@goflowstate/widget-sdk

中文文档
0.3.5发布于 2026/11/15MITTypeScriptES Module近 30 天下载 1万

用于构建 Flowstate Canvas 部件的 SDK

中文使用文档
文档目录13 节
  1. 安装
  2. 快速启动
  3. 无害环境管理(捆绑者/类型脚本)
  4. 脚本标签( 无捆绑)
  5. 加入和订阅事件
  6. 持久性存储
  7. AI 补全
  8. 用户背景和同意
  9. 通知
  10. 观众要求(壳牌嘉宾)
  11. 流量反馈( 错误图标)
  12. 完整 API 参考
  13. 许可证

@ goflowstate/ widget- sdk

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

安装

npm install @goflowstate/widget-sdk

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

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

快速启动

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

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();
});

脚本标签( 无捆绑)

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

加入和订阅事件

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();

持久性存储

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 补全

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

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 —— 说 抓住他们 展示自己的副本.
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);
}

通知

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数字 :

: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 开发者文件 用于完整的API参考、表格式、AI集成指南和提交程序.

许可证

麻省理工学院

版本与发布记录

@goflowstate/widget-sdk 共发布 10 个版本,首次发布于 2026/07/07;过去 12 个月发布了 10 个版本。

版本发布日期距今
0.3.5latest2026/11/151 天前
0.3.42026/11/152 天前
0.3.22026/11/115 天前
0.3.12026/11/115 天前
0.3.02026/10/2819 天前
0.2.22026/08/232 个月前

关于 @goflowstate/widget-sdk 的常见问题

@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 和提交记录判断。