# context.widgets

## instances()

查询本插件某一种超级块的全部实例。后台需要定时更新每个块时，可以先查询实例，再按配置获取数据。

```ts
context.widgets.instances(widgetId: string): Promise<WidgetInstanceDescriptor[]>
```

### 参数

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `widgetId` | `string` | 本插件清单中的超级块 ID。 |

### 返回值

Promise 解析为实例数组。还没有放置这种超级块时，数组为空。

### 示例

```js
const instances = await context.widgets.instances("counter");
for (const instance of instances) {
  await context.states.publish("count", 0, {
    deviceId: instance.deviceId,
    screenId: instance.screenId,
    blockId: instance.blockId
  });
}
```


## WidgetInstanceDescriptor

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `deviceId` | `string` | 设备 ID |
| `screenId` | `string` | 屏幕 ID |
| `blockId` | `string` | 块 ID |
| `deviceName` | `string` | 设备的显示名称 |
| `screenName` | `string` | 屏幕的显示名称 |
| `blockTitle` | `string` | 块的显示名称 |
| `settings` | `Record<string, string \| number \| boolean>` | 这个实例的配置，包括后台可读的私密配置 |

ID 用于后续调用，名称用于显示。用户改名后，ID 保持不变。