# stateSources

一个 `StateSource` 描述一类值，例如电脑静音状态或某个计数器的计数。后台用 [context.states.publish()](./states-api.md)发布值。

## 作用域和可见范围

`scope` 表示这个值属于谁。`visibility` 表示流程从多大范围内能找到它。例如，计数器的值可以属于一个块，但允许同屏幕的流程读取。

| scope | 发布时的 target | lifetime | visibility |
| --- | --- | --- | --- |
| `global` | 省略 | `plugin` | `global` |
| `device` | `{ deviceId }` | `layout` | `device` 或 `global` |
| `screen` | `{ deviceId, screenId }` | `layout` | `screen`、`device` 或 `global` |
| `widget-shared` | 省略 | `placement` | `global` |
| `widget-instance` | `{ deviceId, screenId, blockId }` | `placement` | `block`、`screen`、`device` 或 `global` |

超级块的 `stateSource` 可订阅全局值、同类型共享值或自身实例值。声明时把 `readAccess.widgets` 设为 `true`。

## StateSource

清单位置：`manifest.contributes.stateSources[]`。

### `StateSource.id`

`string` · 必填

来源 ID，使用小写字母开头，可包含小写字母、数字、`.`、`_`、`:` 和 `-`，最多 128 个字符。

### `StateSource.title`

`string` · 必填

状态积木显示的名称，最多 80 个字符。

### `StateSource.description`

`string` · 可选

解释状态含义、单位或采样条件，最多 240 个字符。

### `StateSource.scope`

`string` · 必填

值的归属，见上方作用域表。

### `StateSource.visibility`

`string` · 必填

流程可以找到该值的范围，见上方对应关系。

### `StateSource.widgetId`

`string` · widget-* 必填

状态所属的超级块类型 ID。其他作用域不填写。

### `StateSource.schema`

`Schema` · 必填

完整状态值的结构。固定候选值使用 `enum` 和 `enumLabels`。

### `StateSource.readAccess`

`StateReadAccess` · 必填

分别指定流程和超级块能否读取。

### `StateSource.writeAccess`

`"owner-plugin"` · 必填

值由声明它的插件发布。需要改变外部系统状态时，通过动作完成。

### `StateSource.lifetime`

`"plugin" | "layout" | "placement"` · 必填

值何时随插件或布局清理，按上方作用域表填写。它不表示把值写入磁盘。

`placement` 不保证业务数据持久化，也不代表新挂载页面收到的首份快照已经与后台校准。需要跨插件或宿主重启恢复的数据由插件持久化；已放置实例的首屏同步采用[主动读取加订阅](../guides/data-services.md#超级块首屏读取)。

### `StateSource.maxBytes`

`integer` · 可选

一次发布的 JSON 最大字节数，默认 4096，范围为 1024–65536。

## StateReadAccess

清单位置：`manifest.contributes.stateSources[].readAccess`。

### `StateReadAccess.workflows`

`boolean` · 必填

是否允许流程读取这个来源。

### `StateReadAccess.widgets`

`boolean` · 必填

是否允许超级块订阅这个来源。