组件接入
Qokit 共享组件、Pattern、Skin 与样式 Token 的公开集成契约。
组件接入
Qokit 使用“共享骨架 + Skin 配方”模型。外部集成方依赖组件的语义和交互契约,通过 Skin 和 Token 完成视觉适配。
2026-10-22 · 窄屏当前导航标签
PillTabs 支持可选的 scrollActiveTabIntoView,默认 false。水平页签在选中或尺寸变化时,将直接子项中激活的 PillTabLink 或 PillTabButton 滚入可见区域。只滚动标签轨道,不改变页面位置或键盘焦点;支持 LTR 和 RTL,使用即时定位,并兼容减少动态效果。垂直页签和未启用该选项的调用保持原行为。
2026-10-20 · 可视化选择卡片的独立操作
EditorVisualChoiceGroup 的选项支持可选的 accessory,用于独立的卡片菜单或名称编辑器。共享 RadioGroup 将其放在原生标签旁,管理卡片不会触发单选。可选的 afterOptions 在选项之后放置创建卡片等独立目录操作。宿主负责持久化、权限、校验,以及卡片替换或删除后的焦点。未提供附加操作的选项保留原结构和行为。
2026-10-17 · 共享工作台面板动效
EditorWorkbenchChrome 通过 BuilderWorkbenchFrame 渲染传入的两侧面板区域,与创作室和内容编辑使用同一面板骨架。宿主提供内容、显隐状态和宽度偏好。桌面网格轨道、面板透明度与位移动效共用 --qk-sidebar-motion-duration 和 --qk-sidebar-motion-easing;拖动时禁用过渡,减少动态效果时立即切换。
面板收起后保持挂载以保留草稿。共享骨架立即设置 inert 和 aria-hidden,平台样式在退出动效结束后才隐藏面板。紧凑面板在整个退出过程中保留浮层几何,宿主不得为面板外壳添加 hidden 或 display: none。显式临时展开的面板保留既有交互。页头选项在面板展开和收起时均可用;手机端的多个面板入口需要共用菜单时,使用 EditorPanelChoiceShortcuts.mobileMenu。
2026-10-17 · 按可用宽度计算编辑器默认值
useWorkspaceResponsiveProfile 接受可选的 onWidthChange(width),报告扣除横向内边距后、用于响应式判断的同一工作区可用宽度。使用稳定回调推导比例默认值,无须增加观察器。useEditorLayout 将 sharedWidths.limits 同时应用于宿主偏好和共享宽度存储;readEditorLayout 的第四个可选参数接受同一限制。现有调用方保留原有默认边界和行为。
2026-10-15 · 共享属性选择控件
有限设置统一使用 EditorStyleChoice 与底层 EditorChoiceControl。auto 模式将两至三个带图示的选项显示为分段组,较多选项通过 Portal 中的 ControlMenu 显示当前图示和名称;纯文字选项继续使用原生 Select。已有自定义值保留查看和选择路径。
Select 与菜单选项可通过 annotation 在名称后显示主题色圆点,并把本地化含义加入可访问名称;ControlMenu 的触发器也会在当前选项名称后显示该圆点,triggerAnnotation: null 可仅在菜单内保留标记。菜单模式选择已选中的可用项时,可通过 onReselect 接收回调。原生 Select 在名称旁直接显示本地化说明,hidden 可将占位项排除在展开列表之外。标记哪个值、选择后的行为由宿主决定,共享控件不推断继承关系或写入数据。
presentation="visual" 提供带名称的图示选择,presentation="toolbar" 用于四向文字对齐等熟悉的工具;后者是独立目标,不使用共享胶囊外框。原生单选、菜单键盘行为、焦点、禁用状态与主题 Token 由共享组件维护。宿主负责文案、可用值、保存和撤销。id 标识控件,ControlMenu 另支持 triggerId 与 disabled。
属性栏中的菜单、输入、折叠摘要与恢复操作共用字段高度,鼠标环境为 32px,窄屏和粗指针环境为 40px;字段图标统一为 16px,图示选择保持 8px 间距。EditorComponentSettings 的列数、密度、图片适配与比例复用同一图示选择,复杂版式继续保留结构预览。保存期间短暂禁用单选后,共享骨架恢复选中项的焦点,支持连续方向键编辑。
属性栏标签与图示名称使用 12px 辅助字级,数值、操作与分区标题使用 13px 字段字级。图示选项不叠加装饰外框,以轻量选中底色和居中名称标识当前项;键盘焦点保留焦点环。属性栏内的字体标本使用有上下限的紧凑字级。
2026-10-15 · 工作台表格响应式
WorkspaceDataTable 的 mobileLayout="records" 在窄容器内使用两列带标签的信息,主要名称和末端固定操作横跨整条记录。名称与标识允许两行显示,保留列名与选择控件的可访问性。使用 mobileLayout="scroll" 的比较表格继续保留列布局。
宿主工具栏已经提供排序等表头操作时,可传入 mobileHeader="labels",从移动布局和键盘顺序中移除重复表头控件;辅助技术仍可读取列名,桌面表头保持原有行为。默认值 "controls" 保留移动端自定义表头控件。
2026-10-14 · 编辑面板独立展开
WorkspacePanels 的 resolveWorkspaceResponsiveProfile、useWorkspaceResponsiveProfile 与 EditorWorkbenchChrome 支持可选的 panelPolicy="independent"。结合 BuilderWorkbenchFrame 和平台编辑皮肤时,非手机工作区保持两侧停靠;共享样式临时压缩实际显示宽度,保留记忆尺寸,画布适配剩余空间。有效工作区宽度不大于 720px 时继续使用手机任务切换。
宿主负责面板展开状态。传入自行测量的 profile 时,测量 Hook 与 Chrome 必须使用相同策略。省略 panelPolicy 时继续使用 "adaptive",保留原有宽屏、两栏和覆盖布局。
2026-10-10 · Pagination 圆点显示
@qokit/components/ui 的 Pagination 支持 pageDisplay="dots",用于紧凑的可视化选项切换。配合 layout="centered",箭头和 6px 圆点居中显示,每个圆点保留 32px 宽的点击区域。圆点颜色、悬停与键盘焦点共用主题 Token;PaginationSkin.dot 可适配指示点槽位。宿主提供 currentPage、totalPages、onPageChange 和本地化导航名称。pageLabel 为各圆点提供可访问名称;未提供时由 ariaLabel 与当前页、总页数组合。翻页只调用宿主回调。默认的 "numbers" 模式保留数字分页与 formatPageNumber。容器不超过 440px 时,数字页码收拢为当前页/总页数,保留上一页、下一页及可选跳页输入;圆点模式继续保持选项切换形态。
2026-10-09 · 内嵌 ColorPicker
@qokit/components/ui/ColorPicker 的 ColorPicker 支持 presentation="inline",在字段触发器下方原位展开编辑器。编辑区以有名称的分组留在文档流中,周围工作台继续可用,保留色板、HEX、透明度、渐变和重置能力。宿主应让该字段独占一行。受控值变化,包括撤销与重置,会同步到已展开的编辑器;离开字段时结束本次编辑。默认 "popover" 继续使用 Portal、点击外部关闭和 Escape 交互。
2026-10-07 · WorkspacePanelGrid
@qokit/components/patterns/WorkspaceLayout 的 WorkspacePanelGrid 将独立详情面板接续到当前较短的列下方。内容或容器尺寸变化时自动重排,不移动或重新挂载子节点,DOM 和键盘顺序保持不变;窄容器恢复单列。连续面板应放在同一个网格中,避免拆成固定行。指标、表格、成对字段和有先后关系的操作流程继续使用各自布局。
每个直接子节点是一张面板。需要跨列时,在该子节点的根节点设置 data-workspace-panel-span="full" 或数字列数。可选 skin 提供 root 槽和变量;--qk-workspace-panel-grid-gap 控制共享间距,--qk-workspace-panel-grid-max-columns 默认是 2。未启用 JavaScript 或不支持 ResizeObserver 时,保留普通响应式网格。
2026-09-30 · SelectionToolbar 无障碍支持
SelectionToolbar.ariaLabel 可选地为工具栏区域命名,计数仍作为实时状态消息。宿主提供本地化标签,并可通过 actionContent 组合共享的 EditorToolGroup 与 ActionMenu;权限校验和操作处理仍由宿主负责。
2026-09-10 · 工作空间身份标识
ProjectSwitcherProject.badge 接受可选的非交互 React 内容,显示在条目名称、未列出的当前上下文及文字触发器的名称旁。纯图标触发器保持紧凑;平台文字触发器在手机宽度隐藏标识,为空间名称保留位置。打开菜单后仍显示标识。宿主负责归属正确的数据、本地化文案和展示样式;省略此字段保持原有外观。
2026-09-08 · ProjectSwitcher 上下文与动作
ProjectSwitcher.currentWorkspaceId 可独立于 currentProjectId 标记所属工作空间;只有当前所在位置使用选中底色。ID 必须与 projects 中的条目一致。onActionSelect(action, event) 让宿主在菜单关闭后执行快捷入口的离开保护,省略时保留普通链接行为。创建入口使用普通菜单表面。可选文案 SiteHeaderCopy.projectSwitcherCreate、projectSwitcherWebsites 分别描述创建动作和当前工作空间的网站分组,不改变创作室产品名称。
2026-09-08 · EmptyState
EmptyState 在透明背景上居中组织可选装饰图标 icon、title、可选说明 description 和操作 action。默认 layout="section" 适合局部空状态,layout="workspace" 为业务区空状态预留更多空间。按钮直接传入 action(多个按钮使用 Fragment),由共享容器处理间距与长文案换行。标题使用 h2;定制样式通过 title skin 槽接入,不再依赖 strong 选择器。现有根 class 保留,支持 skin.vars 与 style。宿主继续负责本地化文案、权限、导航和创建逻辑;搜索无结果与错误保留各自的提示及操作。
2026-09-08 · SidebarNavigation
SidebarNavigation 在鼠标停留 180 毫秒或键盘聚焦后预加载同源路由;固定侧栏与弹出导航共享每 30 秒最多 8 个目标的额度。离线、隐藏标签页、省流量或 2G 网络时暂停预加载;下载、禁用链接、新窗口目标与同页锚点不预加载。导航与未保存离开保护保持原有契约。
2026-09-07 - AccountDropdown / SidebarProfile
AccountDropdown.usageSummary 是账户身份下方的可选摘要槽,由宿主提供真实积分、套餐用量及明细导航。也可传入 ({ environmentInfo }) => ReactNode,将共享的 ID 展开与复制控件放入摘要,此时底部不重复显示。摘要链接使用 role="menuitem",沿用菜单键盘行为与离开保护。平台头部将个人积分、套餐用量并排为两列,ID 信息在其下方展开;侧栏底部保留外观和语言。数据加载失败不显示为零,重新打开菜单时刷新。
AccountDropdown 新增可选 compact 和 preferences:紧凑模式隐藏标识符与创作历史,默认保留原有内容。账户菜单内的 Appearance、Language 使用 triggerRole="menuitem"。菜单支持键盘导航与焦点恢复,嵌套语言弹层独立处理 Esc。SidebarNavigation.searchEnabled 默认为 true,少量固定入口可设为 false。仅提供 href、不提供菜单的 SidebarProfile 在展开和图标模式下进入同一目标。
2026-09-07 - FormField / AdminEntityDialog / EditorWorkspace
表单字体层级统一,长标签与辅助信息自然换行,保留椭圆形态和品牌色。FormField 为组合控件提供分组名称;controlId 与内层输入框 id 对应,实现标签聚焦。SearchField 清空后恢复焦点。Segmented、ControlMenu 支持禁用选项,禁用的 ActionMenu 项不保留链接。忙碌按钮保持尺寸并显示指示器。AdminEntityDialog 校验必填、邮箱与 JSON,聚焦错误,防止重复保存,失败保留输入。EditorWorkspace 提供 ref.focusControl(element),先展开隐藏面板再聚焦字段。减少动态效果时关闭控件过渡。 WorkspaceDialog 的长内容独立滚动,标题和操作区保持可见;短弹窗在移动端按内容高度展示。
2026-09-07 · WorkspaceLocationSync / ProjectSwitcher
路由完成切换后,WorkspaceLocationSync 关闭临时的空间选择面板,目标页面直接显示功能菜单;搜索和分组偏好继续保留。侧栏范围名称与上下文说明分两行显示,顶部切换器的长名称在按钮内省略。
2026-09-07 · 统一工作台导航与 Qokit 圆润风格
WorkspaceNavigationDock 在桌面复用宿主侧栏及权限,通过 items、fallback、className 和 onClickCapture 接入,不重复加载会话。展开、图标和隐藏状态共用已有偏好;860px 及以下使用统一抽屉。PlatformHeader.leadingContext 同时进入 EditorHeader,保留工作空间和项目切换。保留椭圆按钮及圆润内容表面,去掉重复框线。
桌面点击菜单按钮完全隐藏侧栏,再次点击恢复上次可见模式。拖动菜单按钮或侧栏边缘,在隐藏、仅图标和展开之间吸附切换;左右方向键遵循文字方向。取消拖动不改写已保存偏好,手机继续使用导航抽屉。
Next 布局在 Suspense 下挂载一次 WorkspaceLocationSync。useWorkspaceQueryState(key, defaultValue, validate) 返回 [value, setValue, ready];useWorkspaceQueryRecord(key, defaults, validators) 仅恢复显式声明的平面筛选。凭证与正文草稿不得写入 URL。WorkspacePage 恢复有容量限制的会话滚动位置;内层滚动区使用 data-workspace-scroll-region 和 WorkspaceScrollRestoration。浏览器支持可取消的原生前进/后退时复用离开保护,不插入历史记录;其他浏览器保留原有回退。AdminEntityDialog 保存失败及父页面重渲染后保留输入;版本与保存结果仍由宿主负责。
管理文字使用固定层级:页标题 20px/650,分组标题 16px/600,正文和导航 14px,标签 13px,辅助说明 12px。--qk-workspace-body-ink 与 --qk-workspace-active-ink 派生自已有平台颜色。
椭圆主按钮保留 Logo 蓝原色 #4695D8,深浅主题下均使用白色文字、图标和加载指示器。悬停保留既有轻微提亮;次要按钮和危险按钮继续使用各自的语义颜色。
下拉菜单与工作空间切换器共用 --menu-option-font-size(14px)和 --menu-option-font-weight(500),行高为 1.45;选中项字重 600,辅助信息 12px/400。WorkspaceNavigationDock 在鼠标悬停或键盘聚焦时预加载同源目标,并限制去重记录数量。导航仍使用既有离开保护与宿主路由。
2026-09-07 - ColumnLayout
桌面管理宿主的 ColumnLayout 使用贴边导航、独立内容滚动区和吸顶页面工具栏铺满视口。WorkspacePage 使用平整分区及共享控件圆角 Token。860px 及以下保留导航抽屉,关闭的抽屉不可交互。属性和业务行为不变。宿主应去掉重复外部留白,将阅读宽度限制放在表单内容上。
导入入口
import { Button, Card, Dialog, IconButton } from '@qokit/components/ui';
import { PlatformHeader, SiteFooter } from '@qokit/components/patterns';
import { platformButtonSkin } from '@qokit/components/skins/platform';
import { siteCardSkin } from '@qokit/components/skins/site';| 入口 | 用途 |
|---|---|
@qokit/components/ui | Button、Card、Dialog、Menu、Pill 等基础组件 |
@qokit/components/patterns | Header、Footer、工作区、表格、资源和 AI 助手等组合 |
@qokit/components/skins/platform | 平台与工作区视觉配方 |
@qokit/components/skins/admin | Admin 视觉配方 |
@qokit/components/skins/site | 生成站点视觉配方 |
公共职责边界
PromptPanel 接受可选的 referenceReader 和本地化 referenceCopy 属性。读取器通过异步 file(File, AbortSignal) 与 website(url, AbortSignal) 返回提取后的 contentExcerpt 和 truncated 标记,认证及 API 访问由宿主负责。组件管理读取、预览、重试和移除;有效网址无提示文字时由 referenceCopy.websitePrompt 补充请求,格式错误使用 referenceCopy.errors.url 并阻止读取。网址尚未读取或正在读取时提交会等待最新内容且只提交一次;输入变化或读取失败会取消待提交操作,重试不会恢复旧提交。文件须就绪后才能提交。完整网址在粘贴、失焦或按 Enter 时自动读取,初始网址也会读取并复用进行中或已完成结果;失败提供明确重试。编辑或移除网址会取消旧读取并清除结果。未提供读取器时继续原生提交,不做异步引用处理。
引用摄取于 2026 年 9 月作为可选且向后兼容的组件能力加入。
骨架组件保证:
- DOM 与语义标签;
- ARIA、键盘、焦点和 disabled 行为;
- 状态与基础交互;
- 稳定默认 class;
- 具名 Skin 槽位。
Skin 可以:
- 为
root、header、body、item、action等槽位增加 class; - 通过
vars传入 CSS 变量; - 使用组件已公开的 tone、layer 或视觉适配开关。
Skin 不得请求数据、改变 DOM、持有业务规则或绕过可访问性行为。
生成元素内容
生成的自定义区块继续在 Schema v2 中使用已注册的 html-* 元素,不使用可执行 HTML 或新块类型。自 2026 年 9 月起,@qokit/site-schema 提供 bindSiteModuleContent、updateSiteModuleBoundContent 和 forkSiteModuleContentBindings,用于语言内容绑定。内容路径保存在模块中,访客文案保存在语言内容映射中,更新沿用撤销与保存事务;复制或跨块移动元素时必须派生绑定,避免改变来源。
可选的 extensionRequirements 记录未解决的运行时需求,并非安装清单或权限授予。createSiteExtensionHandoff 导出不可执行的 v1 开发请求;发布可运行站点前必须解决这些需求或经审核明确排除。
表单控件
共享表单使用 FormField 关联标签、说明、必填元数据、错误和控件 ID。文本控件使用 Input,多行内容使用 Textarea,选择控件使用 Checkbox、RadioGroup 和 Switch;既有 Select 与 SearchField 使用同一尺寸和状态契约。
import { FormField, Input } from '@qokit/components/ui';
<FormField label="Site name" description="Up to 60 characters" error={errors.name} required>
<Input name="name" value={name} onChange={handleChange} />
</FormField>;FormField 通过 id、aria-describedby、aria-invalid 和 required 把标签、说明与错误关联到唯一子控件。不要再用额外的 <label> 包裹共享控件。
Input、Textarea、Select 与 SearchField 支持 sm、md 和 lg 三种尺寸,对应 40px、44px 和 48px。单行控件默认使用 pill 形状;Textarea 始终使用共享的多行圆角。各交互和错误状态均来自共享 Token。
迁移期间仍可使用旧的 .qk-field 契约;新接入应使用共享组件和具名 Skin 槽位。
列表选择
自 2026 年 9 月起,列表可把 useWorkspaceSelectionMode({ enabled, resetKey, onClear }) 与 WorkspaceFilterToolbar.selection 配合使用。该 Hook 初始未激活,在范围或权限变化时重置,并区分清空所选 ID 与退出批量模式;范围键应包含集合、语言、分页和筛选。
仅在批量模式激活时传入 WorkspaceDataTable.selection,网格和移动端复选控件使用同一模式。工具栏负责通用选择操作,使用方提供本地化文案、可选 ID 和经过权限检查的领域操作。可选的 actionContent 可承载额外 ARIA 语义,但不替代通用控件或确认。只读列表不显示批量模式,文件选择器和提案审核保留各自语义。
这些新增能力可选且向后兼容;表格选择仍由使用方显式控制。
数据卡片
DataCard 提供头部标题与 headerAction、主体内容与可选强调值 value、底部说明 footerText 与 footerAction。主体的其他信息放在 children。density="default" 为 144px 最小高度、20px 内距,density="compact" 为 112px 最小高度、16px 内距;内容较多时卡片自然增高。variant 使用共享 Card 的 surface、muted、state 表面。使用方选择共享规格,不在路由 CSS 中覆写高度、内距或数字字号。
卡槽中的按钮和链接使用共享 UI 控件。带操作卡槽时,卡片根节点保持非交互;整卡可点击时,不再放入嵌套操作。MetricCard 复用同一骨架,并保留 label、detail、语义 tone 与可选小图。
import { DataCard, MetricCard } from '@qokit/components/patterns';
import { Button } from '@qokit/components/ui';
<DataCard
title="Published"
value={24}
headerAction={<Button size="sm" variant="ghost">View</Button>}
footerText="Up 3 from last week"
footerAction={<Button size="sm" variant="secondary">Details</Button>}
density="compact"
/>;
<MetricCard density="compact" label="Published" value={24} tone="success" />;平台 Header 与 Footer
Logo 默认显示静态图片。motion="breathe" 初始保留尺寸,进入视口后随页面加载绘制:加载中在 4.8 秒内缓慢接近约 80% 并停住,收到浏览器 load 事件后从当前画面用 900 毫秒平滑收尾。若开始时页面已加载完成,则直接以 1.8 秒柔和入场,不额外等待。这里的比例是动效阶段,不是真实资源加载百分比;异步业务请求不由 load 覆盖。使用一次加载事件、可见性观察和 CSS 动画,无轮询或逐帧 React 更新。motionVisibilityDelayMs 默认为零。motionOnceKey 在同一文档内跨重新挂载共享播放记录,平台页头、页脚使用独立标识;站内切页、主题切换和滚回不重播,整页刷新后重置。减少动态效果、禁用 JavaScript 或缺少可见性观察能力时直接显示静态 Logo。motion="reveal" 继续作为兼容别名。
PlatformHeader 是无业务状态的 Header 骨架。PublicPlatformHeader 在它之上组合品牌入口、公共导航、语言、主题、登录、“立即体验”和移动菜单,平台匿名状态与文档站直接复用该组合。
PlatformHeader.autoHideOnScroll 默认为 false,PublicPlatformHeader 默认启用。页面向下滚动时隐藏头部,向上滚动或接近页顶时恢复;头部菜单打开或焦点位于头部内时保持显示。工作区与编辑器头部保持常驻。
PublicPlatformHeader.workspaceAction 可传入 { href, label },提供已登录访客返回工作区的入口。它替换桌面登录图标,并在手机菜单按钮旁直接显示;此时手机菜单不再显示匿名账户操作。登录状态由宿主判断。平台首页使用轻量的本地会话检查,在焦点或存储变化后更新,并在品牌链接保留 ?view=public,确保明确查看官网后刷新也保持官网。
公共导航通过 buildPublicHeaderNavItems(copy, links) 统一生成“资源 / 价格 / 新闻”。接入方只解析当前应用的站内、文档站和平台 URL,不应重复定义菜单顺序或文案。登录后的平台 Header 也使用同一生成函数。
<PublicPlatformHeader
copy={headerCopy}
links={{
brandHref: '/',
resourceCenterHref: '/resources',
userManualHref: 'https://docs.qokit.com/manual',
developerDocsHref: 'https://docs.qokit.com/developers',
changelogHref: 'https://docs.qokit.com/changelog',
pricingHref: '/pricing',
newsHref: '/news',
loginHref: '/login',
studioHref: '/studio'
}}
/>底层 navItems 仍支持 link、scroll 和 menu。menu 桌面端支持点击、键盘、Escape 和点击外部关闭,移动端由 MobileHeaderMenu 展开为链接分组。
SiteFooter 是 Footer 骨架;平台与文档站使用 PublicPlatformFooter 统一组合外层 Shell、品牌入口、链接、主题和语言控件。跨域接入通过 resolveCompanyHref 把相对平台链接转换为绝对地址。
<PublicPlatformFooter
brandHref="https://qokit.com"
copy={footerCopy}
resolveCompanyHref={(href) => `https://qokit.com${href}`}
/>业务应用不得复制 Header、Footer DOM 或公共导航数组;需要不同视觉表现时使用 PlatformHeaderSkin、SiteFooterSkin 或对应平台 Skin。
兼容策略
- 新增可选属性和 Skin 槽位属于向后兼容变更;
- 删除属性、修改默认语义或改变 DOM/键盘行为属于破坏性变更;
- 破坏性变更必须进入 Changelog,并提供迁移示例;
- 不要依赖未公开的内部 class、目录或路由结构;
- 两个以上接入点需要相同覆写时,应提升为公开 Skin 或 Token。
全屏编辑
EditorWorkspace 组合全屏对话框、焦点管理和响应式面板。通过 dirty 确认是否放弃修改,通过 busy 阻止保存中退出,通过 onSave 响应 Ctrl/Cmd+S。权限、数据、保存和发布由宿主负责。
workspaceNavigation 接入宿主的统一业务导航,并复用 EditorWorkbenchChrome:桌面展开导航时让出内容空间,手机使用统一抽屉。它与文档结构面板 navigation 分别承担业务导航和编辑工具,导航继续使用宿主的权限与离开保护。
view / onViewChange 统一切换 edit、focus、preview,不替换正文编辑器。preview 提供预览,previewPanel 复用已有面板。layout 支持 writing、structure、canvas;storageKey 只记忆面板宽度与折叠偏好,不存储正文。
onSaveAndClose 在保存确认成功后返回 true,失败返回 false;宿主已导航返回 handled,业务校验还需用户决定则返回 pending。失败时保持编辑器打开。只有宿主保留草稿时才使用 closeBehavior="collapse"。EditorSaveStatus 展示宿主确认的状态;现有工作区也可组合 EditorViewControls、EditorLeaveDialog 和 useEditorLayout。
键盘迁移:Segmented 只占一个 Tab 停靠点,通过方向键及 Home / End 切换选项。Dialog 尊重子浮层对 Escape 的处理;编辑器随后先退出专注或预览,再处理关闭。LivePreviewToolbar.exitControl 可接入共享视图控件。保存快捷键调用宿主,发布与权限仍由宿主负责。
import { EditorWorkspace } from '@qokit/components/patterns';
<EditorWorkspace
open={open}
title={title}
dirty={dirty}
busy={saving}
onClose={closeEditor}
onSave={saveDraft}
onSaveAndClose={saveDraft}
saveState={saveState}
layout="writing"
storageKey="article"
preview={preview}
navigation={structure}
inspector={properties}
actions={saveActions}
>
{editor}
</EditorWorkspace>SidebarToggleSlot
SidebarToggleSlot 把现有侧栏折叠按钮放到工作区页头,每个工作区配合一个左侧栏使用一个插槽。展开状态、快捷键和移动抽屉仍由 SidebarNavigation 管理;未提供插槽时保留原位置。移动抽屉也由页头按钮关闭,关闭后焦点返回同一按钮。
EditorSaveButton.showIcon 在文字旁保留保存图标,iconOnly 将按钮收成图标并保留操作与状态的可访问名称及提示。编辑器宿主可使用 useCompactWorkspaceHeader(),在宽裕布局显示图标和文字、紧凑布局只显示图标;EditorStatusAction.iconOnly 使用相同规则并保留问题数量。
EditorHeader
EditorHeader 将宿主的 Logo、头像和全局菜单保留在当前编辑器中。startControl、endControl 分别控制左右面板,center 放视图命令,actions 放保存操作。PlatformHeader.editorActions 复用响应式导航、语言和主题控件。onNavigate 必须先处理未保存内容,再执行导航回调。窄屏顶栏分为两行,子菜单优先处理 Escape。
WorkspaceHeaderPortal.startControl 和 endControl 将管理页的面板开关放入宿主对应槽位。宿主除标题、状态和操作外,可选提供 startTarget 与 endTarget。文件库和单文件工作区使用 workAreaControls;文件预览保留完整页头,持续提供对象身份、返回操作和面板入口。ProjectWorkspace 统一负责内容和文件的左侧导航与对话切换。文件库通过 useProjectResourcePanel 登记已记忆的资源面板尺寸,通过 ProjectContentTools 挂载导航,仅通过 ProjectToolbar.endControl 提供右侧详情开关。项目各业务区域的对话共用左侧面板区域与内嵌输入框;紧凑布局下,资源、对话和详情面板互斥。
EditorNavigationMenu
EditorNavigationMenu 将宿主完整的 SidebarNavigation 放入覆盖式抽屉,保留权限和项目上下文,不挤动画布。语言与主题位于底部,子菜单优先处理 Escape。专注与浏览器全屏相互独立;导航会等待进行中的保存,并保护未保存草稿。
WorkspaceNavigationMenu / WorkspacePageHeader
全局导航使用 Mac 的 Command+\ 或 Windows/Linux 的 Control+\,在创作室内也可独立使用。T 与 Shift+T 保留编辑布局功能;快捷键会忽略可编辑目标、输入法组合输入、重复及已处理事件。 按钮提示和 aria-keyshortcuts 显示组合键;全局导航不再占用单独的 T。
登录后的工作区通过 PlatformHeader.workspaceActions 在所有宽度共用账户和导航区,WorkspacePageHeader 统一标题与操作。WorkspaceNavigationMenu 展示当前侧栏,保留权限和业务上下文;EditorNavigationMenu 保留为兼容别名。Studio 保留自己的任务工具栏。公共头部沿用现有表现。
WorkspaceNavigationMenu.footerLinks 提供直接跳转的图标入口。footerMenus 接收有序的 WorkspaceNavigationFooterMenu,每项包含标签、图标和链接条目(支持 separatorBefore)。平台导航承载官网首页、价格、模板和新闻,书本图标的“帮助与支持”菜单承载使用手册及联系支持。未传 footerMenus 时仍兼容单个 footerMenu。桌面菜单使用 ActionMenu placement="top" portal 向上展开并限制在视口内,手机端使用底部弹层。展开时控件排成一行,图标模式下纵向排列,手机端侧栏控制直接关闭导航抽屉。每个图标保留可访问名称和提示。profile 在编辑器导航和抽屉底部显示用户名、套餐及账户上拉菜单,常驻侧栏已有账户时不重复渲染。未传底部链接与菜单时保留原有偏好与全屏操作。
底部菜单条目的 newTab 为资料类入口设置 target="_blank" 和 rel="noopener noreferrer",骨架同时添加右侧箭头及本地化读屏提示;其他条目继续在当前页导航。官网首页、价格、模板、新闻、使用手册及联系支持使用新标签页,保留当前工作区。明确查看官网的首页链接保留 ?view=public,跳过已登录用户的默认跳转,刷新后也继续显示官网。
WorkspaceNavigationGuard 通过 dirty、busy、error 和可选的 onSave 保护全局导航。保存确认成功并返回 true 后才能离开,失败保留草稿。Language.onBeforeChange(apply) 允许宿主通过同一保护延后语言切换。保存期间禁用表单字段。
桌面导航保留展开和图标模式,并增加自动隐藏。常驻侧栏与抽屉共享搜索和分组状态。精确指针在导航边缘停留 300ms 后临时唤出,离开 320ms 后收回;点击后保持展开。触控与键盘保留明确入口。Dialog 默认使用 modal={true} 和 autoFocus={true};悬停预览将两者设为 false,保留原输入焦点与滚动。
EditorViewControls
编辑与专注使用同一个双向按钮:编辑时显示“专注”,专注时显示“编辑”。点击或按 T 切换,E 仍可直接返回编辑。窄屏保留切换按钮,预览、全屏和附加操作收进更多菜单。
EditorViewControls 将编辑/专注与屏幕全屏分开控制。预览为独立开关,关闭后返回之前的工作模式;自定义退出动作通过 useEditorWorkMode 保留该模式。原有 edit/focus/preview 值继续有效。预览入口改为带 aria-pressed 的 button,不再是模式组内的 radio。屏幕全屏由用户点击进入,应用根节点包含导航与弹层;浏览器不支持时隐藏入口。
Language / Appearance
Language 与 Appearance variant="menu" 支持可选的 layout="row",同一行显示标签、当前值和箭头。默认紧凑布局及语言切换保护保持兼容。SiteHeaderCopy.helpResources 与 contactSupport 可选提供工作区帮助入口文案。
requestWorkspaceNavigation
有侧栏开关的页面不再显示额外的头部菜单按钮,收起和手机布局也遵循此规则;编辑器及无侧栏页面保留入口。从 @qokit/components/patterns/WorkspaceNavigation 导入 requestWorkspaceNavigation(returnFocusTarget?) 和 useWorkspaceNavigationState():请求切换已注册的抽屉,无可用抽屉时返回 false,可选元素用于关闭后恢复焦点。显示备用入口前检查 .available。请使用既有开关或此 API,不再依赖已移除按钮的 DOM 位置。
WorkspacePanelReveal
全局导航使用菜单图标,编辑工具使用左右分栏图标。useWorkspacePanelReveal({ temporary: true }) 在专注中支持点击和键盘临时打开工具;toggle(trigger?) 和 close(true) 保留已保存的布局和工作模式,并在关闭后恢复焦点。屏幕边缘唤出全局导航,工具只响应自身按钮附近的悬停。预览隐藏编辑面板开关,提供“返回编辑”,恢复此前的编辑模式。
EditorViewControls / 显示模式
EDITOR_VIEW_SHORTCUTS → Tooltip + aria-keyshortcuts
EditorHeader 同时管理 EDITOR_TOOLBAR_SHORTCUTS:Command/Control+S 调用可见的 EditorSaveButton,Shift+P 打开 EditorStatusAction shortcut="publish" 的发布设置或检查,Shift+M 打开编辑工具菜单。快捷键调用与点击相同的可用控件,正式发布仍需在面板内显式操作。只有当前可见头部响应;子菜单和弹窗打开时、输入法组合输入或重复事件中不响应,普通输入框内仅允许保存组合键。提示和 aria-keyshortcuts 共用定义。自定义 toolsControl 在触发按钮上设置 aria-keyshortcuts={EDITOR_TOOLBAR_SHORTCUTS.tools.aria};ActionMenu.triggerKeyShortcuts 只提供属性及共享提示,不自行注册全局快捷键。
面板快捷键统一为 Shift+A 增加、Shift+L 页面/图层、Shift+K 对话、Shift+C 内容、Shift+D 设计、Shift+G 全站风格。CMS 在相应入口可用时提供 Shift+S 设置、Shift+E SEO、Shift+H 历史。EditorChoiceControl/EditorViewTabs 选项及 ActionMenu 操作通过 shortcut 元数据共用提示;EditorPanelChoiceShortcuts 和 EditorViewControls.compactActions 在控件收进菜单后保留原宿主操作。自定义 EditorPanelShortcuts.commands 可注册同一组操作,不渲染第二套控件。隐藏或 inert、禁用、预览和浮层限制保持有效;同一工作区的手机非模态侧栏允许继续切换面板,菜单和模态弹窗仍会拦截快捷键。未按 Shift 的既有编辑快捷键继续使用原行为。
| 显示模式 | |
|---|---|
E | 编辑 |
T | 编辑 ↔ 专注 |
V | 预览 / 返回编辑 |
F | 进入全屏 / 退出全屏 |
仅当前编辑器响应;输入文字、输入法组合、持续按键及子对话框或菜单打开时,不切换模式。
PlatformHeader.workspaceNavigation
PlatformHeader.workspaceNavigation 将全局导航放在 Logo 前,workspaceActions 与 editorActions 保留账户操作。普通工作区复用已有侧栏开关,编辑器的右侧工具开关位于头像之前。窄屏上行放导航、品牌、标题与头像,下行放编辑工具与保存;DOM 顺序同步布局,继续使用无边框磨砂。
2026-09-06 - EditorHeader.preview / EditorViewControls.returnView
EditorHeader.preview 仅显示 center,收成无边框的精简预览工具条;Logo、账号、保存和面板入口保持挂载但隐藏。宿主使用独立 LivePreviewToolbar 时可隐藏编辑头部,通过 EditorViewControls.returnView(edit 或 focus)恢复原工作模式。保留可访问的返回与独立全屏操作;网站自身的页头继续显示。
2026-09-06 · Builder / CMS
Builder 与 CMS 内容编辑通过 BuilderWorkspace、EditorCatalog 和 EditorComponentSettings 复用工作台面板、插入图示及样式设置。预设一次应用关联设置并保留已有内容,保存与撤销由宿主负责。工作台控件跟随平台主题,正文渲染跟随站点主题。
2026-09-07 · WorkspaceAssembly
WorkspaceAssembly 标记离开的卡片和进入的工作区,不增加布局盒子。依赖直接子元素定位的宿主,应把 workspaceAssemblyAttributes(part, index, phase) 放在原有 DOM 元素上;EditorHeader.assemble 与 BuilderWorkspacePanels.assemble 已提供编辑器头部和面板标记。
仅在创建成功后调用 await startWorkspaceAssembly(navigate, destinationPathname)。它截取可见区块、执行一次导航,再于最长 720 毫秒内拼入目标工作区或对应加载骨架。目标必须包含进入阶段的 canvas 标记;通过 useWorkspaceAssemblyPending() 保持该加载界面挂载到快照归位,并在此期间预加载编辑器数据与代码。减少动态效果或浏览器不支持时直接导航;过慢或中断的过渡会释放快照并继续导航。标记本身不会让编辑、刷新或历史导航产生动画。临时样式和清理由共享模式负责,创建错误、幂等及加载状态仍由宿主管理。
服务端页脚 · 2026-09-07
SiteFooterLayout 接受明确的 locale 和单语言 copy。服务端组件输出共享页脚结构;主题、语言控件和二维码弹窗仍作为客户端组件运行。原有 SiteFooter、PublicPlatformFooter 接口继续保留。
import { SiteFooterLayout } from '@qokit/components/patterns/SiteFooter';
<div className="qk-platform-footer-shell">
<SiteFooterLayout locale={locale} copy={footerCopy} />
</div>跨域链接先在服务端归一化到 copy.companyLinks;通过 controls 自定义交互控件槽。
EditorHeader.titleControl / FloatingAssistant.presentation
EditorHeader.titleControl 与 EditorWorkspace.titleControl 可将纯标题替换为共享项目菜单。保留描述性的 title 作为工作区标识,导航继续经过现有未保存更改保护。FloatingAssistant.presentation="embedded" 在宿主面板内渲染有名称的区域,省去浮动入口和遮罩;默认仍为 floating。宿主负责位置与显隐,对话状态和权限继续由助手管理。
2026-09 · 管理工作区
WorkspacePage 和 WorkspaceLayout 接受 variant:overview、list、detail、settings 或 editor。WorkspaceFormFooter 统一宿主提供的 actions、message、tone 和 busy 反馈位置,不负责保存数据。
窄屏 WorkspaceDataTable 和 AdminDataTable 默认显示带字段标签的记录,保留选择、自定义表头与操作。需要列对齐的比较矩阵使用 mobileLayout="scroll"。WorkspaceFilterToolbar 先放搜索与筛选,再放排序和视图控件。侧栏标题使用 h2,页面保留 h1。
2026-09-08 · Task focus
useSidebarTaskFocus(active) 在专注任务期间临时隐藏导航,退出时恢复先前显示方式;任务期间用户主动修改导航模式时,以用户选择为准。自动隐藏不会改写已保存的偏好。
新增 API 参考(英文,译文待同步)
EditorHeader.contextMode="title" displays the editor's own titleControl instead of the host workspace picker. The default "host" behavior is unchanged; navigation, brand, account controls and leave guards retain their existing ownership. Hosts supply responsive placement for their title control.
EditorViewControls.focusInMenu shows a labelled preview action and moves focus mode into the shared menu. Its default remains false; view shortcuts and returning from preview keep the existing behavior.
EditorViewControls.toolsControl replaces the fallback menu with a host-owned tools control. Hosts retain its accessible trigger, menu state and actions; view buttons and keyboard shortcuts keep their existing behavior. 创作室 uses this slot for its complete editor tools menu beside Add, Layers and Preview.
EditorViewControls.responsiveLabels displays text beside focus and preview icons above 720px, reserving space for both focus labels. At phone widths the labels are hidden while accessible names and tooltips remain. EditorSaveButton.showStatusLabel displays saved/saving status or a retry action when state is provided; it reserves label space across states. Both options default to false.
ResizablePanels.middlePanelProps forwards section attributes such as inert to the middle panel, matching the existing side-panel attribute slots. An editor can keep its canvas mounted while preventing keyboard and pointer interaction when a compact conversation view covers it. Hosts still control panel visibility and restore focus when switching views; the prop does not unmount content.
contextAfter places editor-specific scope controls after the host project picker, preserving their DOM and keyboard order. The host retains project navigation and leave guards; the editor owns page and content-language selection. Hosts may adapt the responsive layout to put this context on its own row.
Editor tool palettes can use Dialog with keepMounted to preserve search and form state while closed. Closed dialogs immediately become inert, hidden from assistive technology, and leave the focus stack, including during a visual exit transition; the default still unmounts their content. Pair nonmodal palettes with DialogPanel to reuse the global overlay surface. Toolbar accepts a DOM ref for bounded positioning while retaining its shared arrow-key navigation.
useFloatingSurface from @qokit/components/patterns/FloatingTools supports defaultHeight: 'auto' for content-sized palettes. Keep the host body shrinkable with internal scrolling; the hook caps the surface to its workspace bounds and observes size changes. Moving an automatic palette stores its position without freezing the measured height. Resizing explicitly stores a fixed height, including across reloads; reset() or Home on a movement/resize handle restores automatic sizing. Numeric defaultHeight retains the existing fixed-height behavior.
FloatingToolPanel composes the shared DialogPanel, TreeToggle, pin button, tooltip and close button. Place it inside a nonmodal Dialog; the host controls pinned, collapsed, their callbacks and document operations. Pinning keeps the palette open after an operation; it does not lock its position. The title and header whitespace accept useFloatingSurface().dragHandle, while buttons, menus and inputs never initiate dragging or folding. Double-click the title or whitespace to fold; the explicit fold button supports keyboard and touch. Folding hides the body without unmounting it, preserving searches and tree state. Pass the same collapsed value to useFloatingSurface to retain the expanded height while moving the folded header. Optional actions and skin slots reuse the same structure; styles stay in the shared stylesheet.
Optional FloatingToolPanel.viewKey adds a short opacity transition when the active tool changes, without replacing its body instance. Ordinary parameter updates do not animate. Opening, closing, unfolding and pin feedback share the existing motion Tokens and respect reduced motion. Dragging stays direct; useFloatingSurface coalesces pointer movement to one geometry update per animation frame and saves the final position on release. Browsers without discrete display transitions close immediately.
Unified editors pass focus={false} to omit the separate Focus control. primaryActions accepts shared tool buttons before Preview; onTogglePanels handles T, and onToggleAllPanels handles Shift+T. 创作室 uses T to cycle from visible panels to floating launchers to fully hidden and back to the last visible layout; ordinary launcher clicks still open their panel. Shift+T directly hides everything and restores the exact preceding state. Both sidebar shortcuts are inactive in Preview and respect editable targets and active overlays. Existing hosts keep Edit/Focus behavior by default.
useWorkspacePanelVisibility().togglePanels hides the visible editor panels or restores their preceding layout. Desktop and compact layouts are remembered independently, and forceCollapsed (for example during Preview) does not overwrite that memory. The host owns global navigation visibility and any edge launchers.
For floating editor panels, pass skin: platformWorkspacePanelRevealSkin from @qokit/components/skins/platform and spread the returned panelProps onto the existing panel. The skin applies only while revealed; the docked panel and its mounted content remain intact. ResizablePanels merges startPanelProps, middlePanelProps, and endPanelProps class names with its own skin slots. Pair focus controls with Toolbar and platformFloatingToolbarSkin for shared keyboard navigation and compact spacing. Both skins share the global DialogPanel surface (background, shadow and blur); panel corners use the card radius and toolbar corners use the control radius. Hosts own positioning and available space, not a separate overlay palette.
useWorkspacePanelEdgeDrag is an opt-in hook for an existing workspace root ref. Mark its focusable borders with data-workspace-panel-edge="start" or "end"; ResizablePanels supplies these attributes on its own separators. The host provides each side's mode (expanded, icons, hidden), saved width and bounds through getState, applies onChange, and returns a rollback callback from onBegin. onResizing should suspend layout transitions; onFinish restores focus to the resulting control, and onReset restores the host's default width. One captured mouse or touch gesture crosses all three states, with RTL direction handling and cancellation on Escape, pointer cancellation or window changes. Arrow keys resize or step states, Shift increases the step, Home/double-click resets, and End expands to the allowed maximum. This hook adds no visual controls or stored content. Hosts can pair hidden borders with useWorkspacePanelReveal for temporary shortcut access while retaining their normal click actions; hosts without the hook keep existing resizer behavior.
FloatingAssistant.headerActionsTarget optionally accepts an HTMLElement in the host heading. The assistant portals its existing conversation history and new-conversation controls into that element and omits its internal header. Without a target, the original header remains. The host owns the heading and placement; the assistant retains action handlers, accessibility labels and conversation state. The Web adapter forwards this slot.
FeatureHint is exported from @qokit/components/patterns/FeatureHint. Use it for contextual first-use guidance attached to a real control. Provide a versioned id, a stable user scopeKey, an anchor: HTMLElement, an active eligibility signal, localized title, description, dismissLabel, and action: { label, onClick }. Set completed when the user discovers the capability independently. A null scope or unavailable anchor suppresses the hint.
The shared component allows one hint at a time, waits briefly for a visible target, follows scrolling and resizing, supports RTL, and keeps content inside the viewport. It does not add a backdrop, steal focus, or perform the action automatically. Escape, the close button, or clicking elsewhere dismisses it; Tab from the target reaches the action. The target receives a temporary highlight and accessible description. Seen hints are remembered in the current browser per scope and version, with an in-memory fallback if storage is unavailable; this is not cross-device progress. Hosts own permissions, review-state suppression and the actual action. skin, className and style adapt presentation.
AssistantContextCard is exported from @qokit/components/patterns/FloatingAssistant. Place it in composerContext to summarize the current editing target. Its typed contract includes title, description, scope, preview, parameters: { id, label, value }[], optional controls, status and notice, plus actions, onLocate and clearAction. Pass localized labels and formatted values, including units, from the host.
The card renders a read-only definition list, an optional controls slot for a few common adjustments, and a live status region. Reuse the host’s existing editing controls and commands in this slot; keep complete settings behind an explicit action that opens the existing inspector. Hosts retain ownership of selection, permissions, save, undo and AI requests. Conversation, canvas editing and inspector editing can operate together, with independent panel visibility. Selecting an object updates the card and an already open inspector without opening a closed panel or moving focus. Removing a conversation reference preserves canvas selection and direct editing; keep the conversation entry independent of this card and of floating-tool visibility. Changing the target or a parameter updates this live card without appending chat messages. Both draft and project conversations can use the same component. className, style and AssistantContextCardSkin support visual adaptation; styles are loaded with the component.
FloatingAssistantPanel.composerContext 接收输入框上方的实时上下文区域。提供此插槽时,顶部旧的 activeContext 摘要隐藏,activeContext.promptPlaceholder 仍供输入框使用。实时参数属于当前编辑状态,不应追加到历史消息列表;Web 适配器透传此插槽。
Hosts can set hoverReveal={false} to disable navigation previews from the trigger and window edge while retaining explicit controls and drag resizing; the default remains true.
WorkspaceNavigationDock prefetches same-origin destinations on mouse hover or keyboard focus, with bounded deduplication.
Web 适配器同时透传 FloatingAssistantPanel.composerAttachments:在消息表单内部、文本输入区之前放置宿主管理的附件。宿主负责网格位置与发送生命周期:拖入只添加待发送附件,成功后仅清除本次提交的附件,失败保留以便重试。
共享对话组件
@qokit/components/patterns/Conversation 导出 ConversationPanel、ConversationMessages、ConversationMessage、ConversationSuggestions 和 ConversationComposer。创作室生成、草稿修改和项目内嵌助手复用这些结构及同一套基于 Token 的样式;宿主负责请求、历史、权限、选中对象和审阅、应用操作。
ConversationFeedback 组合 InlineNotice,在对话中紧凑呈现任务状态、失败、回退和保存回执。提供本地化的 title,以及可选的 description、tone 和 action。两行均使用说明文字字号、紧凑间距和透明表面;色调突出状态,辅助文字保持弱化。默认的 role="status" 与 aria-atomic="true" 将整个更新一起播报;需要用户处理的失败使用 role="alert"。助手撰写的正文继续放在 ConversationText 中。
将可滚动的 ConversationMessages 和固定的 ConversationComposer 直接置于面板内。为消息区域提供本地化标签,通过 inputProps 控制文本输入。输入组件接受 attachments、notice、actions 插槽及 formProps、formRef;组件自身创建表单,不要再嵌套表单。Enter 换行,Cmd/Ctrl+Enter 提交,并检查输入法组合输入及禁用、忙碌状态。宿主支持时,请求期间保留用户输入。
PromptPanel.presentation="conversation" 复用输入组件,同时保留参考资料读取、上传菜单和序列化表单字段。默认 "prompt" 保持入口页输入行为。FloatingAssistant.presentation="embedded" 使用共享面板、消息、建议和输入组件;浮动助手继续使用紧凑布局。
2026-10-15 · EditorControlGroup 标题操作
EditorControlGroup 的 headerActions 槽位在分组展开和收起时均保持可见,适合内容显隐等紧邻标题的操作;点击或通过键盘操作这些控件不会切换分组。summaryActions 继续只在收起时显示。宿主负责操作名称、状态与保存,纯图标操作仍须使用带本地化可访问名称的共享 IconButton。
2026-10-10 · EditorItemDisclosure
EditorItemDisclosure(@qokit/components/patterns/EditorItemCollection)通过 title、summary、open、onOpenChange、leading、actions 和 children 提供列表内编辑。展开保留周围列表,Escape 收起并返回触发点焦点;普通展开不主动滚动或抢焦点。useEditorItemDisclosure 按 scopeKey 管理单项展开,并在删除当前项后恢复相邻项焦点。EditorItemCollection 使用同一方式;宿主继续负责内容、排序、保存与撤销。原有 EditorFocusedItem 导出保留,供确实需要独立详情的流程使用。
新增 API 参考(英文,译文待同步) · 2026-10
2026-10-10 · ActionMenu search header
ActionMenu.dropdownHeader accepts host-owned content before the actions in both dropdown and mobile sheet presentations. onOpenChange reports opening and dismissal so hosts can reset transient search state. Search hosts supply localized copy, filtering and initial input focus; ArrowDown from the input should focus the first enabled result, then the shared menu handles result navigation, selection and Escape.
2026-10-08 · Shared list toolbar groups
WorkspaceFilterToolbar now has one container-responsive contract across Projects, CMS and Admin:
query:search、状态filters、sort、业务controls、advanced选项、按条件显示的reset、资源result和辅助summary。presentation:view,显示controls和options,如可见列和每页条数。页面组件自定义属于页面页头操作。actions: persistent operations, followed by the optionalselectioncontrol at the logical end. UseToolbarButtonswithiconand localizedcompactLabelfor refresh and other familiar actions.
The shared component measures its own available width. Controls show icons with labels above 960px and accessible icon buttons at or below 960px. At or below 640px, search occupies the first row and tool groups wrap in query → presentation → actions order. Routes must not override group widths or hide individual labels. ControlMenu and ViewMenu inherit this presentation without a route-specific responsive flag.
通过 query.result={{ label, count, total?, locale? }} 提供资源名称和结果数量。共享 WorkspaceResultSummary 显示“名称 · 数量”,仅在可靠的未筛选总数与结果数量不同时添加“/ 总数”,并按界面语言格式化和隔离双向数字。数量未知时省略 result;零是有效结果。同一列表上方不要另加名称和数量行。AdminFilterBar.result 接受相同对象。页面标题、有效分组标题、分页和选中数量各归其位;其他计量单位、查询上下文或更新时间使用 query.summary。
Give overflow a localized label to move advanced and display options into More when compact. query.compactItems and presentation.compactItems supply complete menu choices replacing their corresponding controls; controlled values and callbacks remain in the host. Permanent menu actions use overflow.items. Selection and refresh stay outside More. Select and Done share the end slot, hit target and reserved idle toolbar height, including wrapped mobile rows.
This replaces the old flat toolbar API: migrate search, filters, sort, reset and secondaryControls into query; migrate view and display controls into presentation; move persistent endActions to actions. The former adaptive / inline-wrap CSS modes and WorkspaceFilterControlGroup capsule are removed; use these three semantic groups rather than compatibility aliases.
2026-10-14 · 管理分组与摘要
WorkspaceSectionGroup、WorkspaceSection、WorkspaceFieldGrid 与 WorkspaceFacts 从 @qokit/components/patterns/WorkspaceLayout 导出。分组在桌面和手机都将标题、说明放在卡片上方,起始边缘对齐。使用默认 stacked 布局;旧 layout="split" 参数兼容为 stacked。分组中的表单使用 qk-workspace-section-group__form,让分组间距和保存区对齐使用同一契约。WorkspaceSection 支持可选的 icon、actions 和 description,标题保留在内容面板外。
WorkspaceFieldGrid 按实际可用宽度安排最多两列独立短字段。WorkspaceFacts 输出语义化定义列表,接受稳定 id、label、value、可选 unit、description、emphasis 和 tone;columns 支持 2、3、4 列,窄容器自动重排。简短数字摘要可指定 mobileColumns={2},在手机保留两列;默认单列。它自身不绘制卡片,避免摘要形成嵌套内容面板。各组件支持对应的具名 Skin、className 和 style。表单状态、权限、提交、冲突和恢复继续由宿主管理,组件不发起请求。
2026-10-14 · 管理内容面板与折叠
WorkspaceContentPanel 及 WorkspaceSection.kind 支持 summary、form、records、actions 四种相关内容配方。toolbar 放在内容底板之外,supporting 和 footer 分别提供紧凑辅助信息与尾部操作;titleId 保留已有标题锚点。默认面板容器不会覆盖宿主已有的命名容器。
卡内子组、辅助信息和记录行分别使用 WorkspacePanelBlock、WorkspacePanelMeta、WorkspaceRecordRow。记录行接受 title、description、meta、status、actions 及整行详情 children。摘要事实始终顶部对齐;各页面继续拥有业务字段、权限、表格列与提交范围。
WorkspaceActionRow 的可选 label 表达操作身份,status 表达空或加载状态,配合 description 与 actions 使用。操作标题为 14px,状态为同字号的普通辅助文字,说明为 12px。桌面文案组与按钮共用中心线,窄屏上下排列。Card 本身不覆盖内部 strong 的字号或间距。
WorkspaceDisclosure 接受 title、可选 status 与 children,WorkspaceDisclosureGroup 接受 Accordion items 和受控展开属性。默认关闭,同组最多展开一项;宿主可显式设置默认展开项。Enter/空格切换,Esc 收起并返回触发器;嵌套先处理内层,内容隐藏时保留 DOM 与输入状态。headingLevel 可给分区级触发器提供标题语义,Skin 与 class 槽只负责视觉适配。以上组件均从 @qokit/components/patterns/WorkspaceLayout 导出。
2026-10-17 · ActionMenu 复用富内容触发器
ActionMenu.renderTrigger 可复用 SelectableTile 等富内容控件,接收 aria-expanded、aria-haspopup、disabled 与 onClick,调用方须将这些属性传给真实触发器。控件的选择语义和外观由宿主管理;Portal 定位、菜单键盘导航、关闭、焦点返回和可选手机底部面板继续由 ActionMenu 拥有。默认文字和图标触发器保持兼容。
CustomizableWidgetLayoutControls / CustomizableWidgetLibrary
将 CustomizableWidgetLayoutControls 放置在页面页头操作中,位于上下文帮助之后和主要操作之前,包括在移动设备上。使用本地化的 copy.customize 明确命名该操作(例如,“自定义组件”)。相同的仅图标入口暴露 aria-pressed 和 aria-expanded,并在编辑时变为 copy.done。customizeButtonRef 可选暴露触发按钮,供宿主恢复焦点;disabledCustomize 禁用该入口而不改变其布局尺寸。仅为支持折叠组件的宿主提供 onCollapseToggle 和 areWidgetsCollapsed;省略它们将单独呈现自定义入口。
CustomizableWidgetLibrary 负责通用组件库标题、重置/关闭操作、响应式滚动布局、初始关闭按钮焦点和 Escape 处理。关闭时将焦点返回给调用控件(如果焦点仍在库内);外部点击保持其目标焦点。宿主保留组件定义、添加/删除/排序/调整大小命令、持久化和重置语义。CMS 和 Admin 类槽位仍可用于业务挂钩,但不得定义单独的组件库表面或移动布局。
圆角和范围控件
@qokit/components/ui/RangeNumber 的 RangeNumber 将原生范围滑块与精确数值 Input 配对。传入 label、value、min、max、可选 step 和 unit,以及 onChange。未定义的值显示混合值短横线;修改任一输入会设置一个范围内的数值。onCommit 让宿主将连续修改合并到既有撤销历史。disabled、键盘导航、紧凑密度、RTL 和焦点样式共用;持久化由宿主负责。RangeNumberSkin 提供根、滑块、输入和单位槽位。
@qokit/components/patterns/EditorRadiusControl 的 EditorRadiusControl 组合实时形状预览、四个物理角输入、RangeNumber 和可选形状预设。value 与 onChange 使用 CSS border-radius 简写;cornerLabels 和预设名称由宿主本地化。RTL 下仍依次为左上、右上、右下、左下。设置 max 将编辑限制为有界像素值,省略则保留 CSS 单位和椭圆角语法。混合圆角在用户统一设置四角前不显示单一数值。可选 EditorRadiusControlSkin 适配根、示意图、预览和预设槽位,不改变状态或持久化。