host:宿主能力
查询宿主接口版本,与权限和运行时可用性分开判断。
Documentation content is currently available in Simplified Chinese.
这里的宿主指运行插件的飞块桌面端。context.host 提供当前桌面端已实现的接口及版本,用于判断当前系统支持哪些功能。
接口支持、插件权限和执行条件分别检查。例如,桌面端提供读取音量接口时,插件仍需声明并获得相应权限;实际读取也可能因音频设备不可用而失败。
插件可以直接使用 SDK 提供的 context.host 和 context.storage。
#hasCapability()
context.host.hasCapability(name: string, minimumVersion = 1): boolean同步查询接口是否达到最低版本。未知能力返回 false,版本必须为正安全整数。context.host.capabilities 是只读的名称到版本映射,生命周期内保持不变。
插件的必需能力写入 hostCapabilities.required,宿主在安装、启动和检查插件依赖时验证;不兼容的已安装包仍显示原因,但不会出现在新增动作、预设或超级块列表中。optional 缺失不阻止启动,插件按当前系统支持的能力决定是否启用对应功能。例如,读取音量接口支持 Windows 和 macOS:
if (context.host.hasCapability('system.getVolume', 1)) {
const volume = await context.system.getVolume();
// 仍需处理 volume.available、权限拒绝和设备读取失败。
}能力版本使用正整数,查询时按声明的最低版本比较。当前能力版本均为 1;插件包的 SemVer、apiVersion、服务接口版本与能力版本分别描述不同的契约。
#当前能力
下列接口当前均为 v1:
| 支持范围 | 能力名称 |
|---|---|
| 所有桌面平台 | settings.global、settings.configPage、host.capabilities、storage.paths、widgets.instances、states.publish、events.emit、network.getJson、plugins.call、native.execute、deck.navigate、system.openExternal、system.openPath |
| Windows、macOS | system.openApplication、system.getVolume、system.adjustVolume、system.sendHotkey、system.sendText、system.captureScreen、system.lockScreen、system.sleepDisplay |
| macOS | system.sleepComputer、system.runShortcut |
查询和目录分配无需权限。使用系统代理仍须声明对应 permissions 并获用户批准;system.getVolume 使用 system.adjustVolume 权限。插件业务能力通过自己的贡献或服务提供,不加入宿主能力表。
插件全局设置使用宿主能力 settings.global: 1,支持后台读取与运行期间的设置变更通知,见插件全局设置。