跳转到内容

签名关联类型:ExtensionDocumentScanPage – FocusLayoutSource

本页由当前 SDK 声明自动生成。

返回接口索引

ExtensionDocumentScanPage · ExtensionDocumentStore · ExtensionDocumentValue · ExtensionFaultHandle · ExtensionFaultKind · ExtensionFaultService · ExtensionFaultState · ExtensionInstallationsView · ExtensionManagerFacade · ExtensionManagerRowStatus · ExtensionManagerView · ExtensionManagerViewRow · ExtensionModelRow · ExtensionRenderFailedDiagnostic · ExtensionRenderFailure · ExtensionSiteRow · ExtensionToggles · ExternalJournalEntry · ExternalJournalOutcome · FieldValue · FileModelPreparation · FocusContentRect · FocusLayoutConfig · FocusLayoutSource

ExtensionDocumentScanPage

前缀扫描的一页(有界;稳定 key 排序)。

export type ExtensionDocumentScanPage = {
entries: ExtensionDocument[];
nextCursor: string | null;
};

关联类型:ExtensionDocument

成员说明:

  • nextCursor:下一页 cursor;无更多时为 null。

ExtensionDocumentStore

一个 extension 的 owner-scoped 存储 facade。

owner 固定为可信 extensionId;实现 MUST 拒绝任何其它 owner 的键/索引访问。

export type ExtensionDocumentStore = {
owner(): string;
get<T extends ExtensionDocumentValue = ExtensionDocumentValue>(key: string): Promise<ExtensionDocumentRead<T>>;
batch(operations: readonly ExtensionDocumentOperation[]): Promise<ExtensionDocumentBatchResult>;
scan(prefix: string, options?: {
cursor?: string;
limit?: number;
}): Promise<ExtensionDocumentScanPage>;
schemaVersion(): Promise<number>;
setSchemaVersion(version: number): Promise<void>;
};

关联类型:ExtensionDocumentValue · ExtensionDocumentRead · ExtensionDocumentOperation · ExtensionDocumentBatchResult · ExtensionDocumentScanPage

成员说明:

  • owner:该 facade 的 owner(extensionId)。
  • batch:原子 batch(CAS/成员索引一致)。
  • scan:前缀扫描(有界分页)。
  • schemaVersion:schema 迁移钩子:扩展拥有 schema,store 只保证幂等执行一次标记。

ExtensionDocumentValue

结构性 JSON 标量/对象/数组(可持久化)。

export type ExtensionDocumentValue = null | boolean | number | string | ExtensionDocumentValue[] | {
[key: string]: ExtensionDocumentValue;
};

ExtensionFaultHandle

装配方(kernel / reconciler)为一个已装配扩展登记的控制。

export type ExtensionFaultHandle = {
required: boolean;
epoch: number;
trip: (reason: "render-fault-threshold") => void;
reload?: () => void;
};

成员说明:

  • epoch:当前装配 epoch;只有该 epoch 的报告计入。
  • trip:熔断:释放该扩展的当前装配。
  • reload:重新加载:以新 epoch 重新装配(可选;缺省时设置面板只提示刷新)。

ExtensionFaultKind

故障类别(遥测 errorCode):只区分发生在哪类路径,不携带错误消息或堆栈。

  • render:React 渲染抛错(ContributionBoundary);
  • callback:宿主同步调用扩展回调抛错(guardContributionCall)。
export type ExtensionFaultKind = "render" | "callback";

ExtensionFaultService

export interface ExtensionFaultService {
report(failure: ExtensionRenderFailure): void;
attach(extensionId: string, handle: ExtensionFaultHandle): () => void;
isTripped(extensionId: string): boolean;
stateOf(extensionId: string): ExtensionFaultState | null;
reload(extensionId: string): boolean;
diagnostics(): readonly ExtensionRenderFailedDiagnostic[];
subscribe(listener: () => void): () => void;
version(): number;
}

关联类型:ExtensionRenderFailure · ExtensionFaultHandle · ExtensionFaultState · ExtensionRenderFailedDiagnostic

成员说明:

  • attach:装配方登记;返回注销函数(释放装配时调用)。重复登记同一扩展以最新为准。
  • reload:解除熔断并请求重新装配;返回是否已发起。

ExtensionFaultState

export type ExtensionFaultState = {
extensionId: string;
tripped: boolean;
reason: "render-fault-threshold" | null;
recentFailures: number;
lastMessage: string | null;
reloadable: boolean;
};

ExtensionInstallationsView

/api/settings 附带的受管安装概览(进行中的任务,供设置面恢复进度)。

export type ExtensionInstallationsView = {
revision: number;
jobs: ExtensionInstallJobView[];
restartSupported: boolean;
};

关联类型:ExtensionInstallJobView

成员说明:

  • revision:installations.json 的 revision。
  • jobs:进行中或最近结束的任务(最多保留最近若干条)。
  • restartSupported:本机宿主是否能受控重启(运行在受支持的拉起进程下);false 时设置面提示「请手动重启」。

ExtensionManagerFacade

面板能力(由 Plugin Manager Plugin 提供,Dialog renderer 消费)。

export type ExtensionManagerFacade = {
getSnapshot(): ExtensionManagerView;
subscribe(listener: () => void): () => void;
setEnabled(id: string, enabled: boolean): void;
refresh(): void;
setSiteEnabled(id: string, enabled: boolean): void;
siteRows(): ExtensionSiteRow[];
canManageSite(): boolean;
modelRows(): ExtensionModelRow[];
setModelEnabled(modelKey: string, enabled: boolean): void;
setModelsEnabled(modelKeys: readonly string[], enabled: boolean): void;
refreshModels(): Promise<void>;
setModelDefault(modelKey: string, modelType: string): void;
};

关联类型:ExtensionManagerView · ExtensionSiteRow · ExtensionModelRow

成员说明:

  • setEnabled:写入一个可配置 optional 插件的浏览器本地目标状态(不改变当前 Fiber;下次启动生效)。
  • refresh:触发刷新应用(生产实现为页面 reload)。
  • setSiteEnabled:写入一个站点应用插件的目标配置(服务端权威;运行中生效,仅管理员可用)。
  • siteRows:站点插件的实际状态(不含秘密;由服务端状态同步)。
  • canManageSite:站点操作是否可用(管理员授权)。
  • modelRows:生成模型行(服务端权威策略)。
  • setModelEnabled:启用/停用一个生成模型(仅管理员)。
  • setModelsEnabled:一次启用或关闭一批模型(仅管理员)。
  • refreshModels:重新拉取生成模型策略(发现新模型后立刻看到现状)。
  • setModelDefault:设置某类型的默认生成模型(仅管理员)。

ExtensionManagerRowStatus

面板一行的展示状态。

export type ExtensionManagerRowStatus = "active" | "disabled" | "failed" | "pending-enable" | "pending-disable";

ExtensionManagerView

面板只读快照。

export type ExtensionManagerView = {
rows: ExtensionManagerViewRow[];
siteRows: ExtensionSiteRow[];
modelRows: ExtensionModelRow[];
siteManageable: boolean;
siteError: string | null;
pending: boolean;
persistenceMessage: string | null;
error: string | null;
};

关联类型:ExtensionManagerViewRow · ExtensionSiteRow · ExtensionModelRow

成员说明:

  • siteRows:站点插件行。
  • modelRows:生成模型行。
  • siteManageable:站点写操作是否可用(管理员授权)。
  • siteError:站点状态同步错误(安全文案);无错误为 null。
  • pending:目标状态与本次启动实际装配是否不一致(存在待生效变更)。
  • persistenceMessage:持久化降级原因(读取/写入失败或存储不可用);无问题时为 null。
  • error:最近一次操作错误(不含底层原始数据);无错误时为 null。

ExtensionManagerViewRow

export type ExtensionManagerViewRow = {
directory?: string;
id: string;
name: string;
description: string;
required: boolean;
configurable: boolean;
status: ExtensionManagerRowStatus;
failureReason?: string;
icon?: PluginIcon;
};

关联类型:ExtensionManagerRowStatus · PluginIcon

成员说明:

  • directory:部署侧提供的所在目录,仅用于展示。
  • failureReason:failed 时的真实原因(加载/激活失败信息);没有就只显示状态,不编造文案。
  • icon:插件声明的图标;未声明时设置页回退通用插件图标。

ExtensionModelRow

生成模型管理行。

executable 表示 Provider 注册表中可执行;策略可包含不可执行的占位/历史模型。

extensionId 是可选补充(旧宿主没有):设置页用它把模型归到插件卡片(「服务端接入」这类 Provider 没有 providers.<id> 配置段,按 providerId 匹配不到)。

export type ExtensionModelRow = {
modelKey: string;
providerId: string;
modelType: string;
title: string;
enabled: boolean;
isDefault: boolean;
executable: boolean;
tombstone: boolean;
extensionId?: string;
notice?: string;
};

成员说明:

  • extensionId:提供该模型的宿主插件 id;旧宿主的策略历史行没有。
  • notice:行上的短标签(例如「站点在售」);缺省不显示。

ExtensionRenderFailedDiagnostic

export type ExtensionRenderFailedDiagnostic = ExtensionRenderFailure & {
event: "extension.render-failed";
at: number;
};

关联类型:ExtensionRenderFailure

成员说明:

  • message:仅用于本地诊断与设置卡片提示;MUST NOT 进入遥测。

ExtensionRenderFailure

export type ExtensionRenderFailure = {
extensionId: string;
epoch: number;
slot: string;
contributionId: string;
message: string;
kind?: ExtensionFaultKind;
};

关联类型:ExtensionFaultKind

成员说明:

  • message:仅用于本地诊断与设置卡片提示;MUST NOT 进入遥测。

ExtensionSiteRow

站点插件面板行。

actualState 来自服务端权威状态;面板不得从本地布尔值推导后端可用性。

export type ExtensionSiteRow = {
directory?: string;
extensionId: string;
name: string;
description: string;
desiredEnabled: boolean;
actualState: string;
actualStateLabel: string;
diagnostics: string[];
busy: boolean;
providerManaged: boolean;
icon?: PluginIcon;
};

关联类型:PluginIcon

成员说明:

  • directory:部署侧提供的所在目录,仅用于展示。
  • actualStateLabel:面向用户的实际状态说明(含 draining/failed 等)。
  • diagnostics:安全诊断(不含秘密);无诊断为空数组。
  • busy:该行是否处于进行中/异常(用于样式与只读提示)。
  • providerManaged:该站点插件是 Provider 类插件(声明了 providers.<providerId> 配置段):它的启停不列在 「站点插件」清单里,而是和配置一起出现在设置页「插件配置」的 Provider 卡片上。
  • icon:发布 metadata 声明的图标;站点服务端摘要不含图标,拿不到时回退通用插件图标。

ExtensionToggles

扩展启停状态:配置文件 extensions.<extensionId>.enabled 的投影。

事实来源是宿主配置文件,与扩展自己的参数配置同层同格式;消费方只投影它,不自带持久化。 未出现的 ID 表示使用默认值:manifest 的 defaultEnabled;未声明时按停用处理。

缺省为关是有意的:站点/后端扩展(含市场安装的扩展)不会因为漏写 defaultEnabled 就自动拿到可激活实例,启用必须有人显式表达。只有 Provider / 存储后端这类不进控制面的 hostPlugin 与本键无关,它们的键写了也不生效。

export type ExtensionToggles = Readonly<Record<string, boolean>>;

ExternalJournalEntry

Entry whose forward/inverse edits are owned by another authoritative authority (scene-area receipts, camera settings). The journal only stores verified callbacks; a rejected, cancelled or version-conflicted callback leaves the cursor in place, so an uncertain receipt never advances global history.

export type ExternalJournalEntry = {
kind: "external";
id: string;
label: string;
revision?: number;
undoRevision?: number;
undo: () => Promise<ExternalJournalOutcome>;
redo: () => Promise<ExternalJournalOutcome>;
state: JournalEntryState;
};

关联类型:ExternalJournalOutcome · JournalEntryState

ExternalJournalOutcome

export type ExternalJournalOutcome = {
ok: true;
revision?: number;
} | {
ok: false;
reason: string;
};

FieldValue

type FieldValue<D> = D extends {
kind: "integer";
} ? number : D extends {
kind: "boolean";
} ? boolean : string;

FileModelPreparation

export type FileModelPreparation = {
executionKey(context: NodeCapabilityContext): string | undefined;
prepare(context: NodeCapabilityContext): Promise<NodePreparationResult>;
};

关联类型:NodeCapabilityContext · NodePreparationResult

FocusContentRect

聚焦可用内容矩形(CSS 像素)。所有控件都落在 contentRect 之外。

export type FocusContentRect = {
x: number;
y: number;
width: number;
height: number;
};

FocusLayoutConfig

插件提供的布局配置(design D2/D3):只描述布局尺寸与开关,不携带 DOM 查询、 第二 runtime 或类型分支。公共几何据此 + 画布尺寸计算唯一 contentRect。

export type FocusLayoutConfig = {
desktop?: boolean;
navigationWidth?: number;
bottomBar?: number;
panel?: boolean;
animationPreview?: boolean;
toolColumn?: number;
toolbar?: number;
player?: number | ((width: number) => number);
panelMaxWidth?: number;
panelMaxHeight?: number;
chromeOwner?: "host" | "workspace";
};

成员说明:

  • desktop:固定桌面工具布局,不随窗口宽度将工具列与检查器移到上下。
  • navigationWidth:Independent left navigation width (CSS px).
  • bottomBar:Bottom operation area height; replaces the default footer/player reserve.
  • panel:是否呈现右侧(桌面)/底部(窄屏)检查面板(工具或历史)。
  • animationPreview:动画预览占位(模型编辑器子模式)。
  • toolColumn:左侧竖排工具列宽度(CSS px);缺省 0(模型编辑器使用)。
  • toolbar:公共标题栏下的工具选项区高度(CSS px)。
  • player:底部播放器占位高度(CSS px,或按画布宽度求值);缺省 0(video-editor 使用)。
  • panelMaxWidth:检查面板最大宽度(桌面);缺省 320。
  • panelMaxHeight:检查面板最大高度(窄屏);缺省 280。
  • chromeOwner:顶部/底部 chrome 由谁自绘。 缺省 "host":公共布局预留标题栏与底部基座;"workspace":工作区自己绘制顶部/底部 chrome,公共布局不再预留,contentRect 只扣面板与工具占位。该字段只影响几何计算,不回写 到 layout 结果(避免与窗口 chrome 偏移混淆)。

FocusLayoutSource

插件提供给公共宿主的布局来源(design D3):静态配置,或可订阅布局快照。

可订阅来源让插件把工具开关等局部状态以布局快照暴露,公共宿主在变化时重算 contentRect, 无需让公共 provider 拥有各 editor 的 toolsOpen。

export type FocusLayoutSource = FocusLayoutConfig | {
get(): FocusLayoutConfig;
subscribe(listener: () => void): () => void;
};

关联类型:FocusLayoutConfig