# @bitakit/ui 中文文档

规范地址：https://npmcn.com/package/%40bitakit/ui/

版本：0\.2\.10
npm 元数据更新时间：2026-11-01T11:20:52.452Z
中文译文更新时间：2026-11-08T04:00:28.425Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bitakit/ui
原文对照：https://npmcn.com/package/%40bitakit/ui/?lang=original
项目主页：https://github.com/mvavesal/bitakit#readme
源码仓库：https://github.com/mvavesal/bitakit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：308 kB，156 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：10 个
- peer 依赖：react ^19\.0\.0，react-dom ^19\.0\.0
- 首次发布：2026-10-01T10:38:35.892Z
- 最新版本发布：2026-11-01T11:20:52.058Z
- 近 30 天下载量：2635（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

BitaKit(动作,服务,插槽,设置)和可选标准组件的回放绑定.

## 安装

```sh
npm install @bitakit/ui
```

也可以使用：`pnpm add @bitakit/ui`、`yarn add @bitakit/ui`、`bun add @bitakit/ui`

## README

# @ bitakit/ ui (英语)

无头 BitaKit 运行时间的回放绑定 。 可选 `./components` 条目提供 共享标准视觉组件; Core仍然独立于React和UI库. 自 0.2 起, 此套件只出口 React 绑定: 导入 `define*` 助手和其他核心名称 从 `@bitakit/core` (单位:千美元)`npx @bitakit/cli migrate` 移动现有进口.

## 第一个约束

在有生成的 BitaKit 提供者和已有的应用程序中 `counter.increment` 行动:

```tsx
import { Action } from '@bitakit/ui';
import { Button } from '@bitakit/ui/components';

<Action id="counter.increment">
  <Button />
</Action>;
```

行动提供标签 并守护着处决。 为首先界定这一行动,遵循 [小型反证课](https://npmcn.com/package/apps/docs/content/docs/concepts/actions.mdx)。 。 。 . 以下提供者和具有约束力的备选办法是参考材料.

## 提供者

`BitaKitRuntimeProvider` 每个配置挂载一次运行。 它拥有根 `ActionProvider` 在迁移过程中默认并重新使用现有的外部提供者。 Apps 渲染生成 `BitaKitProvider` 从 `src/bitakit.gen.tsx`,通过发现的 `config`; 数据 框架适配器添加导航和查询状态.

| Prop | 含义 |
| --- | --- |
| `config` | 生成的配置( E)`createBitaKitConfig()`),或明示的 |
| `additionalPlugins` | 添加到配置中的插件; 带有现有ID的条目将替换它 |
| `controls` | 例如,每个控件类型的推广名适配器 `{ button: (s) => ({ isDisabled: s.disabled }) }` |
| `notify` | `(message, kind)` 用于行动反馈的祝酒词 |
| `services` | 合同名称下的主办服务,例如 `{ auth }` |
| `translate`, (中文(简体) ), `labels`, (中文(简体) ), `ui` | 翻译、默认副本和标准视觉映射 |
| `actionOptions` | 拥有的选项 `ActionProvider`,例如 `shortcuts` |
| `isolateFailures` | 当插件启动失败时保持应用程序运行; 在开发中构建 |

在开发中,一个无法启动的插件与插件一起关闭 ,并有一个启动报告命名插件、原因和文件;一个页面 仍然需要其中一项服务 显示一个解释而不是崩溃。 生产失败 快点.

水分后, 提供者在文档元素上标记其启动, 用于不重复的工具 访问,例如 `npx bitakit check-page` 和浏览器测试 : `<html data-bitakit-runtime>` 实值 `starting`,则 `ready` 一旦初始启动完成(在开发中关闭插件) 列入)或 `failed` 当应用程序无法启动时。 服务器和水分标记从不携带.

## 捆绑动作

```tsx
import { Action, ActionButton, useAction } from '@bitakit/ui';
import { Button } from '@bitakit/ui/components';

<Action id="todos.add" input={draft}><Button /></Action>          // empty child: icon + title
<Action id="todos.open"><a /></Action>                              // link for actions with href
<Action id="todos.show-done" kind="toggle"><Switch /></Action>      // checked / onCheckedChange
<ActionButton action="todos.add" input={draft} as={Button} />       // sugar on <Action>

const add = useAction('todos.add', draft);
<button {...add?.props()}>{add?.title}</button>
```

`<Action id input kind?>` 将控制道具合并到它的孩子: 处理器是连锁的, 类 加入名称和 `disabled` 综合起来. `kind` 实值 `button`, (中文(简体) ), `link`, (中文(简体) ), `toggle`, (中文(简体) ), `choice` 或者说 `menuItem`; 默认为 `link` 用于使用 `href`,否则 `button`A. 成 就 函数接收控件. `useAction(id, input)` 返回已解析状态(`title`, (中文(简体) ), `enabled`, (中文(简体) ), `visible`, (中文(简体) ), `pending`, (中文(简体) ), `disabled`, (中文(简体) ), `checked`, (中文(简体) ), `value`, (中文(简体) ), `href`, (中文(简体) ), `status`, (中文(简体) ), `error`页:1 守卫 `execute(input?)` 和道具获取器 `props()`, (中文(简体) ), `linkProps()`, (中文(简体) ), `checkedProps()`, (中文(简体) ), `valueProps()` 财务报告和审定财务报表 `menuItemProps()`; 返回时 `undefined` 用于未注册的行动。 全体 绑定值还接受打入的引用,例如: `app.actions.todos.add`。 。 。 .

`useActionGroup(group, input?)` 返回一组可见的动作作为菜单的控制, 工具栏和行动作; `ActionMenu` 创建带有主机菜单组件的组. `ActionBoundary` 将儿童关在行动上. `useActions()` 公开列表 示意图.

## 阅读服务、设置和活动

```tsx
const todos = useServiceState('todos.list', (state) => state.todos, []); // reactive
const service = useService('todos.list'); // the instance
useEvent('todos.changed', (event) => {
  /* event.data */
});
const pageSize = useSetting('todos.pageSize'); // { value, ready, writable, pending, error, set, reset }
```

`useSetting(key)` 读取一个设置运行时间自有并写入它; 值是 确认值, `disabled` 封面不装入,只读并保存 。 布局和设置 主机使用 `useSettingsCatalog()` (来自每个插件的部分) `settings.ts` 财务报告和审定财务报表 `ui/settings/page.tsx`, (中文(简体) ), `useNavigation(slotName)` (捆绑导航项目外加路由器) 路径名称、链接和 `isActive`, (中文(简体) ), `useSlot(name, { payload })` (类型动作/组件/数据项、有效载荷、待取和出错)和 `useCurrentPage()` (当前插件页及其 `layout` 名称). 对话框动作名称 a 帧类型( e)`dialog: { component, kind: 'sheet' }`; 注册框架 `BitaKitRuntimeProvider` 结束 `dialogs={{ sheet: SheetFrame }}`两种没有注册框架的工作: `dialog` (默认,带有明显的标题)和 `command`中, shadcn 命令数字组构成 搜索调色板, 其内容以自己的搜索字段显示; 标题保留给 辅助技术.

`useServiceState(name, selector?, fallback?)` 订阅商店 服务曝光为 `state` (或 a 个) `subscribe`编号 :`getSnapshot` 并返回倒数,直到服务 它的主人准备好了. `useEvent` 订阅带有组件清理的运行时总线. `useBitaKitApp()` 返回已键入的应用程序外观( e)`app.services`, (中文(简体) ), `app.actions`, (中文(简体) ), `app.config`, (中文(简体) ), `app.has()`(三); `usePluginConfig(moduleId, path, fallback)` 读取 配置快照 .

## 插件用户界面

`<PluginPage pathname? fallback? unavailable? />` 使插件页面为当前路径注册 和通过 `params` (单位:千美元)`ui/pages/[id].tsx` 接收 `{ id }`(三); `<PluginSlot name payload? />` 调制 将组件插件放在插槽中。 被宣布的目标读取为拥有的活附属物; 遗留目标保留现有视图路径。 隐藏一个出口 从不解开它的条目. 两条道都保留了服务钩所用的全跑时准备障碍. `PluginSlot` 将有效有效载荷传递给每个部件。 行动和数据槽的使用 `useSlot` 编辑 拥有者制造器.

`<PluginSlot name payload? fallback? errorFallback?>{children}</PluginSlot>`数字 : `fallback` 调制 而不贡献; `children` 以道具方式到达每个贡献( 布局包) (第2页)。 对a `single` 插头, `useSlot` 只保留候选人 `selectSingle` 选择( 应用程序 `choose` 条目,应用程序自己的贡献,或唯一的候选人),报告 `ambiguous` 或者说 `choice-unavailable` 内 `diagnostics.reason` 与 `diagnostics.candidates`记录了一次领带, 并显示运行时间开始前的选定文件贡献;失败的用户 使 `fallback`。 。 。 . `SlotProps<'slot.id'>` 类型 `{ payload, children }`。从 `ui/providers` 包装应用程序 自动. `DialogHost` 财务报告和审定财务报表 `ConfirmDialog` 提交 `dialog` 财务报告和审定财务报表 `confirm` 行动 主机的对话框原始 .

## 键盘快捷键

词根 `ActionProvider` 绑定 `shortcut` 使用 [@tastack/hotkeys (英语)](https://tanstack.com/hotkeys/latest/docs/overview)按钮和菜单 安装与执行无关; `actionOptions={{ shortcuts: { scopes: ['global', 'editor'] } }}` 启动瞄准镜, `shortcuts: false` 禁用绑定。 隐藏、残废、待处理和内部 动作无法执行 。 除非 `allowInInputs: true`。 。 。 . `Mod` 指在其他地方对macOS和Control的指挥. 碰撞政策 保持第一次登记并报告冲突 `onError`。 。 。 . `StandardActionMenu` 显示快捷键; 其他渲染器可能使用 `ActionShortcutLabel`,然后是哪种格式 水分和不绑钥匙.

## 翻译

`const t = useTranslation()` 提供者内部 : `t('feature.key', { name: 'Ada' }, 'Fallback')`, (中文(简体) ), `t.has(key)` 财务报告和审定财务报表 `t.getCatalog(namespace?)`。钩子遵循运行时间翻译通知. 通过核心替换翻译集成 `translationService` 合同; 有 没有第二个地方商店。 软件包拥有的英语和德语信息 `locales/` 并且现在 导出为 `./locales/en.json` 财务报告和审定财务报表 `./locales/de.json`;用 `mergePluginMessages`,其中应用程序目录覆盖匹配的密钥.

## 构成部分和主题

见 [开发者主题合同](https://npmcn.com/package/%40bitakit/ui/THEME.md) 对于一个由 Shell 共享的主机主题, 设置, 快速搜索、本地认证/组织控制和Devtools,包括打字、边框 宽度,阴影,焦点和运动。 在生成的根 CSS 导入后定义符; 消费者应用不补丁单个插件选择器.

可选 `./components` 进口 `Button`, (中文(简体) ), `Input`, (中文(简体) ), `Field`, (中文(简体) ), `Label`, (中文(简体) ), `Badge`, (中文(简体) ), `Checkbox`, (中文(简体) ), `RadioGroup`, (中文(简体) ), `RadioGroupItem`, (中文(简体) ), `Dialog`, (中文(简体) ), `DropdownMenu`, (中文(简体) ), `Sidebar`, (中文(简体) ), `NavigationMenu`, (中文(简体) ), `Sheet`, (中文(简体) ), `Skeleton`, (中文(简体) ), `Tooltip`, (中文(简体) ), `Separator`, (中文(简体) ), `PageHeader`, (中文(简体) ), `AppBar`, (中文(简体) ), `StandardActionMenu`, (中文(简体) ), `ActionSidebarNavigation`, (中文(简体) ), `ActionNavigationMenu` 财务报告和审定财务报表 `standardBitaKitUI`。这些构成主机主题符号和 没有应用程序、设置或壳牌行为. `./theme.css` 导出共享主题符和 控制几何; 生成的应用程序导入它 `src/bitakit.gen.css`。 。 。 .

## 测试

`renderWithBitaKit(element, { plugins, config, services, ui })` 从 `@bitakit/ui/testing` 将元素挂载在内 `BitaKitRuntimeProvider`,包裹在 `act`,然后在 插头 `onStart`返回时返回 `runtime`, (中文(简体) ), `container`, (中文(简体) ), `events.recorded`, (中文(简体) ), `rerender(element)` 财务报告和审定财务报表 `unmount()`。 。 。 . `events.recorded` 列表 `{ type, data }` 每一次升起的时候, 包含启动, 形状 `mountPlugin` 记录. `plugins` 添加到 `config` (单位:千美元) 替换现有的身份证; `services` 是主机服务, 如假的 `auth`失败 以给定的启动错误开始拒绝, 并留下任何挂载 。 帮助导入 没有 DOM 执行: 安装 jsdom 的 `window` 财务报告和审定财务报表 `document` 作为全球第一,作为 `tests/support.mjs` 做,并通过自己的 `ui` 当标准原始人不被通缉时.

```js
import { renderWithBitaKit } from '@bitakit/ui/testing';

const view = await renderWithBitaKit(<PluginPage pathname="/notes" />, { plugins: [notes] });
await act(async () => view.container.querySelector('button').click());
assert.deepEqual(view.events.recorded, [{ type: 'notes.added', data: { title: 'Write tests' } }]);
await view.unmount();
```

无头服务、行动和事件不通过反应测试 `mountPlugin` 从 `@bitakit/core/testing`。 。 。 .

## 客户认证

`useAuth` 遵守登记 `AuthService` 并揭露它的快照加 `signIn` 财务报告和审定财务报表 `signOut`。 。 。 . `AuthBoundary` 处理待决、认证、非认证和错误渲染 通过主机提供的内容;它使用现有的导航绑定来登录. 没有 视觉依赖,不执行服务器授权. 见 [配置和适配器示例](https://npmcn.com/package/apps/docs/content/docs/reference/authentication.mdx)。 。 。 .

## 来源组织

-   `components/`数字 : `<Action>`, (中文(简体) ), `ActionButton`, (中文(简体) ), `ActionLink`, (中文(简体) ), `ActionMenu`, (中文(简体) ), `ActionBoundary`,对话框主机,插件页面和槽,标准原始 `components/primitives`。 。 。 .
-   `hooks/`数字 : `useAction`, (中文(简体) ), `useActionGroup`, (中文(简体) ), `useService`, (中文(简体) ), `useServiceState`, (中文(简体) ), `useSetting`, (中文(简体) ), `useSettingsCatalog`, (中文(简体) ), `useNavigation`, (中文(简体) ), `useSlot`, (中文(简体) ), `useEvent`, (中文(简体) ), `useBitaKitApp`, (中文(简体) ), `usePluginConfig`, (中文(简体) ), `useTranslation`, (中文(简体) ), `useAuth`。 。 。 .
-   `providers/`数字 : `BitaKitRuntimeProvider`, (中文(简体) ), `ActionProvider`,共享的背景和 `data-bitakit-runtime` 启动标记 .
-   `bindings/`: 键盘快捷键注册.
-   `utils/`数字 : `mergeProps`。 。 。 .
-   `testing/`数字 : `renderWithBitaKit`,则 `@bitakit/ui/testing` 条目( 需要) `react-dom`;没有输入DOM).
-   `types/`:主机UI合同和React演示文稿打字.
-   `index.ts`, (中文(简体) ), `actions/index.tsx`, (中文(简体) ), `components.ts`:未执行的公共出口.

Core 中不包含 React 导入或渲染器切入点; 此套件会增加 Core 的不透明度 有反应类型的演示文稿类型。 运行 `npm test --workspace @bitakit/ui`。 。 。 .

### 等待运行时间替换

`BitaKitRuntimeProvider` 使用Core的启动控制器进行故障快取和隔离政策. 更改配置等待上一个运行时间的完整合成清理, 包括 当中间配置被跳过时。 清理失败阻止了自动替换. `renderWithBitaKit(...).unmount()` 正在等待清理; 记录的事件包括 `runtime.lifecycle`。运行时状态通过 `runtime.lifecycle.get()/watch()`。 。 。 .

显示的动作项目 `item.action`; 将控件传给 `Action`, (中文(简体) ), `ActionButton` 或者说 `ActionLink` 以保存输出的映射输入。 分组仍然是合乎逻辑的查询. `PluginSlot` 将经验证的有效载荷传递给贡献的部件.

槽点接受 `entryKey` 以选择一个按键组件并只返回其可选条目 `when({ payload })` 与事件相符 装入 `item.key`; 输出过滤 从不解析共享条目. `PluginSlot` 转发已解析的有效载荷。 现有目录 也带有每页不透明 `boundary`,包括额外页面的继承.

输出仅跟随动作本身的条目引用 。 组件或数据槽不 当操作或演示文稿在服务变化后更新时再次打开; 动作 当它自己的动作之一改变时, 位置会再次变成 . `PluginSlot` 记住每项贡献 因此,一个记忆中的有效载荷可以避免他们父母的贡献.

`ActionControl.linkProps({ href })` 让一个渲染器修改一个 URL 用于其路由基数/ query,同时 保留安全的 URL 检查、 禁用 的 守护 和 一致 的 本地/ 客户 导航 .

### 东道主最新情况和检查

`useBitaKit().runtime.reconcilePlugins(nextPlugins)` 支持明显的相容插件 更新。 等待它从主机管理代码得到结果 。 它保存无关的服务例 并保持未受影响的页面/部件挂载. `useBitaKitReady()` 表示初步准备状态; 通过一个插件ID来观察该所有者 . `useService` 财务报告和审定财务报表 `useServiceState` 跟踪备妥实例 而不解开不变的来源. `PluginPage` 接受一个 `unavailable` 倒计时; `useSlot` 揭露其申报的拥有者 `phase`,将失败/锁定与 `pending`。 。 。 . 受影响的页面/预测可以重新挂载; 受影响的对话框在替换前关闭 。 提供者 配置道具更改仍然可以取代整个运行时间. 这不能保证文件- HMR 状态保留 .

```tsx
import { useRuntimeInventory } from '@bitakit/ui';
function RuntimeStatus() {
  const snapshot = useRuntimeInventory();
  return <output>{snapshot.live?.phase}</output>;
}
```

钩子读取了Core共享版本的库存,有稳定的快照. 它没有应用程序 数值. `live` 实值 `null` 服务器渲染和水分时, 因为运行时间只开始 在浏览器中;在水合之后,活状态紧随其后。 使用普通的动作/服务钩子进行交互操作. App 首选项和 Devtools 使用同样的目录;静态的 CLI 字段可能明确不可用.

### 隔离部件失败

`PluginSlot` 自动隔离每个组件。 健康兄弟姐妹仍被挂起;默认 倒置名插件/ slot 并使用现有的主机按钮进行重试 。 覆盖一个出口 与 `errorFallback={({ error, retry }) => ...}` 需要的时候. `SlotRenderError` 包含 `slot`, (中文(简体) ), `plugin`, (中文(简体) ), `contribution` 财务报告和审定财务报表 `cause`; 默认的 UI 从不打印原始原因或堆栈 。 汇报用途 现有提供者 `actionOptions.onError` 调用.

自定义 `useSlot` 渲染器可以将每个条目包入 `SlotErrorBoundary` 与 `slot`, (中文(简体) ), `plugin`, (中文(简体) ), `contribution` 财务报告和审定财务报表 `children`. 保持入门钥匙的稳定,并将边界置于出入通道内 控制系统。 明确重试或更改所有者定义/组件重排错误; 不相关 更新和等同的稳定有效载荷物体没有。 上下文重新验证/隐藏可能卸载出一个出错并丢弃其局部出错 。 重试不会重新启动服务或附加两次 .

此客户端提供边界使用 `react-error-boundary`; 它不处理槽有效载荷/装订 错误、 服务器渲染、 事件处理器或以后的合成失败 。 暂住住住持. 习惯的失败通常会传播。 核心生命周期和共享清单保持不变.

### 主机拥有的插件控制

运行时间提供者在内部注册 `pluginManagementAction` (单位:千美元)`runtime.plugins.change`(中文(简体) ) 在已有的根行动列表上启动后。 把它捆起来 `Action`编号 :`useAction` 财务报告和审定财务报表 `{ id, operation, expectedRevision, preserve }`。禁用标准确认 受影响的插件名称。 执行重新验证当前状态并安全翻译报告 反馈. `pluginChangeExplanation(runtime, preview)` 翻译打出的计划理由; 原始原因仍是诊断性的。 这一行动没有列入公共行动清单.

可选 `@bitakit/ui/components` 条目还输出标准卡和项目原始. 设置表面共享这些组件和中心主题; 通用根保持自由 视觉原始人.

## 常见问题

### @bitakit/ui 是什么？

BitaKit\(动作,服务,插槽,设置\)和可选标准组件的回放绑定\.

### 如何安装 @bitakit/ui？

在项目目录运行 npm install @bitakit/ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bitakit/ui 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bitakit/ui 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @bitakit/ui 可以商用吗？

@bitakit/ui 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bitakit/ui 的下载量有多少？

根据 npm 官方下载统计，@bitakit/ui 在 2026/10/08 – 2026/11/06 这 30 天内被下载 2,635 次，日均约 88 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bitakit/ui 还在维护吗？

最新版本 0\.2\.10 发布于 2026/11/01（7 天前）；至今共发布 12 个版本，其中过去 12 个月发布了 12 个；首次发布于 2026/10/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。