# @desource/context7-widget 中文文档
规范地址：https://npmcn.com/package/%40desource/context7-widget/
版本：0\.2\.3
npm 元数据更新时间：2026-10-31T16:12:21.272Z
中文译文更新时间：2026-11-12T01:40:37.234Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40desource/context7-widget
原文对照：https://npmcn.com/package/%40desource/context7-widget/?lang=original
项目主页：https://github.com/DeSource-Labs/context7-widget/tree/main/packages/core#readme
源码仓库：https://github.com/DeSource-Labs/context7-widget
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：292 kB，53 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-09-09T22:04:34.285Z
- 最新版本发布：2026-10-31T16:12:20.979Z
- 近 30 天下载量：16743（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）
## 中文简介
可自定义的上下文 7 文档聊天部件, 包含 TypeScript 帮助器和 drop- in脚本构建 .
## 安装
```sh
npm install @desource/context7-widget
```
也可以使用：`pnpm add @desource/context7-widget`、`yarn add @desource/context7-widget`、`bun add @desource/context7-widget`
## README
# @ desource/context7-widget (英语)
[](https://www.npmjs.com/package/@desource/context7-widget) [](https://codecov.io/gh/DeSource-Labs/context7-widget) [](https://sonarcloud.io/summary/new_code?id=DeSource-Labs_context7-widget) [](https://context7.com/desource-labs/context7-widget) [](https://deepwiki.com/DeSource-Labs/context7-widget) [](https://github.com/DeSource-Labs/context7-widget/blob/main/LICENSE)
样式上下文 7 文档聊天以适应您的网站, 并带有脚本标记或 TypeScript . 这个麻省理工学院许可的软件包增加了一个精心设计的站点需要的控制: 字体、颜色、间隔、自定义按钮和灵活面板放置.
## 为什么它存在
上下文7提供了其文件部件并免费托管了 AI 答案 。 官员 部件的基本视觉选择为您的设计留下了小空间。 我们造了这个 版本,使助手可以外观并感觉像您产品的一部分.
保留背景7的搜索和AI的答案. 加入你自己的风格,多行问题, 可复制的答案和代码, 停止和重试控件, 以及尊重的滚动 访客在看什么? 现有的部件用户可以通过更改 脚本 URL; 它们的库和允许域设置相接 .
新到背景7吗? 给参观者一个问图书馆的地方 找个例子, 并迈出第一步使用它。 这个项目基于背景7的免费 docs 聊天主动程序,您可以自行制作,也可以免费.
使用自定义元素的根条目和正在安装的助手, `/core` 页:1 自定义聊天接口,或 `/kit` 建立本地框架一体化。 无害环境管理 进口品具有树能变化性,不挂载任何东西 `/widget.js` 开始 自己来.
## 开始前
使用您在背景7上声称的图书馆 。 在其 **管理 – 聊天** 设置, 启用部件, 将您的站点域添加到允许的域并保存 . 替换 `/owner/repo` 以该图书馆的编号为例。 图书馆 仅索引无法在您的网站上聊天 . 见 [背景7 的部件设置](https://context7.com/docs/howto/chat-widget)。 。 。 .
## 安装
```bash
npm install @desource/context7-widget
```
## 浏览器脚本
不需要软件包管理器或构建步骤 :
```html
```
主机文件是一款经典自开机的IIFE. 多个脚本标签是 当页面需要多个独立配置的部件时支持; 给 每个都有一个独特的 `data-widget-id`。 。 。 .
## 挂载部件
```ts
import { mountContext7Widget } from '@desource/context7-widget';
const widget = mountContext7Widget({
library: '/owner/repo',
position: 'center',
preset: 'glass',
theme: 'auto',
backdrop: true,
closeOnOutsideClick: true
});
widget.open();
await widget.send('Show me the recommended setup.');
widget.cancel();
await widget.retry();
widget.reset();
```
`Context7WidgetElement` 曝光情况 `open`, (中文(简体) ), `close`, (中文(简体) ), `toggle`, (中文(简体) ), `send`, (中文(简体) ), `cancel`, (中文(简体) ), `retry`, (中文(简体) ), `reset`, (中文(简体) ), `isOpen`, (中文(简体) ), `isBusy`,以及 `getMessages`。同样的业务是: 可用数据 `widgetId` 结束 `window.Context7Widget`。 。 。 .
进口品是安全的。 要素创建、安装和必要的DOM操作 仍然需要浏览器文档, 并在调用时出现焦点错误时失败 服务器.
## 直接自定义元素
当声明标记更适合您的应用程序时, 登记该元素一次 :
```ts
import { defineContext7Widget } from '@desource/context7-widget';
defineContext7Widget();
```
```html
```
自定义标签名称在不重用同一已注册的构造器的情况下被支持 :
```ts
defineContext7Widget('context7-docs-widget');
```
## 实例
在已有的帮助按钮旁挂起一个锁定的部件 :
```html
```
```ts
import { mountContext7Widget } from '@desource/context7-widget';
const widget = mountContext7Widget({
library: '/owner/repo',
customTrigger: '#docs-help',
position: 'anchor',
preset: 'minimal',
widgetId: 'docs'
});
await widget.send('Show the installation steps.');
```
使用 `position: 'center'` 与 `backdrop: true` 一种模式的帮助流。 使用一个 无角位置 `customTrigger` 为内置起浮发射器. 可运行的框架中性示例 [演示画廊](https://context7.desourcelabs.com/examples)。 。 。 .
## 选项
JavaScript 使用骆驼大小写选项名. 直接自定义元素属性使用 kebab 大小写; 脚本安装这些属性的前缀 `data-`。 。 。 .
| JavaScript 选项 | 自定义元素属性 | 类型/ 默认 |
| --- | --- | --- |
| `library` | `library` | 需要的背景7 库 id |
| `position` | `position` | `bottom-right`还有角落, `center`,或 `anchor` |
| `preset` | `preset` | `default`; 还 `minimal`, (中文(简体) ), `glass`, (中文(简体) ), `neo`, (中文(简体) ), `terminal`, (中文(简体) ), `brutalist` |
| `theme` | `theme` | `auto`; 还 `light` 或者说 `dark` |
| `color` | `color` | 无覆盖; 预设自有重音 |
| `customTrigger` | `custom-trigger` | CSS 选择器, 简单的元素 id, 或 JavaScript 中的元素 |
| `backdrop` | `backdrop` | `true` 页:1 `center`,否则 `false` |
| `closeOnOutsideClick` | `close-on-outside-click` | `true` |
| `defaultOpen` | `default-open` | `false` |
| `initialMessage` | `initial-message` | 内地打招呼; `{library}` 内插 |
| `labels` | 只有财产 | 部分本地化对象与英语默认合并 |
| `launcherLabel` | `launcher-label` | `Ask Docs AI` |
| `launcherVariant` | `launcher-variant` | `icon`; 还 `pill` 或者说 `badge` |
| `linkBaseUrl` | `link-base-url` | 相对链接的基础; 默认为背景7 库页面 |
| `panelHeight` | `panel-height` | 响应样式表默认值 |
| `panelWidth` | `panel-width` | 响应样式表默认值 |
| `placeholder` | `placeholder` | `Ask about the docs...` |
| `title` | `dialog-title` | `Chat with Documentation` |
| `widgetId` | `widget-id` | `default` |
对于脚本标签, `library` 变成 `data-library`, (中文(简体) ), `dialog-title` 变成 `data-title`,其余属性则遵循相同的 `data-*` 模式. 定制元素有意使用 `dialog-title` 而不是当地人 HTML 语言 `title` 属性,避免意外浏览器工具提示.
布尔属性接受诸如 `backdrop="false"` 财务报告和审定财务报表 `close-on-outside-click="false"`他们没有强迫他们 `true`。 。 。 .
对于挂载元素,指定 `widget.labels = { send: 'Enviar', ... }` 改为 将可见和辅助文本本地化,包括属性和缺失图书馆 堕倒. JavaScript 帮助对象接受相同的 `labels` 选项。 脚本标签 `data-*` 数值在连接后仍为活; a 只有在申请时才优先使用语法自定义元素属性 明确作者.
## 生成脚本标记
```ts
import { buildContext7WidgetScriptTag } from '@desource/context7-widget';
const script = buildContext7WidgetScriptTag({
library: '/owner/repo',
customTrigger: '#docs-chat',
position: 'anchor',
preset: 'minimal'
});
```
选择器自定义触发器仅在匹配后隐藏内置启动器 元素绑定。 缺少或延迟交付的选择器保持发射装置可用 并当目标出现时自动绑定.
脚本仍然发送聊天请求到 `https://context7.com`此软件包 不运行上下文7代理;它提供可自定义的客户端层.
## 数据流动
浏览器会发布已配置的库 ID 和当前对话信件 直接转到 `https://context7.com/api/v2/widget/chat`源代码实验室没有 代理聊天内容 。 这个客户端没有添加分析,饼干, 或持续 浏览器存储; 状态保留在活部件的内存和 `reset()` 清除 这个 公众活动向主机应用程序暴露问答,所以 整合者控制任何额外的分析或持久性。 避免发送 机密或敏感个人数据并审查背景7的后端政策 处理和保留.
## 支持的视觉模式
- 职位: `bottom-right`, (中文(简体) ), `bottom-left`, (中文(简体) ), `top-right`, (中文(简体) ), `top-left`, (中文(简体) ), `center`, (中文(简体) ), 财务报告和审定财务报表 `anchor`
- 预设 : `default`, (中文(简体) ), `minimal`, (中文(简体) ), `glass`, (中文(简体) ), `neo`, (中文(简体) ), `terminal`,以及 `brutalist`
- 主题 : `light`, (中文(简体) ), `dark`,以及 `auto`
- 发射装置变体: `icon`, (中文(简体) ), `pill`,以及 `badge`
若为 `color` 中省略,预设自有发射装置和发送按钮颜色。 设定 `color` 只有在你的产品需要品牌控制时.
## 自定义
先选择一个预设,然后覆盖公共符号或部件. 内部 `.c7-*` 课程是私人的,可以在发布之间改变.
### 定型合同
从主机页面中样式自定义元素。 不瞄准内部 `.c7-*` 课程.
```css
context7-widget[widget-id='docs'] {
--c7-accent: #7cffb2;
--c7-accent-contrast: #07120c;
--c7-font-family: Inter, ui-sans-serif, system-ui, sans-serif;
--c7-panel-background: #101513;
--c7-panel-color: #f7f2e8;
--c7-border-color: rgba(247, 242, 232, 0.18);
--c7-panel-radius: 8px;
}
context7-widget::part(send-button) {
min-width: 5rem;
text-transform: uppercase;
}
```
公共变量包括:
- 品牌/类型: `--c7-accent`, (中文(简体) ), `--c7-accent-contrast`, (中文(简体) ), `--c7-font-family`, (中文(简体) ), `--c7-muted-color`, (中文(简体) ), `--c7-focus-ring`
- 面板: `--c7-panel-background`, (中文(简体) ), `--c7-panel-backdrop-filter`, (中文(简体) ), `--c7-panel-color`, (中文(简体) ), `--c7-panel-width`, (中文(简体) ), `--c7-panel-height`, (中文(简体) ), `--c7-panel-radius`, (中文(简体) ), `--c7-panel-shadow`, (中文(简体) ), `--c7-border-color`, (中文(简体) ), `--c7-spacing`, (中文(简体) ), `--c7-z-index`
- 发射器 : `--c7-launcher-background`, (中文(简体) ), `--c7-launcher-color`, (中文(简体) ), `--c7-launcher-gap`, (中文(简体) ), `--c7-launcher-radius`, (中文(简体) ), `--c7-launcher-shadow`, (中文(简体) ), `--c7-launcher-size`
- 后投递 : `--c7-backdrop`, (中文(简体) ), `--c7-backdrop-filter`
- 页眉/页脚 : `--c7-header-background`, (中文(简体) ), `--c7-footer-background`
- 信件数 : `--c7-message-assistant-background`, (中文(简体) ), `--c7-message-assistant-color`, (中文(简体) ), `--c7-message-user-background`, (中文(简体) ), `--c7-message-user-color`, (中文(简体) ), `--c7-message-radius`, (中文(简体) ), `--c7-error-background`, (中文(简体) ), `--c7-error-color`
- 控件 : `--c7-control-background`, (中文(简体) ), `--c7-control-border`, (中文(简体) ), `--c7-control-color`
稳定阴影部分 :
`backdrop`, (中文(简体) ), `panel`, (中文(简体) ), `header`, (中文(简体) ), `title`, (中文(简体) ), `close-button`, (中文(简体) ), `messages`, (中文(简体) ), `message`, (中文(简体) ), `assistant-message`, (中文(简体) ), `user-message`, (中文(简体) ), `error-message`, (中文(简体) ), `typing`, (中文(简体) ), `tool-call`, (中文(简体) ), `tool-toggle`, (中文(简体) ), `code-block`, (中文(简体) ), `composer`, (中文(简体) ), `input`, (中文(简体) ), `send-button`, (中文(简体) ), `footer`, (中文(简体) ), `powered-by`,以及 `launcher`。 。 。 .
## 活动
听这个元素或者在 `document` 级别 :
```ts
import type { Context7WidgetQuestionEventDetail } from '@desource/context7-widget';
document.addEventListener('c7:answer-complete', (event) => {
// `event.detail` is inferred from the event name.
console.log(event.detail.library, event.detail.answer);
});
function trackQuestion(detail: Context7WidgetQuestionEventDetail) {
console.log(detail.question);
}
```
活动 : `c7:ready`, (中文(简体) ), `c7:open`, (中文(简体) ), `c7:close`, (中文(简体) ), `c7:cancel`, (中文(简体) ), `c7:question`, (中文(简体) ), `c7:first-token`, (中文(简体) ), `c7:answer`, (中文(简体) ), `c7:answer-complete`, (中文(简体) ), `c7:tool-call`, (中文(简体) ), `c7:tool-result`,以及 `c7:error`。 。 。 .
答录符到达后取消保留可见的部分助手 信件输入 `getMessages()` 与 `status: 'cancelled'`。 。 。 . `send()` 以 状态结果,例如 `complete`, (中文(简体) ), `cancelled`, (中文(简体) ), `error`, (中文(简体) ), `busy`,或 `empty`。 。 。 . `retry()` 在不重复用户信件的情况下再发送最后一个失败的问题 .
作曲为多行:输入发送并Shift+Enter插入一行新行. 答案和有栅栏的代码块有复制动作. Markdown 逃出原始 HTML, 允许安全 HTTP( S) 和相对链接, 并支持 标题 带有轻亮亮度的栅栏式代码 嵌入式列表 任务, 块、表格和行内格式。 流出文字保留为平原 文本和Markdown 解析被推迟到答案完成后进行,避免 四重工作同时长回放流.
## 无头引擎订阅
`Context7ConversationEngine.subscribe(listener)` 包括每个州的快照 默认。 消耗事件流的框架或自定义渲染器 `subscribe(listener, { includeTransient: false })` 跳过快照 仅通过部分回答或工具框流. 请求启动, 已执行 信件、取消、错误、重置和最后繁忙状态仍在发送; `subscribeEvents` 继续发出每条流事件.
州和活动的听众独立援引。 如果消费代码投出, 错误已被记录,引擎继续请求并引用 其余的听众。 两种订阅方法都返回自定义的未订阅者 召回电话.
## 出口
- `@desource/context7-widget`
- `@desource/context7-widget/core` - 有用的框架中立原始物 自定义体验:引擎,出炉桥,运输,Markdown,布局, 剪贴板和复制操作协调、模式隔离、违约、合同、, 和标签
- `@desource/context7-widget/kit` 独立对话引擎, 制造桥、运输、减值、浮出水计算、合同、, 违约,以及框架软件包的品牌资产
- `@desource/context7-widget/widget.js`
根头, `/core`,以及 `/kit` 仅限无害环境管理并保留内部模块 边框。 因此,下游捆绑者可以省略自定义元素运行时间 当应用程序只导入时 `renderMarkdown` 或者说 `resolveContext7AnchorLayout` 从 `/core`。 。 。 . `/kit` 有意扩大 框架作者表面; 应用程序集成应选择根或 `/core`编辑 `widget.js` 子路径是经典浏览器脚本和故意 有副作用.
自定义元素在实例中共享一个可构造样式表 浏览器支持并返回到内置阴影样式表 否则。 流程化的 DOM 更新被帧绑定,而解答事件依然不变 每个接收块都有可用数据.
该套软件只出版无害环境管理。 它的根头, `/core`,以及 `/kit` 声明是: 为现代节点无害环境管理和TypeScript捆绑器分辨率验证.
## 浏览器、可访问性和安全说明
运行时间目标为ES2020时代带有自定义元素的现代浏览器,打开 阴影DOM, `fetch`, (中文(简体) ), `ReadableStream`,以及 `AbortController`。可构造 样式表在可用时共享; 旧浏览器接收内线 `