# @goflowstate/widget-sdk 中文文档

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

版本：0\.3\.5
npm 元数据更新时间：2026-11-15T09:49:37.221Z
中文译文更新时间：2026-11-16T18:09:18.664Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：541 kB，42 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-07-06T16:38:22.021Z
- 最新版本发布：2026-11-15T09:49:36.817Z
- 近 30 天下载量：10363（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

用于构建 Flowstate Canvas 部件的 SDK

## 安装

```sh
npm install @goflowstate/widget-sdk
```

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

## README

# @ goflowstate/ widget- sdk

SDK用于在"流州"风景名胜区内部运行的构件.

## 安装

```bash
npm install @goflowstate/widget-sdk
```

或者通过CDN(不需要捆绑):

```html
<script src="https://unpkg.com/@goflowstate/widget-sdk/dist/canvas-widget-sdk.js"></script>
```

## 快速启动

### 无害环境管理(捆绑者/类型脚本)

```ts
import { CanvasWidget } from '@goflowstate/widget-sdk';

const widget = await CanvasWidget.init();

// React to display state changes
widget.onStateChange((state) => {
  console.log('Widget state:', state); // 'collapsed' | 'expanding' | 'expanded' | 'collapsing'
});

// Expand into modal view
document.getElementById('open-btn')?.addEventListener('click', () => {
  widget.requestExpand();
});
```

### 脚本标签( 无捆绑)

```html
<script src="canvas-widget-sdk.js"></script>
<script>
  CanvasWidget.init().then((widget) => {
    widget.onStateChange((state) => console.log(state));
  });
</script>
```

## 加入和订阅事件

```ts
const widget = await CanvasWidget.init();

// Broadcast to other widgets on the same canvas
widget.emit('timer:tick', { remaining: 60 });

// Listen for events from other widgets
const unsub = widget.subscribe('timer:tick', (event) => {
  console.log(event.topic, event.payload);
});

// Stop listening
unsub();
```

## 持久性存储

```ts
const widget = await CanvasWidget.init();

// Store a value (scoped to this widget installation)
await widget.storage.set('count', 42);

// Retrieve a value
const count = await widget.storage.get('count');

// Remove a value
await widget.storage.delete('count');
```

## AI 补全

在不持有任何提供者密钥的情况下调用平台的模型. 每个电话都是 和你的出版业务有关.

```ts
const widget = await CanvasWidget.init();

// One-shot completion
const res = await widget.ai.complete({
  alias: 'widget.gpt-mini', // widget.* aliases only — never raw model ids
  system: 'You summarise kanban boards in one sentence.',
  messages: [{ role: 'user', content: boardAsText }],
});
console.log(res.text, res.inputTokens, res.outputTokens);

// Streaming
for await (const ev of widget.ai.stream({
  alias: 'widget.haiku',
  messages: [{ role: 'user', content: 'Brainstorm three icebreakers.' }],
})) {
  if (ev.type === 'text') appendToUi(ev.text);
  if (ev.type === 'done') console.log('tokens:', ev.inputTokens, ev.outputTokens);
  if (ev.type === 'error') showError(ev.message);
}
```

可用的别名 : `widget.haiku` (Anthropic,快来), `widget.sonnet` (Anthropic,最强), `widget.gpt` (开放AI,最强), `widget.gpt-mini` (开放AI,快), `widget.gemini` (Google,最强), `widget.gemini-mini` (高格尔,快), `widget.sonar` (复杂,答案基于现场网络) 搜索), `widget.sonar-pro` (繁杂,网易,更深的研究). 异名是平台管理的;一个模型背后的模型可以改进而不用 代码在你这边更改.

注释:

-   `maxTokens` 被夹住的服务器侧到 \[256, 4096\] (默认 1024)。 这个 地板之所以存在,是因为OpenAI的别名是推理模型:一个微小的 预算完全被隐形推理所消耗,返回为空 文本为 `stopReason: 'length'`。如果看到空文本,请提高预算.
-   越狱 `stream()` 循环取消上游呼叫,所以你是 没有为您停止阅读的文本计费.
-   预算出错, 有信件开始 `usage limit reached` —— 说 抓住他们 展示自己的副本.

## 用户背景和同意

```ts
const widget = await CanvasWidget.init();

// Request access to user data
const result = await widget.requestConsent('user:profile', 'Needed to personalise your experience');
if (result.granted) {
  console.log('User:', widget.user?.displayName);
}
```

## 通知

```ts
widget.notify('Saved!', { level: 'info', duration: 3000 });
```

## 观众要求(壳牌嘉宾)

在unishell shell网页上开幕的会话 属于一位客人,他的名字是, 电子邮件或电话已验证 。 这些事实都发生在 状态改为 `state.viewer.claims`,最新的一个是 `session.claims`数字 :

```
const session = CanvasWidget.initSession();
const state = await session.join();
const email = session.claims?.email; // { type, value, source, verifiedAt? } | undefined
```

索求只是读者自己的 而且是背景,不是 授权. `session.claims` 实值 `null` 为会员、PWA嘉宾和 在第一州到达之前.

## 流量反馈( 错误图标)

呼唤的流出 `CanvasWidget.initSession()` 带有反馈图标,没有自己的代码. 戒指打开了反馈,会话状态就这么说了 SDK放一圈 按钮。 水龙头一次打开一个字段的表,然后取出 其后页的截图,图标和工作表都没有. 床单上写着 步骤:角标记框上页,槽上写作"抓取截图"(最多15秒), 然后"Screenshot附" 图片和一张支票,或者"没有截图" 与"Take" 当无法取出或被取出时, 按钮读取“ 发送” 时, 便条 单子在关闭前以"Feedback sent"结尾 该说明通过流量会话发送给 `POST /api/w/:slug/feedback`。 。 。 .

图标和工作表查看他们所坐的页面:其字体、地、墨、填 和它的主按钮的形状,以及它的角半径。 要设定角色, 请设置自定义属性 `:root`数字 :

```css
:root {
  --fs-feedback-cta: #5136c4; /* also -cta-ink, -ground, -ink, -font, -font-display, -radius */
  --fs-feedback-bottom: 96px; /* where the icon sits; also -right */
}
```

工作表的类型来自流动所画的字,而不是来自 `<body>`: 标题 最大方向、音符和字段的相貌、重量和字母间隔 流中大部分较小的文字被设定在相上,发送按钮取出相上,相上,相上,相上, 字母间距和流量主按钮的大小写。 键 `--fs-feedback-font` 或者说 `--fs-feedback-font-display` 当诵经已去.

按钮会漂浮在流上,属于使用它的人. 他们可以把它拖到任何地方, 它在更近的一面。 一闪一闪,或一被拖入边缘, 把它停在那里,作为一个 微小标签, 错误仍在显示; 标签上的水龙头打开工作表并拉取标签 内向又漂出. 床单还设有"把按钮接到侧"的链接. 当一个人 离开按钮被记住.

在一个人移动之前,按钮保持远离页面自身的控制. 它从下角开始,并且,任何时候 页面更改、大小调整或停止滚动,查找最下端为空的边缘。 它仅停留在一行文字上 当空地在它的上方, 只有在整个边缘控制时, 才能控制。 接线 `--fs-feedback-bottom` 关掉它,把图标放在流出的地方.

将图标取出流出的一个屏幕(胶片,全屏幕图片),设定 `--fs-feedback-display: none` 例如,从流程的样式表开始,当屏幕打开时 `:root:has(.film) { --fs-feedback-display: none; }`。 。 。 .

每个屏幕的名字,所以一个报告说它来自哪里: `document.body.dataset.pageKey = 'question-2'`。 。 。 . 不可显示图标的页面( 投影墙) `<html data-fs-feedback="off">`。 。 。 .

## 完整 API 参考

见 [Flowstate 开发者文件](https://developer.goflowstate.com/docs/) 用于完整的API参考、表格式、AI集成指南和提交程序.

## 许可证

麻省理工学院

## 常见问题

### @goflowstate/widget-sdk 是什么？

用于构建 Flowstate Canvas 部件的 SDK

### 如何安装 @goflowstate/widget-sdk？

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

### @goflowstate/widget-sdk 支持 TypeScript 吗？

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

### @goflowstate/widget-sdk 支持 ESM 还是 CommonJS？

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

### @goflowstate/widget-sdk 可以商用吗？

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

### @goflowstate/widget-sdk 的下载量有多少？

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

### @goflowstate/widget-sdk 还在维护吗？

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

