# @fasterfixes/widget 中文文档

规范地址：https://npmcn.com/package/%40fasterfixes/widget/

版本：1\.4\.0
npm 元数据更新时间：2026-11-12T11:59:16.943Z
中文译文更新时间：2026-11-14T11:02:11.468Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40fasterfixes/widget
原文对照：https://npmcn.com/package/%40fasterfixes/widget/?lang=original
项目主页：https://faster-fixes.com/
源码仓库：https://github.com/manucoffin/faster-fixes

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

- 包体积（解压后）：279 kB，16 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：4 个
- 首次发布：2026-09-26T16:37:48.656Z
- 最新版本发布：2026-11-12T11:59:16.590Z
- 近 30 天下载量：7006（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

任何网站的快取反馈部件, 不需要框架 。 审查者对元素进行注释并提交视觉反馈.

## 安装

```sh
npm install @fasterfixes/widget
```

也可以使用：`pnpm add @fasterfixes/widget`、`yarn add @fasterfixes/widget`、`bun add @fasterfixes/widget`

## README

# @ fasterfixes/ widget (帮助)

> **[文档](https://faster-fixes.com/docs/widget/install/script-embed)** • 妇女 [网站](https://faster-fixes.com/)

这个 [更快的图像](https://faster-fixes.com/) 任何网站的反馈部件,不需要框架。 审查者在页面中注释元素,并向您的项目提交可视反馈. 它工作于WordPress,Webflow,静态HTML和任何框架所构建的应用程序. React, Vue, Angular 和 Svelte 应用程序也可以使用 [`@fasterfixes/react`](https://www.npmjs.com/package/@fasterfixes/react), (中文(简体) ), [`@fasterfixes/vue`](https://www.npmjs.com/package/@fasterfixes/vue), (中文(简体) ), [`@fasterfixes/angular`](https://www.npmjs.com/package/@fasterfixes/angular) 财务报告和审定财务报表 [`@fasterfixes/svelte`](https://www.npmjs.com/package/@fasterfixes/svelte)。 。 。 .

元件船没有框架运行时间,在开放的Shadow DOM内制造出,所以你的站点CSS并不影响它.

## 脚本标签

粘贴一个标记到您的站点, 用您的站点替换工程 ID :

```html
<script
  src="https://cdn.jsdelivr.net/npm/@fasterfixes/widget@1/dist/widget.iife.js"
  data-project-id="proj_your_project_id"
  defer
></script>
```

标签在 `<head>` 与 `defer`,在 `<body>`,或在该页面已加载后注入。 这个 `@1` channel服务每1.x放出一次:在不编辑片段的情况下修正到达,在新的主要版本下只进行破解更改.

### 属性

| 属性 | 需求 | 说明 |
| --- | --- | --- |
| `data-project-id` | 对 | 你的项目ID。 没有它,脚本会加载但不会初始化部件. |
| `data-api-origin` | 没有 | 快速Fixes API的出处. 默认为 `https://www.faster-fixes.com`。 。 。 . |
| `data-color` | 没有 | 赤色相为相. 接受任何 CSS 颜色值。 默认为 `#02527E`。 。 。 . |
| `data-position` | 没有 | 浮动按钮位置 。 默认为 `bottom-right`。 。 。 . |
| `data-capture-diagnostics` | 没有 | 设定为 `"false"` 以禁用诊断道。 默认启用 . |
| `data-capture-recording` | 没有 | 设定为 `"false"` 以禁用记录。 默认启用 . |

`labels` 无法通过属性设置 。 要设置它们,或通过完整的选项对象,请参见下方的"手册"初始化.

### 手动初始化

别管了 `data-project-id` 在不挂载部件的情况下装入脚本,然后调用 `window.FasterFixes.init` 自己,例如从一个框架的挂钩:

```html
<script src="https://cdn.jsdelivr.net/npm/@fasterfixes/widget@1/dist/widget.iife.js"></script>
<script>
  window.FasterFixes.init({
    projectId: "proj_your_project_id",
    labels: { submitButton: "Send" },
  });
</script>
```

通话 `init` 当一个部件被挂载时, 首先会破坏上一个实例, 因此部件永远不会挂载两次 。 初始化后, `window.FasterFixes.instance` 持有当前实例.

## 无

用捆绑器安装软件包并导入 `init`包件装入带有类型Script的无害环境管理条目.

```bash
npm install @fasterfixes/widget
```

```ts
import { init } from "@fasterfixes/widget";

const widget = init({ projectId: "proj_your_project_id" });
```

`window.FasterFixes` 仅由脚本标记定义.

## 可见度

部件只为审查者挂载:必须有一个审查者符号(来自 `ff_token` URL参数,然后是本地存储)和工程必须启用部件. 公众访问者看不到任何东西,任何配置请求都会在没有符号的情况下发出.

## 选项

`init` 接受一个选项对象 :

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `projectId` | `string` | 所需经费 | 你的项目公开身份证, `proj_...`。 。 。 . |
| `apiOrigin` | `string` | `https://www.faster-fixes.com` | 快速Fixes API的出处. |
| `color` | `string` | `#02527E` | 赤色相为相. |
| `position` | `WidgetPosition` | `bottom-right` | 一个 `bottom-right`, (中文(简体) ), `bottom-left`, (中文(简体) ), `top-right`, (中文(简体) ), `top-left`, (中文(简体) ), `middle-right`, (中文(简体) ), `middle-left`。 。 。 . |
| `labels` | `Partial<Labels>` | 英语默认值 | 替换任何可见或已宣布的字符串。 Oconduct 密钥保存它们的默认值 . |
| `captureDiagnostics` | `boolean` | `true` | 记录控制台和网络历史 导致一个报告. |
| `captureRecording` | `boolean` | `true` | 将最后一分记录在页面上,每回反馈一次。 见 [记录](https://faster-fixes.com/docs/widget/recording)。 。 。 . |
| `customMetadata` | `CustomMetadata | (() => CustomMetadata)` | 无 | 随每一份反馈发送的密钥/值对 。 见下文. |

一个未知 `position`页:1 `projectId` 这不是一个非空字符串, a `labels` 非对象或对象的值 `customMetadata` 既非对象又非函数的值会阻止部件的上架。 开发建立日志 .

`customMetadata` 显示在您的团队,在代理 API 和镜像的问题, 从来没有给审查者。 通过一个对象, 或每个提交时调用的同步函数, 这样一个值, 如签名的用户 ID 保持当前 。 值是字符串、数字、布尔或 `null`。最多保存50个密钥,密钥被缩短为40个字符,值被缩短为500个,开发时会发出控制台警告。 一个从不屏蔽提交文件的函数:反馈在没有自定义元数据的情况下发送。 它是否发送 `captureDiagnostics` 或者说 `captureRecording` 开始.

## 实例

`init` 返回 a `Widget`其成员与 `useFeedback` 钩子 `@fasterfixes/react`,则 `useFeedback` 混凝土 `@fasterfixes/vue`, (中文(简体) ), `injectFeedback` 联 合 国 `@fasterfixes/angular` 财务报告和审定财务报表 `getFeedback` 联 合 国 `@fasterfixes/svelte`数字 :

| 成员 | 说明 |
| --- | --- |
| `show()` | 后显示部件 `hide()`。 。 。 . |
| `hide()` | 从页面中删除部件直至 `show()`。 。 。 . |
| `isVisible` | `true` 当部件在页面上. |
| `startAnnotation()` | 显示部件并进入注释模式. |
| `feedbackItems` | 项目的反馈项目迄今已装入. |
| `togglePins()` | 隐藏或显示页面上的每一针. |
| `showPins` | `true` 并显示指针. |
| `subscribe(listener)` | 电话 `listener` 之后 `isVisible`, (中文(简体) ), `feedbackItems` 或者说 `showPins` 变化。 返回删除听众的函数. |
| `destroy()` | 删除部件、 停止诊断拖拉并恢复 `console` 财务报告和审定财务报表 `fetch`。 。 。 . |

```html
<button type="button" onclick="window.FasterFixes.instance?.startAnnotation()">
  Report an issue
</button>
```

`subscribe` 让你自己的UI在没有投票的情况下跟随Widget州. 听者不接受参数:读取实例中的值. `destroy()` 删除每个听众.

```js
const widget = init({ projectId: "proj_your_project_id" });
const unsubscribe = widget.subscribe(() => {
  counter.textContent = String(widget.feedbackItems.length);
});
```

## 标签

屏幕阅读器显示或宣布的每个字符串来自 `labels`。通过部分覆盖;省略的密钥保留其英语默认值. `pinAriaLabel` 是接收反馈注释摘录的函数 :

```js
window.FasterFixes.init({
  projectId: "proj_your_project_id",
  labels: {
    submitButton: "Envoyer",
    cancelButton: "Annuler",
    textareaPlaceholder: "Décrivez le problème...",
    pinAriaLabel: (comment) => `Retour : ${comment}`,
  },
});
```

密钥和默认值的完整列表在 [自定义文件](https://faster-fixes.com/docs/widget/customization#labels)。 。 。 .

## 他们

主题 CSS 自定义属性的部件 `[data-ff-widget]` 主机 :

```css
[data-ff-widget] {
  --ff-background: #ffffff;
  --ff-foreground: #18181b;
}
```

| 财产 | 默认 |
| --- | --- |
| `--ff-accent` | 页:1 `color` 选项 |
| `--ff-background` | `#1c1c1c` |
| `--ff-foreground` | `#e4e4e7` |
| `--ff-radius` | `8px` |
| `--ff-font-family` | `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif` |
| `--ff-z-index` | `2147483647` |

`--ff-accent` 设置从 `color` 选项,所以倾向于 `color` 来改变它。 接触更深的元素 `::part()`数字 : `button`, (中文(简体) ), `overlay`, (中文(简体) ), `popover`, (中文(简体) ), `textarea`, (中文(简体) ), `pin`, (中文(简体) ), `list` 财务报告和审定财务报表 `list-item`。 。 。 .

```css
[data-ff-widget]::part(button) {
  box-shadow: none;
}
```

## 许可证

麻省理工学院

## 常见问题

### @fasterfixes/widget 是什么？

任何网站的快取反馈部件, 不需要框架 。 审查者对元素进行注释并提交视觉反馈\.

### 如何安装 @fasterfixes/widget？

在项目目录运行 npm install @fasterfixes/widget，或使用 pnpm add / yarn add / bun add。

### @fasterfixes/widget 支持 TypeScript 吗？

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

### @fasterfixes/widget 支持 ESM 还是 CommonJS？

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

### @fasterfixes/widget 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @fasterfixes/widget 可以商用吗？

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

### @fasterfixes/widget 的下载量有多少？

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

### @fasterfixes/widget 还在维护吗？

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