插件插槽

大多数 TUI 应用最初都是单一代码库。随着功能和团队的增长，您可能需要扩展点，而无需让用户 fork 应用。

插件插槽为您提供了解决方案。宿主应用在布局中定义命名位置（例如状态栏、侧边栏或面板），插件在运行时为这些位置贡献 UI。

宿主保持对布局、渲染模式和类型契约的控制。插件只能接收宿主有意暴露的上下文和插槽属性。

本页描述了 Core、React 和 Solid 绑定所构建的共享注册表 API。如果您正在构建应用，请从您使用的绑定对应的页面开始：

• Core 插槽 — 无框架依赖，BaseRenderable 节点
• React 插槽 — ReactNode
• Solid 插槽 — JSX.Element

如果您在运行时从磁盘加载插件模块，请参阅 React 插槽页面和 Solid 插槽页面上的运行时支持说明。对于自定义宿主，请使用 @opentui/core/runtime-plugin-support 或从 @opentui/core/runtime-plugin 中的 createRuntimePlugin。

如果您需要了解底层模型、想为其他框架构建自定义绑定，或需要直接访问注册表 API，请继续阅读。

概念

• 宿主（Host）：定义插槽名称和插槽属性类型。
• 插件（Plugin）：贡献一个或多个插槽渲染回调。可能包含生命周期钩子。
• 注册表（Registry）：注册插件并解析插槽的贡献。
• 插槽模式（Slot mode）：控制插件输出和回退 UI 的组合方式（append、replace 或 single_winner）。

定义插槽和宿主上下文

插槽名称映射到每个插槽接收的属性。宿主上下文是一个传递给每个插件渲染器的共享对象。

import type { PluginContext } from "@opentui/core"

type AppSlots = {
  statusbar: { user: string }
  sidebar: { section: "left" | "right" }
}

interface AppContext extends PluginContext {
  appName: string
  version: string
}

上下文可以是任何对象。PluginContext 是 object 的类型别名——扩展它不是必须的，但可以为您的插件提供一个可引用的命名类型。

创建注册表

import { createSlotRegistry } from "@opentui/core"

type AppSlots = {
  statusbar: { user: string }
  sidebar: { section: "left" | "right" }
}

const context = { appName: "my-app", version: "1.0.0" }

const registry = createSlotRegistry<string, AppSlots, typeof context>(renderer, "my-app:plugins", context)

第一个类型参数（TNode）是您的框架返回的节点类型——Core 为 BaseRenderable，React 为 ReactNode，Solid 为 JSX.Element。框架特定的辅助函数会为您填充这个类型。

createSlotRegistry 是以渲染器为作用域的。对于给定的 (renderer, key) 对，您总是得到同一个注册表实例。key 参数在渲染器内对注册表命名空间化，以便多个独立注册表可以共存。

使用相同的 (renderer, key) 对再次调用 createSlotRegistry 会返回现有注册表并通过 configure() 应用新的 options。context 参数必须是相同的对象引用——传递不同的上下文对象会抛出错误。这意味着您应该创建一次上下文对象并重复使用：

// 正确 — 相同的对象引用
const context = { appName: "my-app" }
const reg1 = createSlotRegistry(renderer, "my-key", context)
const reg2 = createSlotRegistry(renderer, "my-key", context) // 返回 reg1

// 抛出错误 — 即使结构相同，也是不同的对象
const reg3 = createSlotRegistry(renderer, "my-key", { appName: "my-app" })

当渲染器被销毁时，所有以它为作用域的注册表都会自动清除和释放。

框架特定的辅助函数（createCoreSlotRegistry、createReactSlotRegistry、createSolidSlotRegistry）内部使用固定键调用 createSlotRegistry。仅当您需要每个渲染器有多个独立注册表时才直接使用 createSlotRegistry。

注册表选项

所有 create*SlotRegistry 函数接受一个可选的 SlotRegistryOptions 对象：

注册插件

const unregister = registry.register({
  id: "clock-plugin",
  order: 0,
  setup(ctx, renderer) {
    // 注册时调用一次 — 在此处初始化资源
  },
  dispose() {
    // 插件被注销时调用 — 在此处清理资源
  },
  slots: {
    statusbar(ctx, props) {
      return `${ctx.appName}:${props.user}`
    },
  },
})

// 稍后：移除此插件
unregister()

register() 返回一个注销函数。调用它会移除插件并调用其 dispose 钩子。

插件接口

Core 绑定通过托管插槽对象扩展了此接口，添加了生命周期钩子。

排序

插件按以下顺序解析：

1. order 升序（数字小的优先）
2. 注册顺序（先注册的优先）
3. id 字典序（平局时使用）

插槽模式

每个插槽挂载或 <Slot> 组件都接受一个 mode。该模式控制插件输出和回退 UI 的组合方式。

解析贡献

const entries = registry.resolveEntries("statusbar")
// Array<{ id: string, renderer: (ctx, props) => TNode }>

const slotRenderers = registry.resolve("statusbar")
// Array<(ctx, props) => TNode>

这里的 renderer 指的是插件的插槽渲染回调，而不是 CliRenderer 实例。

当您需要插件 id 和回调一起使用时，请使用 resolveEntries。当您只需要回调时，请使用 resolve。

注册表方法

错误处理

注册表暴露插件错误事件：

registry.onPluginError((event) => {
  console.error(event.pluginId, event.phase, event.source, event.error.message)
})

您也可以读取和清除缓冲的错误：

const history = registry.getPluginErrors()
registry.clearPluginErrors()

PluginErrorReport

reportPluginError 方法接受一个 PluginErrorReport：

PluginErrorEvent

下一步：具体宿主 API

将上述共享模型与以下宿主集成之一配合使用：

• Core 插槽 — 无框架依赖，返回 BaseRenderable 节点
• React 插槽 — 返回 ReactNode
• Solid 插槽 — 返回 JSX.Element