Solid keymap 绑定 (OpenTUI)

本页涵盖 @opentui/keymap/solid。

这些绑定用于 OpenTUI Solid 应用。它们使用来自 @opentui/keymap/opentui 的预创建 Keymap<Renderable, KeyEvent>；它们不包装浏览器 Solid 应用中使用的 DOM/HTML 适配器。

如果您尚未阅读共享模型，请从 Keymap 概览开始。关于 keymap 构建，请参阅 Keymap 宿主。

Solid 提供的功能

KeymapProvider — 现有 OpenTUI keymap 的 Solid 上下文提供者
useKeymap() — 从上下文返回当前的 OpenTUI keymap
useBindings(createLayer) — 为当前响应式作用域注册一个 keymap 层
useKeymapSelector(selector) — 从当前 keymap 响应式派生任意值
reactiveMatcherFromSignal(accessor, predicate?) — 将 Solid accessor 适配为 ReactiveMatcher

基本用法

import { createCliRenderer } from "@opentui/core"
import { createDefaultOpenTuiKeymap } from "@opentui/keymap/opentui"
import { KeymapProvider, useBindings } from "@opentui/keymap/solid"
import { render } from "@opentui/solid"

const renderer = await createCliRenderer()
const keymap = createDefaultOpenTuiKeymap(renderer)

function App() {
  useBindings(() => ({
    commands: [
      {
        name: "quit",
        run() {
          renderer.destroy()
        },
      },
    ],
    bindings: [{ key: "q", cmd: "quit" }],
  }))

  return <text>Press q to quit</text>
}

await render(
  () => (
    <KeymapProvider keymap={keymap}>
      <App />
    </KeymapProvider>
  ),
  renderer,
)

Provider

属性	类型	必需	描述
`keymap`	`Keymap<Renderable, KeyEvent>`	是	OpenTUI keymap 实例
`children`	`JSX.Element`	是	后代 Solid 树

钩子

钩子	描述
`useKeymap()`	返回当前 keymap，如果缺少 provider 则抛出异常
`useBindings(createLayer)`	在响应式 `createEffect` 中运行层工厂，注册层，并随当前响应式作用域释放
`useKeymapSelector(selector)`	返回一个 `Accessor<T>`，在批量 keymap 状态变更时重新运行选择器
`reactiveMatcherFromSignal(...)`	从任何 Solid accessor 构建 `ReactiveMatcher`

`useBindings`

useBindings() 注册一个类似层的对象。返回的层可以包含 priority、enabled、bindings、commands 和任何自定义插件字段。

Solid 在响应式 createEffect 内部运行 createLayer()。在工厂内部读取的任何被追踪的信号或 memo 都会成为依赖项，因此当这些值改变时，钩子将取消注册并重新注册层。如果工厂不读取响应式值，层将保持稳定。

Solid 特定的层形状：

形状	描述
全局层	省略 `target`
局部 `focus-within` 层	设置 `target` accessor 并省略 `targetMode`
局部精确焦点层	设置 `target` accessor 和 `targetMode: "focus"`

当 target 存在且 targetMode 被省略时，使用 focus-within。
如果 target accessor 返回 null 或 undefined，注册会等待它解析。
传递局部 targetMode 而不传 target 会抛出异常。

`useKeymapSelector()`

useKeymapSelector() 是 Solid 的通用派生读取 API。它返回一个 Accessor<T>，因此您通过调用它来读取当前值：

const activeKeys = useKeymapSelector((keymap) => keymap.getActiveKeys({ includeMetadata: true }))
const pendingSequence = useKeymapSelector((keymap) => keymap.getPendingSequence())

activeKeys()
pendingSequence()

将其用于命令面板、按键提示 UI、leader 提示、状态栏或任何其他派生的 keymap 视图。

当底层宿主在更新过程中被销毁时，useKeymapSelector() 会返回先前的 accessor 值而不是抛出异常，以便订阅者可以在其所有者清理之前再渲染一次。如果宿主已经不存在，首次读取仍然会抛出异常。

`reactiveMatcherFromSignal()`

当插件字段期望 ReactiveMatcher 时使用此方法，例如附带的 enabled 字段：

useBindings(() => ({
  enabled: reactiveMatcherFromSignal(mode, (value) => value === "normal"),
  bindings: [{ key: "x", cmd: "delete-line" }],
}))

示例：packages/solid/examples/components/keymap-demo.tsx