# @chatwoot/captain-avatar 中文文档
规范地址：https://npmcn.com/package/%40chatwoot/captain-avatar/
版本：0\.2\.0
npm 元数据更新时间：2026-11-03T09:34:36.453Z
中文译文更新时间：2026-11-09T11:51:43.020Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40chatwoot/captain-avatar
原文对照：https://npmcn.com/package/%40chatwoot/captain-avatar/?lang=original
项目主页：https://github.com/chatwoot/captain-avatar#readme
源码仓库：https://github.com/chatwoot/captain-avatar
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：117 kB，33 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：vue \>=3\.3\.0
- 首次发布：2026-11-03T05:11:56.263Z
- 最新版本发布：2026-11-03T09:34:35.698Z
- 近 30 天下载量：4425（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）
## 中文简介
由Chatwoot机长出品的一出动画"3D相机",有LED-matrix相机,显示代理机的工作. WebGL2, 没有运行时间依赖性 。 一个平版Script API和一个Vue组件.
## 安装
```sh
npm install @chatwoot/captain-avatar
```
也可以使用：`pnpm add @chatwoot/captain-avatar`、`yarn add @chatwoot/captain-avatar`、`bun add @chatwoot/captain-avatar`
## README
# @chatwoot/captain-avatar (中文(简体) )
Chatwoot"船长"动画3D阿凡达. 它的LED-matrix面部和它耳机麦克风上所显示的光线显示代理正在做什么:思考,搜索,聆听,说话等.
它与 WebGL2 并不存在运行时间依赖性 。 可以从平版Script或作为Vue 3组件使用.
## 安装
```bash
npm install @chatwoot/captain-avatar
```
Vue是可选的同伴依赖. 只需使用组件即可使用 Vue 3.3 或稍后使用 .
## 用这个
### 普通类型脚本
```ts
import { createCaptainAvatar, thinking, speaking } from '@chatwoot/captain-avatar';
const avatar = createCaptainAvatar(document.querySelector('#captain')!, {
states: [thinking, speaking],
state: 'thinking',
size: 96,
});
avatar.update({ state: 'speaking' });
avatar.destroy();
```
`createCaptainAvatar` 将元素变成 `size` × `size` 框并画出其中的相机。 跳道,麦克风的发光和地板的影子从盒子边缘引出,而没有参与布局. 如果父母有 `overflow: hidden`剪断了它们.
### 阴道
```vue
```
组件采用与道具相同的选项. 它指出下列事件: `ready`, (中文(简体) ), `unsupported`, (中文(简体) ), `enter-start`, (中文(简体) ), `enter-end`, (中文(简体) ), `state-change` 财务报告和审定财务报表 `poke`。通过模板参考,它暴露了 `poke()` 财务报告和审定财务报表 `enter()`。 。 。 .
## 国家
通过您使用的状态. `idle` 总是包含在内。 进口的只是你用的东西 让你剩下的东西远离你的捆绑。 包括一切,通过 `allStates`。 。 。 .
| 状态 | 脸 | 动议 | 米克光线 |
| --- | --- | --- | --- |
| `idle` | 弹丸眼睛一闪一闪,就像标志一样 | 四处看看,偶尔跳一跳 | 软白色 |
| `thinking` | 眼睛用扫描线 及时扫过它们 麦克风在缓慢的圆圈中漂流 时而一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一 | 头向上倾斜,侧向 | 琥珀脉冲 |
| `searching` | 达丁的眼睛,一个光束扫屏 | 头朝一面扫地 | 青色闪光 |
| `listening` | 警示眼睛在现场的平衡者 | 头被鸡鸡,小点头 | 稳住绿色 |
| `typing` | 以用户类型读取的眼神 和一眨眼的护目镜 | 头被敲了,每个按键点个小点头 | 紫罗兰,每按键闪光 |
| `speaking` | 一个随口而动的口 | 鲍勃说话时 | 有演讲的花花 |
| `working` | 眼睛往下看,一个进步栏 | 忙得要命,偶尔跳一跳 | 蓝色闪烁 |
| `happy` | 举起双眼一笑 | 弹跳 | 粉红色 |
| `error` | 红X眼和一只Zigzag口 | 摇起头来 | 红色闪烁 |
| `sleeping` | 闭上眼睛和上升的Z's | 头被挖出,呼吸缓慢 | 关闭 |
如果你通过了 `happy`,点击也可以显示快乐的一瞬间.
### 显示用户正在输入
使用 `typing` 用户类型和调用 `avatar.keyStroke()` 从输入的 `input` 事件:
```ts
const avatar = createCaptainAvatar(el, { states: [typing], state: 'typing' });
input.addEventListener('input', () => avatar.keyStroke());
```
每通呼叫会把眼睛的视线移开,闪出麦克风光并点头. 8下按键后,凝视会扫回开始,就像被包裹的一行. 在大约2秒没有按键后,眼睛会回到中心. 在Vue,打电话 `keyStroke()` 在组件的模板参考.
## 选项
| 选项 | 默认 | 它会做什么 |
| --- | --- | --- |
| `state` | `'idle'` | 所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出. 一个未知的名字又回到 `idle`。 。 。 . |
| `states` | 无 | 阿凡达能显示的状态,除了 `idle`。 。 。 . |
| `size` | `160` | 装入活字盒的活字盒. |
| `theme` | `classic` | 颜色套. |
| `speed` | `1` | 每部动画速度的乘法. |
| `paused` | `false` | 持州还作相. |
| `interactive` | `true` | 沿着指针走,一击就跳出并旋转. |
| `floorShadow` | `true` | 画出头下柔软相影. |
| `seed` | 随机 | 数字从0到1可以抵消眨眼和一眼. |
| `entrance` | `false` | 在阿凡达准备好后播放出入口. |
| `orbit` | `false` | 让你把头卷起来 从任何一边看。 它留在你离开的地方, 点击它回转。 在触摸屏上,相声取而代之的是触摸手势. |
| `label` | `Captain, ` | 无障碍标签. |
`update(options)` 更改其中任何一项。 你留下的钥匙保持它的价值。 密钥集为 `undefined` 回到默认值.
64px下方,活字塔自画自画出低细. 它会掉入谷粒和LED网格,每个LED会填充它的细胞,使面部保持可读性.
## 主题
四个主题是: `classic`, (中文(简体) ), `midnight`, (中文(简体) ), `snow` 财务报告和审定财务报表 `grape`。每个是导出的对象:
```ts
import { createCaptainAvatar, midnight } from '@chatwoot/captain-avatar';
createCaptainAvatar(el, { theme: midnight });
```
为了制造自己的,通过一个物体 `name`, (中文(简体) ), `color` (壳), `trimColor` (耳杯声), `headsetColor` 和 `screenColor` \[LEDs\]. 每种颜色都是 `#rgb`, (中文(简体) ), `#rrggbb` 或者说 `rgb()` 绳子.
## 入口
与 `entrance: true`,或者当你打电话 `avatar.enter()`船长戴上耳机 头从屏幕上弹出 然后耳机掉下来,杯子收起,麦克风摇倒. 麦克风开着 然后屏幕开关 如果你通过了 `happy`屏幕在快乐的脸上打开 大约需要1.3秒.
## 活动
`avatar.on(event, listener)` 返回停止监听的函数.
| 活动 | 当火 | 细节 |
| --- | --- | --- |
| `ready` | 阴道被编译出,第一个框架被放入屏幕. | 无 |
| `unsupported` | 图形上下文被丢失了,没有在5秒内回来. 阿凡达停止渲染并释放出元素. | 无 |
| `enterstart` | 入口开始. | 无 |
| `enterend` | 入口结束。 如果阿凡达还在的话,它会直接发射 `enterstart`。 。 。 . | 无 |
| `statechange` | `update` 变了州. | `{ from, to }` |
| `poke` | 在交互时点击了相机 . | 无 |
## 浏览器支持
Avatar需要运行在真实图形硬件上的WebGL2. 它要求了解其背景 `failIfMajorPerformanceCaveat: true`,因此可以使CPU上的WebGL计算为不支持的浏览器.
在没有支持的地方, `createCaptainAvatar` 使元素不受影响,使无所事事。 它返回的手柄有 `supported: false`,而其方法却无所作为. Vue 组件没有产生和发出 `unsupported`。 。 。 .
为了避免下载无法渲染的相机, 在装入前在您的应用程序中运行相同的检查 :
```ts
function supportsCaptainAvatar() {
try {
const gl = document.createElement('canvas').getContext('webgl2', {
failIfMajorPerformanceCaveat: true,
});
gl?.getExtension('WEBGL_lose_context')?.loseContext();
return !!gl;
} catch {
return false;
}
}
```
## 业绩
每个帧,CPU运行运动,用一千字节的LED值来写出并构成最多3个绘图调用. GPU从阴影中抽取出其他一切.
帧速率跟随相机正在做的:
- **当有东西移动时:** a hop,出入口,换相,指针或活态以显示的全速运行.
- **冷静点 `idle`数字 :** 封顶了60英尺,所以一个还原的活字塔不会让120赫兹的显示保持繁忙.
- **冷静点 `sleeping`数字 :** 封顶在30英尺处.
- **关闭屏幕、 暂停或隐藏标签 :** 无所不能.
与 `prefers-reduced-motion: reduce`,相机画的州仍然姿势 而不动静.
## 懒地装上
Bundlers 拆分动态 `import()` 进入自己的地块。 以这种方式装入外形,使其远离主包:
```ts
import { defineAsyncComponent } from 'vue';
const CaptainAvatar = defineAsyncComponent(() =>
import('@chatwoot/captain-avatar/vue').then((m) => m.CaptainAvatar),
);
```
在同一懒惰地加载的代码内,从软件包中导入其他所有的东西,例如状态和主题. 正常的导入到其它任何地方都会将共享代码拉回主捆.
## 自定义状态
状态是平庸的对象,所以可以自己写作. 它有:
- `name`: 您通过的名称为 `state`
- `face(grid, params)`:在24×18个LED区域上绘制面相
- `light`:LED颜色(`screen`),麦克风颜色(`mic`),并随着时间推移而呈现出麦克风的亮度(`pulse`(中文(简体) )
- `motion(context)`: 可选的, 设置头部的目标设置每个步骤
- `rest`:可选, 减少运动的静态和 `paused`
- `followsPointer`:可选,将头转向指针
- `calmFps`:可选,在状态平静时将帧率封顶
软件包导出内置面部使用的绘图助手, 包括 `eyes`, (中文(简体) ), `pill`, (中文(简体) ), `rect`, (中文(简体) ), `sprite` 财务报告和审定财务报表 `put`中的文件 `src/states/` 正在使用实例.
## 发展
```bash
bun install
bun run dev # the playground
bun run build # dist/, with the shaders minified
bun run typecheck
```
游乐场拥有每个状态,主题,大小和速度控件的活性迷你相机,一个事件日志,以及一个带有帧统计和姿势控件的调试面板.
## 许可证
麻省理工学院. 见 `LICENSE`。 。 。 .
## 贷项
头部的设计,照明模型,运动和LED面相从一个港口开始 [机器人头](https://github.com/fayazara/robot-heads) 根据麻省理工学院的许可, 它的执照在 `LICENSE.robot-heads`。 。 。 .
## 常见问题
### @chatwoot/captain-avatar 是什么？
由Chatwoot机长出品的一出动画"3D相机",有LED-matrix相机,显示代理机的工作\. WebGL2, 没有运行时间依赖性 。 一个平版Script API和一个Vue组件\.
### 如何安装 @chatwoot/captain-avatar？
在项目目录运行 npm install @chatwoot/captain-avatar，或使用 pnpm add / yarn add / bun add。
### @chatwoot/captain-avatar 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @chatwoot/captain-avatar 支持 ESM 还是 CommonJS？
以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。
### @chatwoot/captain-avatar 可以商用吗？
@chatwoot/captain-avatar 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @chatwoot/captain-avatar 的下载量有多少？
根据 npm 官方下载统计，@chatwoot/captain-avatar 在 2026/10/10 – 2026/11/08 这 30 天内被下载 4,425 次，日均约 148 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @chatwoot/captain-avatar 还在维护吗？
最新版本 0\.2\.0 发布于 2026/11/03（6 天前）；至今共发布 3 个版本，其中过去 12 个月发布了 3 个；首次发布于 2026/11/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。