@ bitakit/ ui (英语)
无头 BitaKit 运行时间的回放绑定 。 可选 ./components 条目提供
共享标准视觉组件; Core仍然独立于React和UI库.
自 0.2 起, 此套件只出口 React 绑定: 导入 define* 助手和其他核心名称
从 @bitakit/core (单位:千美元)npx @bitakit/cli migrate 移动现有进口.
第一个约束
在有生成的 BitaKit 提供者和已有的应用程序中 counter.increment 行动:
import { Action } from '@bitakit/ui';
import { Button } from '@bitakit/ui/components';
<Action id="counter.increment">
<Button />
</Action>;
行动提供标签 并守护着处决。 为首先界定这一行动,遵循 小型反证课。 。 。 . 以下提供者和具有约束力的备选办法是参考材料.
提供者
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 当应用程序无法启动时。 服务器和水分标记从不携带.
捆绑动作
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,否则 buttonA. 成 就
函数接收控件. 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() 公开列表
示意图.
阅读服务、设置和活动
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 (英语)按钮和菜单
安装与执行无关; 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,其中应用程序目录覆盖匹配的密钥.
构成部分和主题
见 开发者主题合同 对于一个由 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 当标准原始人不被通缉时.
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 处理待决、认证、非认证和错误渲染
通过主机提供的内容;它使用现有的导航绑定来登录. 没有
视觉依赖,不执行服务器授权. 见
配置和适配器示例。 。 。 .
来源组织
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 状态保留 .
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 条目还输出标准卡和项目原始.
设置表面共享这些组件和中心主题; 通用根保持自由
视觉原始人.