Feedback Widget 自定义

该小部件会通过配置选项在视觉上适应您的应用程序。您可以更改颜色、文本、位置和响应式行为。

完整配置选项

选项	类型	默认值	描述
publicKey	string	--（必填）	您项目的公钥
position	string	'bottom-right'	按钮位置：'bottom-right'、'bottom-left'、'top-right'、'top-left'
theme	string	'auto'	视觉主题：'light'、'dark'、'auto'
accentColor	string	'#6366f1'	小部件的主色（按钮、边框和链接）
labels	object	见下文	可自定义的小部件文本
labels.title	string	'提交反馈'	表单标题
labels.placeholder	string	'描述您的想法或问题...'	文本字段占位符
labels.submitButton	string	'提交'	提交按钮文本
labels.successMessage	string	'感谢您的反馈'	成功提交后的消息
labels.triggerButton	string	'反馈'	浮动按钮文本
showTriggerLabel	boolean	true	在浮动按钮图标旁显示文本
zIndex	number	9999	小部件的 CSS z-index
metadata	object	{}	随每条反馈发送的附加数据（用户、页面等）

视觉自定义

强调色

accentColor 定义小部件的主色。它会应用于浮动按钮、焦点边框和提交按钮。

<script>
  FeedbackWidget.init({
    publicKey: 'pk_your_public_key',
    accentColor: '#e11d48',
  });
</script>

在 React 中：

<FeedbackWidget
  publicKey="pk_your_public_key"
  accentColor="#e11d48"
/>

自定义文本

自定义小部件的所有文本，使其符合您的品牌或语言：

<script>
  FeedbackWidget.init({
    publicKey: 'pk_your_public_key',
    labels: {
      title: '告诉我们您的想法',
      placeholder: '在此写下您的建议...',
      submitButton: '提交建议',
      successMessage: '已收到。感谢您帮助我们改进。',
      triggerButton: '建议',
    },
  });
</script>

在 React 中：

<FeedbackWidget
  publicKey="pk_your_public_key"
  labels={{
    title: '告诉我们您的想法',
    placeholder: '在此写下您的建议...',
    submitButton: '提交建议',
    successMessage: '已收到。感谢您帮助我们改进。',
    triggerButton: '建议',
  }}
/>

浮动按钮

控制触发小部件的按钮的外观和位置：

<script>
  FeedbackWidget.init({
    publicKey: 'pk_your_public_key',
    position: 'bottom-left',
    showTriggerLabel: false,    // 仅显示图标，不显示文本
  });
</script>

可用位置：

值	描述
'bottom-right'	右下角（默认值）
'bottom-left'	左下角
'top-right'	右上角
'top-left'	左上角

z-index

如果小部件被界面中的其他元素遮挡，请调整 zIndex：

<script>
  FeedbackWidget.init({
    publicKey: 'pk_your_public_key',
    zIndex: 50000,
  });
</script>

自定义元数据

您可以随每条反馈发送附加数据，以便进行分类。元数据会附加到 Almirant 中的创意条目。

<script>
  FeedbackWidget.init({
    publicKey: 'pk_your_public_key',
    metadata: {
      userId: '12345',
      plan: 'enterprise',
      page: window.location.pathname,
    },
  });
</script>

在 React 中，您可以传入动态元数据：

function App() {
  const { user } = useAuth();

  return (
    <FeedbackWidget
      publicKey="pk_your_public_key"
      metadata={{
        userId: user?.id,
        email: user?.email,
        plan: user?.plan,
        page: window.location.pathname,
      }}
    />
  );
}

提示

请在元数据中至少包含 userId 和当前页面。这让您可以将反馈与特定用户关联，并了解他们从应用程序的哪个部分发送了反馈。

响应式行为

小部件会自动适应不同的屏幕尺寸：

屏幕	行为
桌面端（> 768px）	表单会以浮层形式在浮动按钮旁打开
平板电脑（481px - 768px）	表单会居中打开，并带有半透明遮罩层
移动端（< 480px）	表单会以底部面板形式占满整个宽度

浮动按钮在所有分辨率下都会保持其位置。在移动端，showTriggerLabel 会自动禁用以节省空间。

注意

无需进行任何操作即可使小部件具备响应式能力。它会根据设备视口自动适应。

深色模式

使用 theme: 'auto' 时，小部件会检测操作系统偏好（prefers-color-scheme）并相应适应。

如果您的应用程序有自己的主题切换控件，可以直接进行控制：

function App() {
  const { theme } = useTheme(); // 您的主题 Hook

  return (
    <FeedbackWidget
      publicKey="pk_your_public_key"
      theme={theme} // 'light' 或 'dark'
    />
  );
}

完整示例

<script src="https://cdn.almirant.ai/feedback-widget.iife.js"></script>
<script>
  FeedbackWidget.init({
    publicKey: 'pk_your_public_key',
    position: 'bottom-right',
    theme: 'auto',
    accentColor: '#2563eb',
    showTriggerLabel: true,
    zIndex: 9999,
    labels: {
      title: '您的意见很重要',
      placeholder: '我们可以改进什么？',
      submitButton: '提交',
      successMessage: '感谢您。您的反馈已记录。',
      triggerButton: '反馈',
    },
    metadata: {
      page: window.location.pathname,
      userAgent: navigator.userAgent,
    },
  });
</script>