# @arantic/bugpin-widget 中文文档

规范地址：https://npmcn.com/package/%40arantic/bugpin-widget/

版本：1\.1\.5
npm 元数据更新时间：2026-10-24T12:50:14.886Z
中文译文更新时间：2026-11-06T14:04:02.614Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.7 MB，50 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：8 个
- 首次发布：2026-01-02T17:20:04.878Z
- 最新版本发布：2026-10-24T12:50:14.640Z
- 近 30 天下载量：3065（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

可嵌入可视化的错误报告部件 - 抓取截图、注释问题并提交错误报告

## 安装

```sh
npm install @arantic/bugpin-widget
```

也可以使用：`pnpm add @arantic/bugpin-widget`、`yarn add @arantic/bugpin-widget`、`bun add @arantic/bugpin-widget`

## README

# BugPin 部件

可嵌入可视化错误报告网络应用程序的部件 。 抓取截图,注释问题,并易地提交错误报告.

## 特征

-   **截图抓取** - 全页或可见区域
-   **注释工具** - 绘制、突出显示、模糊并添加文字
-   **隐私第一** - 自动托管,您的数据留在您的服务器上
-   **可自定义** - 配合你的品牌颜色和风格
-   **轻巧** - 小于175KB克齐普
-   **黑暗模式** - 自动主题检测
-   **响应** - 所有设备的工程
-   **多语言** - 翻译成8种语文(英文、德文、法文、荷兰文、西班牙文、意大利文、日文、简化中文),自动检测来自 `<html lang>` 或访问者的浏览器
-   **框架不可知论** - 与React、Vue、Angular、Svelte、.NET等合作

## 安装

```bash
npm install @arantic/bugpin-widget
```

## 使用量

```javascript
import BugPin from '@arantic/bugpin-widget';

BugPin.init({
  apiKey: 'your-project-api-key',
  serverUrl: 'https://your-bugpin-server.com',
});
```

从1.1.3版本开始, `BugPin.init()` 向配置的 BugPin 报告软件包版本 服务器可以让管理员看到兼容性警告。 托管 `/widget.js` 整合没有 发送软件包元数据.

## 配置

该部件根据您的 API 密钥自动从 BugPin 服务器获取配置 。 所有视觉设置(主题,位置,颜色,按钮文本)均由BugPin Admin Console管理.

### 需要的选项

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `apiKey` | `string` | 您的工程 API 密钥( 来自 BugPin 管理员) |
| `serverUrl` | `string` | 您的 BugPin 服务器 URL |

### 选项

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `language` | `string` | BCP 47语言代码(例如. `en`, (中文(简体) ), `de`, (中文(简体) ), `fr`, (中文(简体) ), `nl`, (中文(简体) ), `es`, (中文(简体) ), `it`, (中文(简体) ), `ja`, (中文(简体) ), `zh`) (中文(简体) ). 覆盖自动检测和项目默认. |
| `reporterName` | `string` | 预填可编辑的记者名称字段. |
| `reporterEmail` | `string` | 预填可编辑的报员电子邮件字段. |

### 预填报器细节

```javascript
BugPin.init({
  apiKey: 'your-project-api-key',
  serverUrl: 'https://your-bugpin-server.com',
  reporterName: currentUser.name,
  reporterEmail: currentUser.email,
});
```

用于自动脚本标签初始化 :

```html
<script
  src="https://your-bugpin-server.com/widget.js"
  data-api-key="your-project-api-key"
  data-reporter-name="{{ currentUser.name }}"
  data-reporter-email="{{ currentUser.email }}"
></script>
```

记者在提交前仍然可以编辑这两个字段.

## 隐私和诊断捕捉

服务器控制部件可能收集的诊断分类 。 欧盟隐私模式禁用 每个项目的用户活动线索,没有项目覆盖。 当欧盟隐私模式关闭时, 除非项目禁用,否则活动线索将自动可用。 控制台输出, 网络失败,存储键名称仍然是独立的项目控制;存储键捕获是 默认关闭.

活动线索记录了与按钮、链接、输入、选择、, 复选框,以及类似的控件。 它不记录按键或键入值 。 普通个人 数据和符号图案在进入内元缓冲器前被编辑.

标记嵌入式网站的敏感部分 `data-bugpin-private`。BugPin 忽略活动 在标记的元素及其所有后代中:

```html
<section data-bugpin-private>
  <!-- Account, payment, health, or other sensitive UI -->
</section>
```

活动始终是页面内存,直到报告提交或得到清理。 当欧盟隐私 模式或项目活动设置禁用抓取, 部件不安装活动 听者并清除活动缓冲.

诊断捕捉是失败关闭和服务器控制的:

-   控制台和网络抓取仅在部件配置完成后开始 。 错误 在部件初始化未抓取之前发生 。 如果配置请求失败, 所有 诊断捕捉在会话中仍然被禁用.
-   抓取旗帜不能被当地人覆盖 `BugPin.init()` 选项; 它们总是 从服务器配置中解析此实例, 项目隐私设置优先 .

## 语言

载有英文、德文、法文、荷兰文、西班牙文、意大利文、日文和简化中文译文的部件船.

默认情况下,活动语言按此顺序解决:

1.  `language` 转至 `BugPin.init()`
2.  `data-language` 脚本标签上的属性(通过 `<script>`(中文(简体) )
3.  这个 `lang` 属性 `<html>` (部件监视更改和重递)
4.  访问者浏览器语言
5.  项目的默认语言( 在管理控制台中配置)

```javascript
BugPin.init({
  apiKey: 'your-project-api-key',
  serverUrl: 'https://your-bugpin-server.com',
  language: 'de',
});
```

在运行时切换语言, 例如当您的应用程序的地盘改变时 :

```javascript
BugPin.setLanguage('fr'); // returns the resolved locale, or null if unsupported
BugPin.getLanguage(); // returns the currently active locale
```

## 框架实例

### 反应 / Vite

```jsx
import { useEffect } from 'react';
import BugPin from '@arantic/bugpin-widget';

function App() {
  useEffect(() => {
    BugPin.init({
      apiKey: import.meta.env.VITE_BUGPIN_API_KEY,
      serverUrl: import.meta.env.VITE_BUGPIN_SERVER_URL,
    });
  }, []);

  return <div>Your app</div>;
}
```

### 下一个.js

```jsx
import { useEffect } from 'react';
import BugPin from '@arantic/bugpin-widget';

function App() {
  useEffect(() => {
    BugPin.init({
      apiKey: process.env.NEXT_PUBLIC_BUGPIN_API_KEY,
      serverUrl: process.env.NEXT_PUBLIC_BUGPIN_SERVER_URL,
    });
  }, []);

  return <div>Your app</div>;
}
```

### Vue / 坚果

```vue
<script setup>
import { onMounted } from 'vue';
import BugPin from '@arantic/bugpin-widget';

onMounted(() => {
  BugPin.init({
    apiKey: import.meta.env.VITE_BUGPIN_API_KEY,
    serverUrl: import.meta.env.VITE_BUGPIN_SERVER_URL,
  });
});
</script>
```

### 角质

```typescript
// app.component.ts
import { Component, OnInit } from '@angular/core';
import BugPin from '@arantic/bugpin-widget';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent implements OnInit {
  ngOnInit() {
    BugPin.init({
      apiKey: environment.bugpinApiKey,
      serverUrl: environment.bugpinServerUrl,
    });
  }
}
```

### 类型脚本 / Vanilla Java 脚本

```typescript
import BugPin from '@arantic/bugpin-widget';

// Initialize when DOM is ready
document.addEventListener('DOMContentLoaded', () => {
  BugPin.init({
    apiKey: 'your-api-key',
    serverUrl: 'https://bugpin.example.com',
  });
});
```

### .NET / 布拉佐尔

```csharp
// Services/BugPinService.cs
public class BugPinService
{
    private readonly IJSRuntime _js;

    public BugPinService(IJSRuntime js) => _js = js;

    public async Task InitializeAsync(string apiKey, string serverUrl)
    {
        await _js.InvokeVoidAsync("eval",
            $"import('@arantic/bugpin-widget').then(m => m.default.init({{apiKey: '{apiKey}', serverUrl: '{serverUrl}'}}))");
    }
}
```

```csharp
// Program.cs or Startup.cs
builder.Services.AddScoped<BugPinService>();
```

```razor
@inject BugPinService BugPin
@inject IConfiguration Config

@code {
    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            await BugPin.InitializeAsync(
                Config["BugPin:ApiKey"],
                Config["BugPin:ServerUrl"]
            );
        }
    }
}
```

## 环境变量

将您的 API 密钥存储在环境变量中( 使用参见以上框架示例 ) :

```bash
# Vite (React, Vue) - .env
VITE_BUGPIN_API_KEY=your-api-key
VITE_BUGPIN_SERVER_URL=https://bugpin.example.com

# Next.js - .env.local
NEXT_PUBLIC_BUGPIN_API_KEY=your-api-key
NEXT_PUBLIC_BUGPIN_SERVER_URL=https://bugpin.example.com

# .NET (appsettings.json)
{
  "BugPin": {
    "ApiKey": "your-project-api-key",
    "ServerUrl": "https://bugpin.example.com"
  }
}
```

## 获取您的 API 密钥

您需要您 BugPin 服务器的 API 密钥来初始化部件 .

1.  在您的基础设施上部署 BugPin 服务器( 例如使用 [夹克](https://docs.bugpin.io/installation/docker)(中文(简体) )
2.  登录到 BugPin 管理控制台
3.  打开 **项目**,创建新项目或选择现有项目
4.  复制 API 密钥( 在工程卡中或 **工程设置**(中文(简体) )

## 文档

完整文件,访问: [BugPin 文档](https://docs.bugpin.io/)

## 许可证

麻省理工学院

## 支助

-   [文档](https://docs.bugpin.io/)
-   [报告问题](https://github.com/bugpin/bugpin/issues)
-   [讨论情况](https://github.com/bugpin/bugpin/discussions)

## 常见问题

### @arantic/bugpin-widget 是什么？

可嵌入可视化的错误报告部件 - 抓取截图、注释问题并提交错误报告

### 如何安装 @arantic/bugpin-widget？

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

### @arantic/bugpin-widget 支持 TypeScript 吗？

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

### @arantic/bugpin-widget 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @arantic/bugpin-widget 可以商用吗？

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

### @arantic/bugpin-widget 的下载量有多少？

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

### @arantic/bugpin-widget 还在维护吗？

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