跳转到内容

sidecar

在 manifest.sidecar 声明本机程序与默认参数。API 3.9 的 configurable: true 可启用需审阅的启动配置;API 3.12 的 maxOutputFrameBytes 可接收有明确大小上限的大响应。仅独立页面和文件 View 可获得此能力;原生程序保有 JavaScript 沙箱之外的系统权限。CLI Serve 和移动端不提供原生 sidecar。

使用指南: native-processes. API 索引.

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

源码

支持宿主: Lite

export type SidecarEvent = {
type: "message";
data: BackgroundMessage;
} | {
type: "stderr";
text: string;
} | {
type: "exit";
code: number | null;
signal: string | null;
} | {
type: "error";
message: string;
};

关联类型: BackgroundMessage.

源码

支持宿主: Lite

available: boolean;

支持宿主: Lite

running: boolean;

支持宿主: Lite

command: string;

支持宿主: Lite

launch?: SidecarLaunch;

关联类型: SidecarLaunch.

源码

支持宿主: Lite

command: string;

支持宿主: Lite

args: string[];

源码

支持宿主: Lite

仅查询:available 表示找到了程序,running 表示存在所属原生进程;均不保证协议就绪或程序版本兼容。不会执行、安装或弹出授权。

status(): Promise<SidecarStatus>;

返回值: Promise<SidecarStatus>.

支持宿主: Lite

核对按 Space、包修订及含参数的精确程序身份保存的授权,缺失或变化时请求审阅。安装或启用可审阅具体默认启动;覆盖须声明 configurable: true。不同的已有进程须先停止。待启动确认最多五分钟,随发起 View 取消;已启动后关闭 View 仅断开连接。成功仅表示系统启动程序,不代表协议就绪。

start(launch?: SidecarLaunch): Promise<void>;
参数 类型 必填
launch SidecarLaunch 否

返回值: Promise<void>.

支持宿主: Lite

停止共享的所属进程树并等待退出,影响所有已连接 View。Stop 保留授权,禁用或卸载撤销授权。更新插件、离开 Space、关闭所属窗口或退出 Lite 也会停止进程;不会撤销已产生的原生修改。

stop(): Promise<void>;

返回值: Promise<void>.

支持宿主: Lite

写入一个 JSON 值并追加 LF。包含 LF 的单帧最多 1 MiB;含本次新帧的待写 stdin 最多 4 MiB。完成表示流写入完成,不表示收到原生协议回复。

send(data: BackgroundMessage): Promise<void>;
参数 类型 必填
data BackgroundMessage 是

返回值: Promise<void>.

支持宿主: Lite

订阅不会启动进程,返回可释放监听器,关闭 View 时取消订阅。stdout 以 LF 分隔 JSON(接受 CRLF),单条记录默认最多 1 MiB,不含 CRLF;API 3.12 可声明 manifest.sidecar.maxOutputFrameBytes,整数范围 1 至 16777216。stdout 每秒字节上限为 max(16 MiB, 单条记录上限的两倍);stderr 每秒超出 1 MiB 的部分丢弃。非法或超限输出会先发出 error 再停止进程,exit 到达时应保留最初错误。Unicode 行分隔符仍是字符串内容。事件不重放,重新连接后应查询原生状态。

onEvent(listener: (event: SidecarEvent) => void): Promise<Disposable>;
参数 类型 必填
listener (event: SidecarEvent) => void 是

返回值: Promise<Disposable>.

关联类型: SidecarStatus, SidecarLaunch, BackgroundMessage, SidecarEvent, Disposable.