# @chatlychat/widget-element 中文文档

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

版本：0\.27\.2
npm 元数据更新时间：2026-11-05T20:02:58.527Z
中文译文更新时间：2026-11-09T11:48:31.669Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：405 kB，96 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-10-12T16:54:37.720Z
- 最新版本发布：2026-11-05T20:02:58.082Z
- 近 30 天下载量：5064（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：34（近 12 个月 34 个）

## 中文简介

Chartly 聊天部件作为自定义元素 (), 加上嵌入式生命周期框架包装器共享 。 零从属.

## 安装

```sh
npm install @chatlychat/widget-element
```

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

## README

# @ chatlychat/ widget - 元素

作为自定义元素的聊天部件 . **零从属.**

```bash
pnpm add @chatlychat/widget-element
```

```html
<script type="module">
  import '@chatlychat/widget-element/register';
</script>

<chatly-widget public-id="acme-web" api-url="https://api.chatlychat.com"></chatly-widget>
```

在Vue、Svelte、Angular、Lit、Astro、Alpine、htmx和Plain HTML工作—— 在自定义元素工作的地方。 用于反应, 使用 [`@chatlychat/widget-react`](https://npmcn.com/package/%40chatlychat/widget-react),它基于此包 生命周期.

## 为什么不把片段贴上?

如果有的话 `<script>` 在你身边 `<head>` 这是你需要的一切,粘贴 [片断](https://chatlychat.com/guides/channel-web) 并停止阅读。 这个 当部件的寿命被你所左右时 软件包就能保持它 框架拥有 :

-   聊天应该出现在一些路线上,而不是其他路线上,以及您的路由器 卸载元素;
-   主题或访客身份来自组件状态;
-   您的模板绑定属性并倾听事件, 您宁愿 写入 `<chatly-widget :theme="theme" @chatly-ready="…">` 超过伸入 `window`。 。 。 .

它还处理手写集成通常不处理的三件事: 组件卸载时留下的部件, 由 DOM 引起的重起 移动, 和重新初始化, 由重新投降导致.

## 属性

| 属性 | 说明 |
| --- | --- |
| `public-id` | **要求.** 网道公众身份证. |
| `api-url` | 装入器来自主机的默认值 . |
| `realtime-url` | 很少需要;API报告正确的一个. |
| `loader-url` | 何处 `loader.js` 服务从。 很少设置;见下文. |
| `lazy` | 将捆绑拖到访客想要的时候;见下文. |
| `nonce` | 你的页面是CSPnence,如果你服务一个;见下文. |
| `locale` | 应用 `setLocale()` 一旦部件打开. |
| `css-overrides` | CSS注入了部件的阴影根. |
| `inline` | 布尔. 在此元素内挂起聊天 . |
| `theme` | 贾森. |
| `behavior` | 贾森. |
| `visitor` | 贾森. `null` “签署”——见下文. |
| `copy` | 贾森. |
| `copy-by-locale` | 贾森. |
| `quick-links` | 贾森. |

A 类 `visitor` 联 合 国 `null` —— 说 `visitor="null"`,或 `chat.visitor = null` 谓 : "签出",并检查 **挂载** 不只是在改变。 A 类 已签名的加载页面从不会使身份转换到没有 (单位:千美元) `reset()` 因此,前一个账户的外部 id 否则留在 浏览器( 部件保存在 `chatly:xid:<publicId>`在共享设备上 这是最后一个人的身份 比签出另一个标签。 A 类 `visitor` 这仅仅是ABSENT 仍然没有改变任何东西,故意:它不能 除了"身份还没有解决"之外 在每次缓慢的认证检查中都丢下一个直播对话. 忽略当 `identity-endpoint` (或一个 `identity` 已设置 .

属性为活性:更改一并元素应用. 变化 `visitor` 成为 `identify()` 更改 `locale` (单位:千美元) `setLocale()` —— 说 既不重挂部件, 也不更改 `theme` 数值: 是 应用 `setTheme()`,重新绘出一个没有 网络请求. 对其它事物的改变会重新激活它 它会关闭一个 打开面板——只有在一个值真的改变时才会发生.

那个 `theme` 仍然重新初始化的更改是一个 REMOVED 顶级密钥 (或 `undefined`),因为合并不能不应用。 嵌入对象, 如 `darkTheme` 所以把钥匙扔进里面就是直播 一个价值你 已更改了 live, 并删除了它的最后一个值, 直到页面加载 .

### `lazy` - 推迟捆绑

`widget.js` 是~44KB gzipped,每个访客下载到每一页 查看,无论他们是否打开聊天. `lazy` 更改:

```html
<!-- a valueless attribute means "on", as everywhere else in HTML -->
<chatly-widget public-id="acme-web" lazy></chatly-widget>
<chatly-widget public-id="acme-web" lazy="interaction"></chatly-widget>
<chatly-widget public-id="acme-web" lazy="manual"></chatly-widget>
```

| 价值 | 发生了什么事 |
| --- | --- |
| 缺席/ `false` | 捆绑在页面负荷上取回, 一如既往 |
| 当前/ `launcher` | 装入器绘制一个与您的主题相匹配的站入式发射器;使用它取出捆绑并打开面板。 一个回声的捆绑被立即取出 |
| `interaction` | 如上所述,加上游客第一次与网页互动的预热 |
| `manual` | 没有画或取到,直到有电话 `Chatly('load')` —— 说 **回话也没有预装** |

A 类 **回话** 是一个访问者, 此浏览器已经进行交谈 (单位:千美元)`chatly:vr:<publicId>`) (中文(简体) ). 每个模式,但是 `manual` 获取捆绑 它们是加载器评价的,没有点击:无法绘制未读徽章 没有捆绑,所以在他们离开的时候 得到的答复 否则就隐身. `manual` 由你决定.. `Chatly.hasSession()` 同样的测试,和 `loader.js` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}先回答这个问题 捆绑存在 :

```html
<script>
  var a = document.createElement('script');
  a.async = 1;
  a.src = 'https://widget.chatlychat.com/loader.js';
  // AFTER loader.js has evaluated: it is what defines `hasSession`, and the
  // tag is async, so asking any earlier gets `undefined`.
  a.onload = function () {
    if (window.Chatly.hasSession()) window.Chatly('load');
  };
  document.head.appendChild(a);
</script>
```

还有什么.. `lazy="eventually"` 负载 **热心地**这是今天的 行为和安全的方向, 并按名称发出警告。 一个沉默的打字 被禁用的懒惰装入将完全看起来像一个懒惰模式,不起作用.

备用发射装置由这个包裹所绘制. 这是真的 `<button>` 在一个 阴影根, 因此它可以到达键盘, 您的页面 CSS 无法重塑 它的点击速度与片段一直使用的队列相同——所以 组合重放后立即打开面板。 访客从不离开 没有 如何开始聊天.

#### 它推迟了请求, 不只是捆绑

从0.20.0起, `lazy` 其他 `'off'` 表示 **没有请求任何 Chartly 主机** 直到访客到达聊天。 页面载荷上没有联系到任何信息 : 不是 `widget.js`,则不 `loader.js` 也一样.

这是一种改变,值得说明为什么它需要改变。 懒惰的决定 曾经住在里面 `loader.js`,所以决定是否获取的脚本 在每一页视图中,在每一种模式下, `'manual'` 包含。 请求中包含访客的IP地址, 用户代理 和裁判,所以一个页面 设置 `lazy="manual"` 还告诉我们有访客 在他们摸到任何东西之前就在那里 触发器是这个软件包的一部分 现在,这就是说,他们跑英寸 __ 捆绑,所以没什么可拿的 在作出决定之前.

`lazy="off"` (默认和任何未设置) `lazy`)不变并渴望: 表示"在页面负载上牵引",并推迟它会在发射装置时移动 出现在从未要求的页面中.

如果你贴上 `<script>` 片断而不是使用此软件包 页面装入请求是结构性的,不能推迟 - `lazy` 无法运行 直至 `loader.js` 已经到了。 将我们的资产映射到自己的领域 ; 参见公众文件 `/version.json`,则 不可改变 `/v/<build>/` 路径和他们的SRI散列.

两个代价值得知道。 A 类 `track()` 以懒惰模式调用 排队直到装入捆绑,所以先离开页面的访客 失去活动。 还有 `lazy` 改为 ONCE, 在启动时: 更改属性 之后警告而不是生效.

与 `inline` 没有发射装置可以代替,所以触发器就是 元素接近取景端. `prefers-reduced-data` 编辑 浏览器的数据保护程序 `interaction` 温暖前; 从未转过弯 懒惰模式本身.

### `nonce` ——一页服务于严格的CSP

如果你的页面已送达 `script-src 'nonce-…'` 没有 `'unsafe-inline'`,给出 反应的非ce:

```html
<chatly-widget public-id="acme-web" nonce="r4nd0m-per-response"></chatly-widget>
```

元素把它放在 `loader.js` 它注入的脚本,并作为 `window.Chatly.nonce` 这样 `widget.js`、被推迟的块和面板 自己的样式表也带有它。 没有它,一个不单是政策 挡住装载器 唯一的标志是CSP在你的控制台里违反规定.

两件事情要正确 都是为了价值的来源 而不是这个属性.

**非ce是每个响应.** 薄荷一新 每页渲染,永远不会 硬码一: 重复的无字符比 `'unsafe-inline'`,从 任何能够读取一页源头的人,可以在下一页注入脚本 会跑的 这里没有东西缓存它 - 但无论是什么 让你的 HTML 可能,所以它 必须来自请求.

**从财产,而不是属性,如果你曾经读回来.** HTML 隐藏非 ces: 在带信头的 CSP 页面上, 浏览器将空白 `nonce` 内容属性在元素连接后立即保留该值 仅在元素的内部槽中 `element.nonce` 揭发。 这适用 改为 `<chatly-widget>` 就像一个 `<script>`,因此这个元素读取它自己的 财产损益—— a `getAttribute('nonce')` 在每次测试中读取作品 而不返回真实的页面.

如果您的政策允许由主机生成部件, 请留下属性 关闭。 没有什么是盖上印章的 嵌入体会注入它一直拥有的.

### 错误的 JSON 属性不会停止聊天

已经放弃了, `console.error` 说明哪些属性和原因,以及部件 开始没有它.

这和部件用一个 `mountTo` 选择 无匹配, 故意匹配: 失败 `mountTo` 就会把一个 在为嵌入聊天内容而构建的一页上 错误和容易错过, 而失败 `theme` 留个工作聊天 默认颜色和控制台中一个命名错误。 失去您的支持聊天 在后面的逗号上 交易会更糟.

## 属性

每一个JSON属性也是财产,财产获胜:

```js
const chat = document.querySelector('chatly-widget');
chat.theme = { primaryColor: '#4f46e5', colorScheme: 'auto' };
chat.visitor = { externalId: 'u_42', email: 'jamie@acme.io', userHash };
chat.config = { behavior: { tabs: ['home', 'messages'] } }; // the whole object
```

设定财产 **在此之前** 元素也被定义或升级, 因为每个有属性约束的模板引擎可以生成 点菜.

`chat.controls` 是部件的后启动方法对象,所以引用 元素足以驱动聊天。 也单独出口作为 `controls`21种方法——部件 `ChatlyApi` 减 `init` 财务报告和审定财务报表 `destroy` (元素拥有生命周期),减 `on`编号 :`off`谁的工作 `subscribe()` 和减 `mount`编号 :`unmount`,增加了第二个视图 本套件在参考计算寿命周期之外:

`open`, (中文(简体) ), `close`, (中文(简体) ), `toggle`, (中文(简体) ), `identify`, (中文(简体) ), `setUser`, (中文(简体) ), `setCustomAttributes`, (中文(简体) ), `deleteCustomAttribute`, (中文(简体) ), `setLabel`, (中文(简体) ), `removeLabel`, (中文(简体) ), `setLocale`, (中文(简体) ), `track`, (中文(简体) ), `registerPushToken`, (中文(简体) ), `reset`, (中文(简体) ), `setStorageConsent`, (中文(简体) ), `setOffset`, (中文(简体) ), `setTheme`, (中文(简体) ), `getUnreadCount`, (中文(简体) ), `hasSession`, (中文(简体) ), `startConversation`, (中文(简体) ), `setContext`, (中文(简体) ), `reportAction`。 。 。 .

其中两个答案,而不是行动, 两者都是安全的,在部件有之前 挂载 : `getUnreadCount()` 实值 `0` 财务报告和审定财务报表 `hasSession()` 实值 `false` 直到出现 东西问。 对 `getUnreadCount()` 与 `unread` 事件而不是 投票结果.

其他的19个ACT, 和在部件挂起之前打的电话 而非降下(0.21.0):它一挂起就排队并重放,所以 之前制作的主机页面按钮 `<chatly-widget>` 保持其第一次点击. 一个控制台警告说,这个电话已经排队——这个页面从未挂起过 部件还是一无所获.

`load` 未打开 `controls`,故意:这是装载器的动词,而不是 部件,和 `controls` 镜像 `ChatlyApi` 没错 使用 `prefetchWidget()`, (中文(简体) ), 随同出口.

`hasSession()` 这比其他的要早,所以 `lazy="manual"` 页 次 能够用它来决定 并且由于0.2.0是应答的 **马上**数字 : `startWidget` 在同一条存储的线上同步安装 键 `loader.js` 捆绑在山上,是罚款的。 这个 曾经是装货机的单独,装货机的标签是 `async`,所以读取 `false`。页面上没有元素的平地片段仍然需要等待 装载器-见 `onload` 上文的例子.

`init` 财务报告和审定财务报表 `destroy` 故意缺席:元素拥有生命周期, 并召人于后方,而他们确信有一件东西 没有.

## 活动

元素重新发送 **全部十二个** 作为 DOM 部件事件 `CustomEvent`,带有部件的有效载荷 `detail`它们会发泡,而且 `composed`所以祖先的听众会听到他们.

`chatly-ready`, (中文(简体) ), `chatly-open`, (中文(简体) ), `chatly-close`, (中文(简体) ), `chatly-message`, (中文(简体) ), `chatly-message-ack`, (中文(简体) ), `chatly-message-received`, (中文(简体) ), `chatly-unread`, (中文(简体) ), `chatly-conversation`, (中文(简体) ), `chatly-identified`, (中文(简体) ), `chatly-reset`, (中文(简体) ), `chatly-action`, (中文(简体) ), `chatly-error` ——导出为 `ELEMENT_EVENTS`。 。 。 .

部件本身事件名称中的点变成破折号, 所以 `message.ack` 实值 `chatly-message-ack`。前缀的同样原因 `chatly-` 没有 `chatly:`数字 : Vue 读取 `@chatly-message.ack` 作为事件 `chatly-message` 带有修改符 调用 `ack`而听者从不开火.

`chatly-ready` 财务报告和审定财务报表 `chatly-unread` 由 部件和元素订阅 `connectedCallback` - 所以,重播是 随即派出. 模板装订( E)`@chatly-unread`页:1 并看到它; 一个 `addEventListener` 在元素后调用 连接会错过,应该读 `controls.getUnreadCount()` 一次为 它的初始价值.

```html
<chatly-widget public-id="acme-web"></chatly-widget>
<script type="module">
  import '@chatlychat/widget-element/register';
  document.querySelector('chatly-widget').addEventListener('chatly-message', (e) => {
    console.log('reply from', e.detail.authorType);
  });
</script>
```

连字符,不是 `chatly:message`:一个结肠在事件名称中是合法的,但在 a Vue、Angular或Svelte模板装订.

直至 `0.4.0` 三个没有 `chatly-*` 完全没有形式 `message.ack`, (中文(简体) ), `message.received` 财务报告和审定财务报表 `unread` 名称由 `ChatlyEventName`这样 `subscribe()` 到达他们, 元素转发九。 如果你工作的话 环绕着这个圈子,工作仍然有效,不再需要了.

`subscribe()` 是另一条路进入, 而从代码中使用的不是 听众在元素上——它通过 `Chatly.on` 直接 :

```js
import { subscribe } from '@chatlychat/widget-element';

const off = subscribe('unread', (detail) => paint(detail.count));
```

它把未订阅者送回去,这很重要: `Chatly.off` 只删除一个 处理器可以匹配的身份, 所以一个消费者 谁建立一个新的关闭 每一次通话都会在每个挂载上泄露一个订阅者. 平原上 `window` 镜像 (单位:千美元)`chatly:unread`)也携带了所有十二个,如果你不想进口 任何东西.

在不复制此 README 的列表的情况下, 将全部十二个线线线连接到地图上 转发来源于.. `EVENT_HANDLERS` (移动事件 ) 处理器 名称)和 `WIDGET_EVENT_NAMES`,两者自 `0.4.0`他们就是 单源元素, React 包和类型检查器全部读取, 所以 从它们建立的清单不能与实际转发的内容相左.

## 内嵌

```html
<chatly-widget public-id="acme-web" inline style="height: 600px"></chatly-widget>
```

聊天会填充元素而不是浮起. 没有发射装置 没有转角, 财务报告和审定财务报表 `close()` 警告而不是工作——隐藏或去除元素.

要点 `display: block` 在此模式下, 因为自定义 元素为 `display: inline` 默认时, 崩溃为零高框 和装入的部件一模一样 还设置了420px `min-height` 除非你设置了一个.

## 主条目没有副作用

导入 `@chatlychat/widget-element` 定义什么也没有触及 DOM. `@chatlychat/widget-element/register` 是定义 `<chatly-widget>`,以及 `defineChatlyWidget('my-tag')` 如果你需要一个 不同的标签名称。 打两次电话都安全.

分钱的原因 `@chatlychat/widget-react` 可依赖此软件包进行 嵌入生命周期而不登记其消费者从未要求的元素, 和为什么这里没有任何东西 崩溃服务器侧捆绑——一个顶层 `class X extends HTMLElement` 会抛出 `HTMLElement is not defined` 页:1 瞬间 a Next.js 服务器组件从这里导入到一个类型 .

## 每页一个部件

`window.Chatly` 是一个单子。 两个连接 `<chatly-widget>` 元素为 不同的属性是配置错误:第一个拥有配置, 秒的属性被忽略(其事件仍然起火),以及控制台 警告是这么说的。 2个配置相同是无害的——这就是 使模板中的一个元素能够重交安全.

移动 DOM 中的元素,或者删除并重新添加到同一任务中, 已经 **没有** 重新启动部件。 A 类 `disconnectedCallback` 并不一定 卸载 : `appendChild` 在别处起火断开,然后连接,同样 框架对列表进行重键.

## 用片段编织

如果页面已有片段, 此软件包不会获取秒 装入器——它排队 `init` 在shim上 安装的片段并让 加载器重放. 元素的配置获胜. 你不需要两者,但 二者不相断.

## 自己为装货员服务

`loader-url` 默认为 `https://widget.chatlychat.com/loader.js`,这是 对几乎每个人都是正确的答案。 服侍就设置 `loader.js` 离开你 拥有CDN,或瞄准另一个Chatly环境的元素—— `GET /v1/channels/:id` 返回您请求的部署的正确值 `embed.loaderUrl`,所以从那里读取,而不是输入主机。 装载器 从自己的 URL 解析捆绑, 因此您需要一份副本 `widget.js` 财务报告和审定财务报表 它得到的块 坐在它的旁边.

相同的响应列出了运行中的部件连接到的每个来源 `connectOrigins`: API 主机, 以及两者下的实时主机 `https:` 财务报告和审定财务报表 `wss:` ——而从剧本主机中搭建的CSP仅让发射机作画和 然后阻止它提出的每一个请求.

## 许可证

麻省理工学院——见 `LICENSE`。 。 。 .

* * *

## 关于此寄存器

这是一个 **镜像**。 。 。 . `@chatlychat/widget-element` 由私人独身建筑 其余的 月台的迁移和合同检查现场直播 无法直接合并, 但补丁仍然是获得东西最快的方法 固定了,我们会把它 与归属.

您可以在这里做什么: 读取源代码, 运行测试, 打开一个问题, 或打开一个 PR 并且我们将把diff当作提案.

未镜像 : src/icon-names-parity. spec.ts —— 仍然在此重现的类别 与单列波的原作相匹配,这仅仅是其中的一个有意义的主张. 他们 继续跑.

问题: [https://github.com/chatlychat/chatly-widget-element/issues (中文(简体) )](https://github.com/chatlychat/chatly-widget-element/issues) \* 文件: [https://chatlychat.com/docs (中文(简体) )](https://chatlychat.com/docs)

## 常见问题

### @chatlychat/widget-element 是什么？

Chartly 聊天部件作为自定义元素 \(\), 加上嵌入式生命周期框架包装器共享 。 零从属\.

### 如何安装 @chatlychat/widget-element？

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

### @chatlychat/widget-element 支持 TypeScript 吗？

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

### @chatlychat/widget-element 支持 ESM 还是 CommonJS？

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

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

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

### @chatlychat/widget-element 可以商用吗？

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

### @chatlychat/widget-element 的下载量有多少？

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

### @chatlychat/widget-element 还在维护吗？

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

