background

Lite API 3.4，需声明 manifest.background。bluetooth: true 申请用户选中设备的全部 GATT 服务，可用 services 白名单收窄；省略操作字段允许设备支持的全部操作，显式声明任意操作后未声明项禁止。network: true 申请公网 HTTPS/WSS，networkOrigins 白名单可选且优先。start 请求宿主授权并按需启动。首次授权可取消，最多等待五分钟，不计入命令执行预算。关闭发起调用方会取消尚未完成的启动；就绪后关闭 View 不停止 background。stop 释放运行实例和连接。request 使用匹配 requestId 的消息封套，启动后的回复超时为 30 秒。消息必须兼容 JSON。onMessage 属于当前运行实例和调用方，重启后需重新订阅。requestDevice 的截止时间为五分钟：取消保留当前实例，确认则用新设备授权替换实例。网络和 BLE 权限独立于浏览器权限。

使用指南: background. API 索引.

签名、参数及返回类型从 SDK 自动生成；可选成员不保证在每个宿主和上下文中存在。

PluginBackground

源码

PluginBackground.isRunning

支持宿主: Lite

Lite API 3.6。仅当前窗口和 Space 存在已就绪、未撤销的实例时返回 true。不会启动后台或请求授权。

isRunning(): Promise<boolean>;

返回值: Promise<boolean>.

PluginBackground.requestDevice

支持宿主: Lite

打开原生 BLE 选择器。确认会替换当前实例，取消则保留。

requestDevice(): Promise<{
    id: string;
    name?: string;
}>;

返回值: Promise<{ id: string; name?: string; }>.

PluginBackground.start

支持宿主: Lite

经宿主授权启动插件 background，已有运行实例时复用。

start(): Promise<void>;

返回值: Promise<void>.

PluginBackground.stop

支持宿主: Lite

停止当前实例并释放其资源和授权。

stop(): Promise<void>;

返回值: Promise<void>.

PluginBackground.postMessage

支持宿主: Lite

发送兼容 JSON 的原始消息；调用完成不代表 background 已处理完毕。

postMessage(message: BackgroundMessage): Promise<void>;

参数	类型	必填
message	BackgroundMessage	是

返回值: Promise<void>.

PluginBackground.request

支持宿主: Lite

发送请求封套并等待相同 requestId 的响应，超时会拒绝。

request(message: BackgroundMessage): Promise<BackgroundMessage>;

参数	类型	必填
message	BackgroundMessage	是

返回值: Promise<BackgroundMessage>.

PluginBackground.onMessage

支持宿主: Lite

订阅当前实例的原始消息。调用方关闭时释放订阅，background 重启后重新订阅。

onMessage(listener: (message: BackgroundMessage) => void): Promise<Disposable>;

参数	类型	必填
listener	(message: BackgroundMessage) => void	是

返回值: Promise<Disposable>.

关联类型: BackgroundMessage, Disposable.

BackgroundHost

源码

BackgroundHost.spaceId

支持宿主: Lite

Lite API 3.6。后台模块通过 globalThis.ctx 访问宿主对象。此字段标识当前 Space，不是文件系统路径。

readonly spaceId: string;

BackgroundHost.instanceId

支持宿主: Lite

唯一标识本次运行，停止并重启后改变，关闭 View 不改变。

readonly instanceId: string;

BackgroundHost.events

支持宿主: Lite

需声明 background.fileHistory: true 并经宿主授权。events.on(“file.opened”, listener) 返回可取消的成功打开监听，不提供初始快照或历史回放。事件仅含元数据，撤销后停止发送。统计口径见后台指南。

readonly events: PluginEvents;

BackgroundHost.storage

支持宿主: Lite

需声明 storage.maxBytes。与 View/action 共用插件私有、本机二进制存储和配额。跨 Space 共享，需要区分时在键中包含 spaceId。并发读改写不是事务。

readonly storage?: PluginStorage;

关联类型: PluginEvents, PluginStorage.