# @characterxyz/widget 中文文档

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

版本：0\.10\.1
npm 元数据更新时间：2026-11-06T11:20:27.720Z
中文译文更新时间：2026-11-09T10:41:32.792Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.1 MB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-10-12T05:25:08.459Z
- 最新版本发布：2026-11-06T11:20:27.339Z
- 近 30 天下载量：3064（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 17 个）

## 中文简介

任意站点中的字符 XYZ:角落中的有聊天和语音通话的代理. 一个脚本标签,或者一个Web组件.

## 安装

```sh
npm install @characterxyz/widget
```

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

## README

# @ characterxyz/ 部件

将您的字符 XYZ 代理放在任何网站: 角落中的字符, 流出的文本聊天, 和实时的语音通话 与公平排队 当每行忙。 阴影中的一个网络组件 DOM,所以它在简单的HTML, React, Vue, Svelte, Angular 或其他什么方面都有效, 没有任何你 页面的 CSS 漏出进出。 34 KB gzipped, 包括一切; 一旦页面闲置, 便开始 .

创建可公布的密钥, 选择它可能运行的站点并选择查看 **字符 XYZ QQ 设置 QQ 开发者**。 。 。 .

## 脚本标记( 无构建步骤)

```html
<script src="https://unpkg.com/@characterxyz/widget@0/dist/cx.js" data-key="cxyz_pk_live_…" async></script>
```

标签上的设置如下: `data-*` 属性 : `data-display="full"`, (中文(简体) ), `data-accent="#e11d48"`, (中文(简体) ), `data-position="bottom-left"`, (中文(简体) ), `data-mode="dark"`, (中文(简体) ), `data-show-call="false"`, (中文(简体) ), `data-agent="agent_…"`。 。 。 . 从自己的按钮驱动它 `CharacterXYZ.open('chat')` 或者说 `CharacterXYZ.open('call')`。 。 。 .

## 绑定页面

```js
// Who this is / what is true now. Stays in scope for every later turn.
CharacterXYZ.identify({ id: 'u_42', name: 'Asha', traits: { plan: 'pro' } });
CharacterXYZ.setContext({ page: '/pricing', cart: { items: 2 } });

// Something they did. Only names the agent's graph declares.
CharacterXYZ.track('pricing_viewed', { plan: 'pro' });

// Something the agent may ask the page to do.
CharacterXYZ.registerAction('openCart', async ({ itemId }) => { cart.open(itemId); return { opened: true }; });
```

`track` 是火与忘却`void`),发出"一能"id,活下来a 导航点击. 等待的页面动作会运行您的处理器并公布结果 同一请求; 代理答复随附。 图表节点是 **打开 站点活动** 财务报告和审定财务报表 **客户端动作**。 。 。 .

## 无

```bash
npm install @characterxyz/widget
```

```ts
import { mount } from '@characterxyz/widget';

const widget = mount({ publishableKey: 'cxyz_pk_live_…', accent: '#e11d48' });
widget.open('chat'); // or 'call'; widget.close(); widget.destroy()
```

使用反应还是Next.js? 安装 [`@characterxyz/react`](https://www.npmjs.com/package/@characterxyz/react) 相反;它包括这个软件包.

## 设置

默认来自密钥( 设置在 Embed 页面上) ; 这里通过的任何内容都会覆盖它们 .

| 设置 | 数值 |
| --- | --- |
| `agentId` | 哪个钥匙的经纪人? 默认: 密钥的第一个 |
| `display` | `bubble` • 妇女 `half` • 妇女 `full` (多少她的节目) |
| `launcher`, (中文(简体) ), `position` | 发射器样式; `bottom-right` • 妇女 `bottom-left` |
| `accent`, (中文(简体) ), `mode`, (中文(简体) ), `radius`, (中文(简体) ), `font` | 颜色, `auto` • 妇女 `light` • 妇女 `dark`,角半径,字体家族 |
| `showChat`, (中文(简体) ), `showCall`, (中文(简体) ), `branding` | 关闭聊天、电话或页脚 |
| `offsetX`, (中文(简体) ), `offsetY`, (中文(简体) ), `zIndex`, (中文(简体) ), `container` | 安置情况 |
| `movable` | 游客可以沿着底部的任何一带拖住她(先按住接头);放高一点,她会倒下. 然后从她所处的位置开始聊天 默认关闭 |

代理商所说的(人物,知识,问候)是代理商自己的,设定在字符XYZ.

## 样式

元素上的 CSS 符号 : `character-xyz { --cx-accent: …; --cx-font: …; --cx-radius: … }`组件 : `::part(launcher | presence | actions | panel | header | composer | banner | message | message-agent | message-visitor | message-event | event | greeting)`。 。 。 .

## 活动

元素起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起 `cx-ready`, (中文(简体) ), `cx-open`, (中文(简体) ), `cx-close`, (中文(简体) ), `cx-call` (单位:千美元)`{phase, position, endReason}`和 `cx-error`。 。 。 .

## 已注册访问者

将服务器上的会话擦除 [`@characterxyz/server`](https://www.npmjs.com/package/@characterxyz/server), (中文(简体) ), 然后: `mount({ getSessionToken: () => fetch('/api/characterxyz/session').then((r) => r.json()) })`。 。 。 . 然后他们的聊天历史跟随他们穿越设备.

## 警卫

可公布的密钥( E)`cxyz_pk_…`)按设计是公开的:它只从它上开列的地点工作,而且 交换15分钟的会话,然后去那个地点 永远不要放出密钥( N)`cxyz_sk_…`在一页中; sDK拒绝与一个运行.

## 许可证

麻省理工学院

## 常见问题

### @characterxyz/widget 是什么？

任意站点中的字符 XYZ:角落中的有聊天和语音通话的代理\. 一个脚本标签,或者一个Web组件\.

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

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

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

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

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

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

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

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

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

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

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

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