# @botiverse/hands-feedback-react 中文文档

规范地址：https://npmcn.com/package/%40botiverse/hands-feedback-react/

版本：0\.5\.2
npm 元数据更新时间：2026-10-27T02:53:27.195Z
中文译文更新时间：2026-11-08T12:15:50.859Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40botiverse/hands-feedback-react
原文对照：https://npmcn.com/package/%40botiverse/hands-feedback-react/?lang=original
项目主页：https://github.com/botiverse/hands#readme
源码仓库：https://github.com/botiverse/hands

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：356 kB，36 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：react ^19\.0\.0，react-dom ^19\.0\.0，lucide-react \>=0\.575\.0 \<2\.0\.0，@botiverse/raft-ui \>=0\.20\.0 \<1\.0\.0
- 首次发布：2026-09-29T07:34:52.167Z
- 最新版本发布：2026-10-27T02:53:26.698Z
- 近 30 天下载量：12802（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

嵌入式记者-Facing Hands反馈收件箱组件.

## 安装

```sh
npm install @botiverse/hands-feedback-react
```

也可以使用：`pnpm add @botiverse/hands-feedback-react`、`yarn add @botiverse/hands-feedback-react`、`bun add @botiverse/hands-feedback-react`

## README

# `@botiverse/hands-feedback-react`

记者-面对手的反馈组件. 包裹是一个票箱, 对话细节 回复作曲家 以及使用 Raft 设计的新反馈格式 系统(`@botiverse/raft-ui`,来自botiverse/raft-design). 有一个拉夫特的外观: 旧的 `elegant` 编号 : `brutal` 主题家族已不复存在, 不再在此选择 .

```tsx
import {
  FeedbackProvider,
  FeedbackWorkspace,
  type HandsFeedbackTransport,
} from "@botiverse/hands-feedback-react";
import "@botiverse/raft-ui/styles.css";
import "@botiverse/hands-feedback-react/styles.css";

// Implement this in your app. It calls your authenticated same-origin proxy;
// the complete adapter is in the integration guide linked below.
const transport: HandsFeedbackTransport =
  createMyAppFeedbackTransport("/api/feedback");

<FeedbackProvider
  transport={transport}
  // Optional. Without this override the SDK maps browser `zh*` to `zh-CN`
  // and falls back to English. Pass the host app's selected locale when set.
  locale="en"
  onUnreadChanged={({ total }) => setFeedbackBadge(total)}
>
  <FeedbackWorkspace />
</FeedbackProvider>;
```

工作空间拥有记者交互状态:列表过滤/滚动/焦点 恢复、 平板电脑回复草稿、 IME 安全输入处理、 附加 进步/重试/取消、可检索光标页和近下对白 随后. 东道主不应重复该状态机器。 他们只提供 (可选) 附加打开器.

在移动中, 主机可以将这些工作空间通知绑定为真实的浏览器 URL 并启用软件包的触摸性牵引再现行为:

```tsx
<FeedbackWorkspace
  route={routeFromLocation(location)}
  onRouteChange={(nextRoute, options) =>
    navigate(pathForRoute(nextRoute), { replace: options?.replace })
  }
  enablePullToRefresh={isMobile}
/>
```

`inbox`, (中文(简体) ), `new`,以及 `ticket` 是支持的工作空间路径。 SDK标记 创建-成功过渡 `new` 改为 `ticket` 与 `replace: true`这样 返回不会重新打开已提交的表格 。 拉到再新鲜的只附在 列表和对话框滚动视图端口,仅在滚动上方开始,忽略 可编辑控件,并保留现有内容,而权威数据是 已再装入. 一般情况 `usePullToRefresh` 钩子也导出为其它主机 卷轴表面.

所有可见副本、已关闭错误副本、日期和无障碍标签共享 SDK语言. 支持的地方为: `en` 财务报告和审定财务报表 `zh-CN`; 明示提供者 `locale` 优先于浏览器语言检测.

本地化是由提供者驱动的,而不限于内置捆绑. `messages` 接受打入的部分覆盖( 丢失的密钥返回到 ),包括参数化验证字符串. `formatDate` 财务报告和审定财务报表 `formatFileSize` 让东道主采用自己的格式化公约,而不使用 重建 SDK UI。 浏览器谈判选择第一个支持的条目 `navigator.languages` 命令,然后回到英语.

```tsx
<FeedbackProvider
  transport={transport}
  locale={appLocale}
  messages={{
    newFeedback: t("feedback.new"),
    attachmentUnsupported: t("feedback.attachmentUnsupported"), // `{name}`
  }}
  formatDate={(date, { locale }) => appDateFormatter(date, locale)}
  formatFileSize={(bytes, { locale }) => appFileSizeFormatter(bytes, locale)}
>
  <FeedbackWorkspace />
</FeedbackProvider>
```

## 主机级附件

主机可能会放出一个小文件( 例如一个有效的诊断快照) 进入记者的待补附件。 准备 `File` 首先( 任意同步) 在此点击前获取/ 验证, 然后调用控点 **同步** 从点击处理器中:

```tsx
const workspace = useRef<FeedbackWorkspaceHostHandle>(null);

<button
  onClick={() => {
    // No `await` before this call: it needs the live user gesture.
    const result = workspace.current?.openNewFeedbackWithPendingFile({
      file: preparedDiagnosticFile,
    });
    if (result && !result.ok) showReason(result.reason);
  }}
>
  Report issue with diagnostic
</button>
<FeedbackWorkspace
  ref={workspace}
  onOpenPendingAttachment={({ file }) => previewInHost(file)}
/>
```

-   `openNewFeedbackWithPendingFile({ file })` 打开新反馈表格 同一呼叫中已经待决的文件。 如果表单已经打开了,它 在那里添加文件 。 它是同步的,并返回输入结果 .
-   `attachPendingFile({ file })` 是低等变体: 它只有阶段进入 已经打开的窗体并返回 `composer_closed` 否则.

合同(两种方法):

-   **只有阶段.** 他们从来不上传或屈服。 记者看到文件, 可以打开(通过 `onOpenPendingAttachment`,包括非图像文件), 它可以去除它,它只在他们按下“提交”的时候被发送.
-   **需要用户手势 .** 没有瞬态浏览器用户激活 (单位:千美元)`navigator.userActivation.isActive`他们回来了 `user_activation_required` 并且不改变任何东西,包括路线.
-   **只取字节.** 输入就是 `{ file: File }`没有路径, URL, 调用,或获取背景 .
-   **被包围了.** 最多 `MAX_FEEDBACK_HOST_ATTACHMENTS` (1) 主机文件, `MAX_FEEDBACK_HOST_ATTACHMENT_BYTES` (1个小米B),类型 `FEEDBACK_HOST_ATTACHMENT_TYPES` (截图图像类型加 `application/json` 财务报告和审定财务报表 `text/plain`),它计算对共享 三相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相. 相同的文件( 名称、 类型、 大小、 最后修改) 是 以 `duplicate`。 。 。 .
-   **已打出拒绝,零突变.** 失败者返回 `{ ok: false, reason }` (单位:千美元)`FeedbackHostAttachmentRejection`)并且没有 导航、 更改待决列表、 显示错误横幅或上传 任何东西. `busy` 表示呈文在逃.

手的应用和运输必须接受注入的MIME类型. 双手 公开提交端点接受任何类型。 记者的答复只接受图像, 这就是为什么主机文件只使用新反馈格式.

## 安全边界

-   软件包没有 `appToken`, (中文(简体) ), `clientSecret`, (中文(简体) ), `reporterId`或任意 车主道具.
-   主机运输绑定了短寿命的记者范围会话.
-   手为票证并读/未读状态. `unreadTotal` 来源于Hands的回复;该组件从未产生或持续存在 读取光标.
-   细节要求报告并清除未读内容, 只有在它成功后 反应。 失败, 中止, stale, 和未挂载的读取不会突变未读 .
-   Webhooks 是服务器对服务器的可选集成,不需要用于 输入正确性.

使用 Tailwind v4 的消费者如果 他们的建筑清理图书馆课程:

```css
@source '../node_modules/@botiverse/raft-ui/dist';
@source '../node_modules/@botiverse/hands-feedback-react/dist';
```

在 npm 发布前安装此软件包的源位集成 手单取子目录和 pnpm `path:` git 选择器,然后导入 明确源导出 :

```bash
pnpm add "github:botiverse/hands#<full-commit-sha>&path:packages/feedback-react"
pnpm add react react-dom @botiverse/raft-ui lucide-react
```

```tsx
import {
  FeedbackProvider,
  FeedbackWorkspace,
} from "@botiverse/hands-feedback-react/source";
import "@botiverse/hands-feedback-react/source/styles.css";
```

主机捆绑器必须支持TypeScript/TSX的依赖性. 出版消费者 应使用上述已编译的根导出.

完整的服务器证书,不透明 记者身份,路由绑定,代理, 运输、网络购物和生产核查名单的通过情况 [反应反馈收件箱指南](https://npmcn.com/package/docs/public/feedback-react.md)。 。 。 .

## 常见问题

### @botiverse/hands-feedback-react 是什么？

嵌入式记者-Facing Hands反馈收件箱组件\.

### 如何安装 @botiverse/hands-feedback-react？

在项目目录运行 npm install @botiverse/hands-feedback-react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.0）、react-dom（^19\.0\.0）、lucide-react（\>=0\.575\.0 \<2\.0\.0）、@botiverse/raft-ui（\>=0\.20\.0 \<1\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @botiverse/hands-feedback-react 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @botiverse/hands-feedback-react 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @botiverse/hands-feedback-react 可以商用吗？

@botiverse/hands-feedback-react 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @botiverse/hands-feedback-react 的下载量有多少？

根据 npm 官方下载统计，@botiverse/hands-feedback-react 在 2026/10/09 – 2026/11/07 这 30 天内被下载 12,802 次，日均约 427 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @botiverse/hands-feedback-react 还在维护吗？

最新版本 0\.5\.2 发布于 2026/10/27（12 天前）；至今共发布 9 个版本，其中过去 12 个月发布了 9 个；首次发布于 2026/09/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。