Feedback Widget 编程式 API

除了带有浮动按钮的可视化界面外，您还可以完全通过代码控制小部件。这让您能够从自有按钮打开表单、在没有可视化界面的情况下提交反馈，或对小部件事件作出响应。

useFeedbackWidget Hook（React）

@almirant/feedback-react 软件包包含一个 Hook，可完全访问小部件 API。

import { useFeedbackWidget } from '@almirant/feedback-react';

function MyComponent() {
  const {
    open,       // 打开表单
    close,      // 关闭表单
    submit,     // 以编程方式提交反馈
    isReady,    // 小部件初始化后为 true
    isOpen,     // 表单可见时为 true
    error,      // 最近一次错误或 null
  } = useFeedbackWidget();

  return (
    <button onClick={open}>
      提交反馈
    </button>
  );
}

重要提示

useFeedbackWidget Hook 要求在组件树中的某处挂载 <FeedbackWidget> 组件。如果没有挂载小部件，该 Hook 会返回无操作函数，且 isReady 将为 false。

Hook 属性

属性	类型	描述
open()	() => void	打开反馈表单
close()	() => void	关闭表单
submit(data)	(data: FeedbackData) => Promise<void>	以编程方式提交反馈
isReady	boolean	小部件完全初始化后为 true
isOpen	boolean	表单可见时为 true
error	string | null	最近一次错误消息；如果没有错误，则为 null

示例：自定义按钮

隐藏默认浮动按钮并使用您自己的按钮：

import { FeedbackWidget, useFeedbackWidget } from '@almirant/feedback-react';

function FeedbackButton() {
  const { open, isReady } = useFeedbackWidget();

  return (
    <button
      onClick={open}
      disabled={!isReady}
      className="my-feedback-button"
    >
      留下反馈
    </button>
  );
}

function App() {
  return (
    <>
      <nav>
        <FeedbackButton />
      </nav>

      <FeedbackWidget
        publicKey="pk_your_public_key"
        showTriggerLabel={false}
      />
    </>
  );
}

示例：以编程方式提交反馈

无需显示可视化表单即可提交反馈。适合收集上下文反馈（完成操作后、关闭模态框时等）。

import { useFeedbackWidget } from '@almirant/feedback-react';

function PostPurchaseFeedback() {
  const { submit, error } = useFeedbackWidget();

  const handleRating = async (rating: number) => {
    await submit({
      message: `购买后评分：${rating}/5`,
      metadata: {
        type: 'rating',
        rating,
        orderId: 'order_123',
      },
    });
  };

  return (
    <div>
      <p>您的购买体验如何？</p>
      {[1, 2, 3, 4, 5].map((n) => (
        <button key={n} onClick={() => handleRating(n)}>
          {n}
        </button>
      ))}
      {error && <p className="error">{error}</p>}
    </div>
  );
}

FeedbackData 类型

interface FeedbackData {
  message: string;            // 反馈文本（必填）
  category?: string;          // 类别：'bug'、'feature'、'improvement'、'other'
  metadata?: Record<string, unknown>;  // 附加数据
}

全局 API（JavaScript）

使用脚本标签时，API 可通过全局 FeedbackWidget 对象访问。

方法

// 打开表单
FeedbackWidget.open();

// 关闭表单
FeedbackWidget.close();

// 在没有可视化界面的情况下提交反馈
FeedbackWidget.submit({
  message: 'Safari 中的支付按钮没有响应',
  category: 'bug',
  metadata: {
    browser: navigator.userAgent,
    page: window.location.href,
  },
});

// 检查小部件是否就绪
if (FeedbackWidget.isReady()) {
  FeedbackWidget.open();
}

方法参考

方法	参数	返回值	描述
init(options)	WidgetOptions	void	使用给定配置初始化小部件
open()	--	void	打开表单
close()	--	void	关闭表单
submit(data)	FeedbackData	Promise<void>	以编程方式提交反馈
isReady()	--	boolean	如果小部件已初始化，则返回 true
isOpen()	--	boolean	如果表单可见，则返回 true
destroy()	--	void	从 DOM 中移除小部件并释放资源

事件和回调

您可以订阅小部件事件，以响应用户操作。

脚本标签

FeedbackWidget.init({
  publicKey: 'pk_your_public_key',
  onOpen: () => {
    console.log('表单已打开');
  },
  onClose: () => {
    console.log('表单已关闭');
  },
  onSubmit: (data) => {
    console.log('反馈已提交：', data.message);
    // 可以发送到您自己的分析系统
    analytics.track('feedback_submitted', {
      category: data.category,
    });
  },
  onError: (error) => {
    console.error('提交反馈时出错：', error);
  },
});

React

<FeedbackWidget
  publicKey="pk_your_public_key"
  onOpen={() => console.log('已打开')}
  onClose={() => console.log('已关闭')}
  onSubmit={(data) => {
    analytics.track('feedback_submitted', {
      category: data.category,
    });
  }}
  onError={(error) => {
    console.error('错误：', error);
  }}
/>

回调列表

回调	参数	触发时机
onOpen	--	表单打开时
onClose	--	表单关闭时
onSubmit	{ message, category, metadata }	成功提交反馈时
onError	{ message: string }	提交时发生错误时

在没有可视化界面的情况下提交反馈

如果不需要可视化表单，并且想构建自己的 UI，可以只使用 submit 函数：

JavaScript

// 初始化时不显示按钮
FeedbackWidget.init({
  publicKey: 'pk_your_public_key',
  // 直接使用 submit 时不会显示浮动按钮
});

// 您的自定义表单
document.getElementById('my-form').addEventListener('submit', async (e) => {
  e.preventDefault();
  const message = document.getElementById('message').value;

  try {
    await FeedbackWidget.submit({
      message: message,
      category: 'feature',
      metadata: {
        source: 'custom-form',
        page: window.location.pathname,
      },
    });
    alert('反馈已提交');
  } catch (error) {
    alert('提交时出错：' + error.message);
  }
});

React

import { FeedbackWidget, useFeedbackWidget } from '@almirant/feedback-react';

function CustomFeedbackForm() {
  const { submit, error } = useFeedbackWidget();
  const [message, setMessage] = useState('');
  const [sending, setSending] = useState(false);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setSending(true);

    try {
      await submit({
        message,
        category: 'feature',
        metadata: { source: 'custom-form' },
      });
      setMessage('');
    } finally {
      setSending(false);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <textarea
        value={message}
        onChange={(e) => setMessage(e.target.value)}
        placeholder="您的反馈..."
        required
      />
      <button type="submit" disabled={sending}>
        {sending ? '正在提交...' : '提交'}
      </button>
      {error && <p className="error">{error}</p>}
    </form>
  );
}

// 请勿忘记挂载小部件（可以将其隐藏）
function App() {
  return (
    <>
      <CustomFeedbackForm />
      <FeedbackWidget publicKey="pk_your_public_key" />
    </>
  );
}

提示

即使构建自己的界面，也需要使用 FeedbackWidget.init() 初始化小部件或挂载 <FeedbackWidget>，才能让 submit 函数访问 Almirant API。小部件会处理身份验证和提交。

销毁小部件

如果需要完全移除小部件（例如，在 SPA 中导航到其他部分时）：

// JavaScript
FeedbackWidget.destroy();

在 React 中，卸载 <FeedbackWidget> 组件时，小部件会自动销毁。