# @devicechain/widget-sdk 中文文档

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

版本：1\.4\.0
npm 元数据更新时间：2026-11-11T16:16:41.733Z
中文译文更新时间：2026-11-12T03:20:58.192Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：381 kB，55 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react ^19\.3\.0，echarts ^6\.0\.0，@devicechain/dashboards 1\.4\.0
- 首次发布：2026-10-12T22:34:23.560Z
- 最新版本发布：2026-11-11T16:16:41.181Z
- 近 30 天下载量：4907（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 35 个）

## 中文简介

DeviceChain 部件 SDK:将仪表板部件写成反应部件的打出合同,以及提供给主机的密封注册. 一次宣布部件(便携式描述器加可信任组件),并在 bu 旁边注册

## 安装

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

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

## README

# @ devicechain/ widget- sdk

将 DeviceChain 仪表板部件写成反应组件的打字合同,以及 用于主机应用程序的密封登记册。 内置部件是 完全通过此接口声明 .

```bash
npm install @devicechain/widget-sdk @devicechain/dashboards react
```

`@devicechain/dashboards` 财务报告和审定财务报表 `react` 为: **同行依赖关系**: SDK 定义反应 上下文, 新鲜度),一个上下文是 由创建对象识别,所以每个部件包和主机必须解决 同一本软件包的单一副本。 在您自己的部件包中宣布它为对等点, 永远不是一种依赖.

## 盒子里装的是什么

根条目为无图表和无地图:卡片框(`WidgetFrame`),主题可变 参考文献(`css`),格式化器,更改-闪光提示,选项阅读器(`optString`, (中文(简体) ), `optNumber`,...)和将中枢通道绑定到部件状态的回放钩. 一个部件 只从这里取出 DOM 的进口, 并且从Apache ECharts 或 MapLibre 或 内置部件.

一个流钩子从不将订阅的快照还给另一个. 自0.22起, `useAlarmStream` 财务报告和审定财务报表 `useLocationStream` 返回时 `loading: true` 没有从非常的行 将订阅更改(重新定位的插槽,一个新的过滤器),直到新的 订阅答案 。 在0.22之前,一个渲染 仍然背负以前的订阅 警报或位置.

帮助图表的人住在一个单独的条目上, `@devicechain/widget-sdk/echarts`页:1 `EChart` 包装, `buildLineOption` 编号 : `buildGaugeOption` 和图表颜色主题. `echarts` 是一个 **可选同伴依赖**,只需要一个导入该条目的部件.

图表引擎本身不属于该条目的静态进口. `EChart` 随叫随到, 作为一块块,第一次挂起图表,所以主机捆绑器将ECharts排除在第一个块之外 下载。 在发动机到来之前,图框是空的. 如果引擎无法取出, `EChart` 将错误丢入最近的错误边界,下一个挂载将再次取出。 一个东道主 想要在第一帧绘制图表 `loadChartEngine()` 在渲染之前 部件 绘制图表可以设置 `MyWidget.preload = loadChartEngine` ,然后 `preloadWidgets` 从 `@devicechain/widgets` 获取任何包含它的板的引擎 .

## 宣告部件

```tsx
import { defineWidget } from '@devicechain/widget-sdk';

export const tankLevelWidget = defineWidget({
  descriptor: {
    id: 'acme/tank-level',
    version: '1.0.0',
    sdkApiVersion: 1,
    optionsVersion: 1,
    display: { title: 'Tank level', category: 'Telemetry' },
    channel: 'measurement',
    datasource: { mode: 'required', selectors: ['device', 'slot'] },
    binding: { window: { option: 'window', min: 1 } },
    options: {
      unit: { kind: 'string', doc: 'Unit shown beside the level.' },
      window: { kind: 'number', integer: true, min: 1, doc: 'Samples retained.' },
    },
    defaults: { unit: '%' },
    interactions: {},
  },
  implementation: {
    kind: 'trusted-react',
    // `data` is typed from the channel: a measurement widget receives measurement data.
    component: ({ data }) => <span>{Object.values(data.latest)[0]?.value}</span>,
  },
});
```

描述器为平版JSON-序列可分解数据:没有组件,回调或URL. 描述符 或其默认或约束性不同意其选择 schema, 类型检查失败, 以及 `createWidgetRegistry` 再次检查同样的规则 运行时间.

## 登记

```ts
import { createWidgetRegistry } from '@devicechain/widget-sdk';

const registry = createWidgetRegistry([tankLevelWidget]);
```

登记册在创建时经过验证和封存:重复的标识、畸形的描述符, 无支持 `sdkApiVersion` 和无效的约束或默认都一起在 一个 `WidgetRegistryError`。没有全球登记;一页的两个登记册是 独立。 扩展 ids 有命名空格(`scope/name`); 未命名的 id 保留 用于内置部件.

信任的部件代码随主机页面权限运行 。 说明中的声明 形状 API; 它们不是安全边界 .

## 从框架提供下载

一个部件可以让查看器保存它显示的数据. 过 `exportRows` 改为 `WidgetFrame`: 函数 返回一个 `WidgetExportTable` (没有扩展名的文件名称、标题和 弦,数字,布尔斯或虚数,或者一个承诺。 框后绘制一个下载按钮 在标题栏中,和 **下载 CSV** 查看器选择时调用功能,所以表格是 以部件显示的内容为需求构建 。 道具是可选的, 特征检测: 一个部件 当标题栏被隐藏时,框不绘制按钮.

CSV编码器是框架的: RFC 4180 引用,一个文字单元格上的主要缩写,开头是 `=`, (中文(简体) ), `+`, (中文(简体) ), `-`, (中文(简体) ), `@`,标签或车厢返回(因此电子表格从未作为公式运行),UTF-8带有 字节顺序标记,所以 Excel 读取单位如下: `°C`。将单位置于标题中,将即时写入为 ISO 8601带区域,并在文件名中说明文件覆盖的内容(跨度和桶上) 屏幕). 绘制的图表 `<EChart>` 也会得到 **下载图像 (PNG)** 没有你的代码.

## 从0.21升级

0.22去除不导出. TypeScript 构建可注意三个变化:

-   `ChartTheme` 需要一个 `severity` 字段。 只有用手建一个主题,这才重要 而不是打电话 `useChartTheme` 或者说 `resolveChartTheme`。 。 。 .
-   工会 `WidgetChannel` (现在与 `'aggregate'`, (中文(简体) ), `WidgetId`, (中文(简体) ), `BuiltinWidgetId`, (中文(简体) ), `ThemeVar` 财务报告和审定财务报表 `OptionSpec` (现在与 `ListOptionSpec`)获得成员,因此详尽无遗 `switch` 一个以上 他们需要一个新的案子.
-   `formatValue` 不精确的回合至小数点后3个,或低于1个的4个重要数字 用于打印未圆形的数字.

无需改动的添加:

-   `WidgetFrame` 带 `flush`,删除填充其框的部件的内容粘贴 边缘到边缘,和 `sampleTime`,一个样本的时间 单值部件显示,所以 年龄读出年龄是抽样,而不是东道主所持的最新年龄.
-   `useElementSize` 选择 `step` 将每个维向下绕到一个多维, 所以一个只需要粗体大小的呼叫者 并不会对每个像素重新发号施令.
-   大小和密度符号的新出口`fontVar`, (中文(简体) ), `spaceVar`, (中文(简体) ), `tokenStyle`, (中文(简体) ), `useWidgetScale`, (中文(简体) ), `fitValueFont`),样本年龄(`useFreshness`, (中文(简体) ), `Freshness`, (中文(简体) ), `StaleBadge`, (中文(简体) ), `formatAge`),警报严重性(`SEVERITY_LEVELS`, (中文(简体) ), `severityVar`, (中文(简体) ), `useSeverityColors`, (中文(简体) ), 阈值 (`parseThresholds`, (中文(简体) ), `thresholdBands`, (中文(简体) ), `bandAt`),董事会的时间范围 (单位:千美元)`useWidgetTimeRange`)和中枢连接(`useHubConnectionState`, (中文(简体) ), `HubConnectionBadge`) (中文(简体) ).

`SDK_API_VERSION` 不变。 见 [如果您在 npm 包上构建](https://docs.devicechain.io/deployment/releases-and-upgrades#v0220-packages) 在发行的升级指南.

## 常见问题

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

DeviceChain 部件 SDK:将仪表板部件写成反应部件的打出合同,以及提供给主机的密封注册\. 一次宣布部件\(便携式描述器加可信任组件\),并在 bu 旁边注册

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

在项目目录运行 npm install @devicechain/widget-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.3\.0）、@devicechain/dashboards（1\.4\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

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

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

@devicechain/widget-sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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