Skip to Content
设计

设计契约更新

Qokit 公开设计 Token、组件 API 与接入契约的变更记录。

设计契约更新

2026-10-21 · 滚动菜单的固定操作

ActionItem.pinned 支持 start 或 end,使对应操作及 ActionMenu.dropdownHeader 保持在滚动列表之外,键盘导航和选择语义覆盖全部区域。Portal 宿主可通过 --qk-menu-available-height 限制菜单高度,该值按触发器实际展开方向测量;未指定 pinned 时保留原菜单结构。

2026-10-17 · 组件自定义入口

页面组件自定义使用项目、内容和仪表板中共享的页头入口。CustomizableWidgetLayoutControls 添加了可选的 customizeButtonRef 和 disabledCustomize;折叠控件是可选的。CustomizableWidgetLibrary 在宿主之间共享移动布局、初始焦点、Escape 键和焦点返回。组件持久化和命令仍由宿主负责。请参阅 组件自定义集成。

2026-10-17 · 托管工作台面板控件

WorkspaceHeaderPortal 接受可选的 startControl 和 endControl,以及匹配的可选宿主目标。托管文件视图使用与单资产编辑和预览相同的页头面板槽和工作区布局尺寸。现有宿主可以继续仅提供标题、状态和操作。请参阅 EditorHeader 集成。

2026-10-17 · 按可用宽度计算编辑器默认值

useWorkspaceResponsiveProfile 为可用的工作区尺寸添加了可选的 onWidthChange(width)。useEditorLayout 现在也将配置的共享宽度限制应用于宿主存储,并且 readEditorLayout 接受其第四个参数的可选限制。现有调用者保留其默认值。请参阅 组件集成。

2026-10-08 · 工作区标题返回导航

WorkspaceLayout 和 WorkspacePageHeader 新增可选的 backControl,放在标题之前。使用 WorkspaceBackButton,传入本地化 label 及原有 href 或 onClick,共享组件提供箭头、可访问名称、Tooltip 和 RTL 镜像。返回目标、列表状态与离开保护继续由宿主控制;未传入该槽位的头部保留现有布局。

2026-09-26 · 创作室 · 风格方案

站点主题契约 v3 新增可选精细设置,未设置时继续使用现有主题默认值。site.theme.spacingOverrides 按 desktop/tablet/mobile 保存 sectionPadding(0–240px)、pageGutter 与 cardGap(0–96px);平板和手机以站点容器 980px、720px 为断点,缺省值向较宽设备继承。显式区块节奏与元素局部样式继续优先。

primaryButtonStyle、secondaryButtonStyle 支持 solid/outline;buttonFontSize 为 12–24px;linkUnderline 支持 always/hover/none,linkHoverStyle 支持 none/tint。mutedColor、borderColor、buttonTextColor、cardSurfaceColor(--qk-site-color-card-rgb)及对应 dark* 字段分别控制明暗主题。主题解析统一供编辑、预览和发布消费。

新增 Token 为 --qk-site-custom-{sectionPadding|pageGutter|cardGap}-{desktop|tablet|mobile}、--qk-site-{primary|secondary}-button-{background|color|border|shadow}、--qk-site-button-font-size, --qk-site-button-size-{sm|md|lg}、--qk-site-link-decoration、--qk-site-link-hover-decoration、--qk-site-link-hover-background。默认 initial 表示保留配方回退值。

2026-09-09 · 全局导航快捷键

SidebarNavigation 与 WorkspaceNavigationMenu 改用 Mac 的 Command+\、Windows/Linux 的 Control+\,同步按钮提示与可访问快捷键。创作室内可独立开合全局菜单,T 与 Shift+T 继续控制编辑布局;保留输入及输入法组合输入保护。

2026-09-09 · FloatingToolPanel 动效

可选的 FloatingToolPanel.viewKey 为工具切换提供过渡,同时保留正文实例。共享的开合、展开及钉住反馈遵循减少动态效果设置;指针几何更新每帧最多执行一次。关闭的 Dialog keepMounted 立即禁止交互并退出辅助技术可访问树,包括退场过渡期间。已有属性及文档状态归属保持不变。

2026-09-09 · WorkspacePanelEdgeDrag

可选的 useWorkspacePanelEdgeDrag 让已有工作区边缘在一次鼠标或触摸拖动中跨越展开、图标和隐藏三态,并提供键盘调整、RTL 与取消恢复。ResizablePanels 的分隔边新增 data-workspace-panel-edge 标记;未启用该 hook 的宿主保持原有行为。宽度、状态、焦点和视觉皮肤仍由宿主控制,详见接入契约。

2026-09-08 · EmptyState

项目与 CMS 文章、产品的创建引导统一使用 EmptyState:居中、透明背景、紧凑字体层级与可换行操作。新增可选 icon、layout、style,description 改为可选。标题改用 h2;自定义 strong 选择器应迁移到 title skin 槽。多个操作由共享容器布局;现有权限判断与创建逻辑仍归宿主所有。

2026-09-08 · SidebarNavigation

SidebarNavigation 在鼠标停留 180 毫秒或键盘聚焦后预加载同源路由;固定侧栏与弹出导航共享每 30 秒最多 8 个目标的额度。离线、隐藏标签页、省流量或 2G 网络时暂停预加载;下载、禁用链接、新窗口目标与同页锚点不预加载。导航与未保存离开保护保持原有契约。

2026-09-08 - Primary button foreground

椭圆主按钮保留 Logo 蓝原色 #4695D8,深浅主题下均使用白色文字、图标和加载指示器。悬停保留既有轻微提亮;次要按钮和危险按钮继续使用各自的语义颜色。

2026-09-07 - AccountDropdown / SidebarProfile

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 派生自已有平台颜色。

椭圆主按钮通过 --accent-action 直接使用 Logo 蓝原色 #4695D8,取消加深渐变。悬停仅混入 8% 白色提亮;文字使用品牌墨色混入 10% 黑色,保持清晰。导航高亮继续使用同源品牌蓝浅底与适配明暗主题的文字色。

下拉菜单与工作空间切换器共用 --menu-option-font-size(14px)和 --menu-option-font-weight(500),行高为 1.45;选中项字重 600,辅助信息 12px/400。WorkspaceNavigationDock 在鼠标悬停或键盘聚焦时预加载同源目标,并限制去重记录数量。导航仍使用既有离开保护与宿主路由。

2026-09-07 - ColumnLayout

桌面管理宿主的 ColumnLayout 使用贴边导航、独立内容滚动区和吸顶页面工具栏铺满视口。WorkspacePage 使用平整分区及共享控件圆角 Token。860px 及以下保留导航抽屉,关闭的抽屉不可交互。属性和业务行为不变。宿主应去掉重复外部留白,将阅读宽度限制放在表单内容上。

2026-09-05 · WorkspaceNavigationMenu / WorkspacePageHeader

登录后的工作区通过 PlatformHeader.workspaceActions 在所有宽度共用账户和导航区,WorkspacePageHeader 统一标题与操作。WorkspaceNavigationMenu 展示当前侧栏,保留权限和业务上下文;EditorNavigationMenu 保留为兼容别名。Studio 保留自己的任务工具栏。公共头部沿用现有表现。

WorkspaceNavigationGuard 通过 dirty、busy、error 和可选的 onSave 保护全局导航。保存确认成功并返回 true 后才能离开,失败保留草稿。Language.onBeforeChange(apply) 允许宿主通过同一保护延后语言切换。保存期间禁用表单字段。

2026-09-05 · EditorNavigationMenu

EditorNavigationMenu 将宿主完整的 SidebarNavigation 放入覆盖式抽屉,保留权限和项目上下文,不挤动画布。语言与主题位于底部,子菜单优先处理 Escape。1120px 及以下使用两行头部,视图菜单显示当前模式名称。专注与浏览器全屏相互独立;导航会等待进行中的保存,并保护未保存草稿。

2026-09-05 · EditorHeader

EditorHeader 将宿主的 Logo、头像和全局菜单保留在当前编辑器中。startControl、endControl 分别控制左右面板,center 放视图命令,actions 放保存操作。PlatformHeader.editorActions 复用响应式导航、语言和主题控件。onNavigate 必须先处理未保存内容,再执行导航回调。窄屏顶栏分为两行,子菜单优先处理 Escape。

2026-09-05 · SidebarToggleSlot

SidebarToggleSlot 把现有侧栏折叠按钮放到工作区页头,每个工作区配合一个左侧栏使用一个插槽。展开状态、快捷键和移动抽屉仍由 SidebarNavigation 管理;未提供插槽时保留原位置。移动抽屉也由页头按钮关闭,关闭后焦点返回同一按钮。

2026-09-05 · EditorWorkspace / Dialog / Segmented

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 可接入共享视图控件。保存快捷键调用宿主,发布与权限仍由宿主负责。

2026-09 · EditorWorkspace

EditorWorkspace 组合全屏对话框、焦点管理和响应式面板。通过 dirty 确认是否放弃修改,通过 busy 阻止保存中退出,通过 onSave 响应 Ctrl/Cmd+S。权限、数据、保存和发布由宿主负责。

2026-08 · 紧凑指标密度

  • 为 MetricCard 增加可选的 density="compact" API,用于高密度运营工作区;
  • 保持现有默认密度和 DOM 语义不变;
  • 将紧凑内边距、数值尺度和最小高度统一放入共享组件样式,路由无需再做视觉覆盖。

2026-07 · 统一表单控件

  • 向 @qokit/components/ui 新增 FormField、Input、Textarea、Checkbox、RadioGroup 和 Switch;
  • 由共享 FormField 骨架关联标签、说明、错误、必填状态和 ARIA 引用;
  • 将 Input、Textarea、Select 和 SearchField 统一到 40px、44px、48px 尺寸和共享交互 Token;
  • 为新表单基础组件增加平台、Admin 和生成站点 Skin 配方;
  • 保留既有 .qk-field 样式作为向后兼容的迁移路径。

2026-07 · 按钮尺寸排版

  • 新增 --button-font-size-sm、--button-font-size-md、--button-font-size-lg 三个语义 Token;
  • Button 的 sm、md、lg 现在分别固定使用 14px、15px、16px 文字,不再继承 Header、Dialog 或页面容器字号;
  • 站点 Skin 如需调整按钮排版,应覆盖对应语义 Token,不再通过路由 class 重写 font-size。

2026-07 · 平台公共导航骨架

  • 新增无登录依赖的 PlatformHeader,平台与文档站使用同一语义骨架;
  • 新增 PublicPlatformHeader 与 buildPublicHeaderNavItems,平台匿名状态和文档站复用同一公共 Header 组合及导航配置;
  • HeaderNavItem 新增 menu 类型,桌面 Header 使用可关闭的下拉菜单,移动 Header 自动展开为链接分组;
  • SiteFooter 新增可选的 brandHref 与 controls,支持公开文档等不同接入场景;
  • 新增 PublicPlatformFooter,平台和文档站复用同一 Footer Shell,并允许跨域解析平台链接;
  • 以上均为向后兼容的可选 API,原有平台 Header 状态逻辑和 Footer 默认控件保持不变。

2026-07 · 公开设计指南

  • 将公开设计契约与内部 AI 实现规范分离;
  • 公开视觉 Token、组件导入、Skeleton/Skin 边界、Button、Card 和无障碍要求;
  • 明确破坏性组件变更必须提供迁移说明;
  • 公开搜索、Sitemap 与 LLM 输出只包含可对外依赖的内容。

兼容性说明

  • 新增可选属性、可选 Skin 槽位和语义 Token 通常保持向后兼容;

  • 删除或重命名属性、改变默认 DOM/语义/键盘行为属于破坏性变更;

  • 破坏性变更将在本页说明影响范围、替代 API 和迁移步骤。

  • 2026-09-06: 桌面导航保留展开和图标模式,并增加自动隐藏。 SidebarNavigation / WorkspaceNavigationMenu / Dialog

  • 2026-09-06: EditorViewControls 将编辑/专注与屏幕全屏分开控制。 EditorViewControls

  • 2026-09-06: Language 与 Appearance variant="menu" 支持可选的 layout="row",同一行显示标签、当前值和箭头。默认紧凑布局及语言切换保护保持兼容。SiteHeaderCopy.helpResources 与 contactSupport 可选提供工作区帮助入口文案。 Language / Appearance

  • 2026-09-06: 有侧栏页面移除重复的头部菜单按钮,保留既有开关及导航 API。 WorkspaceNavigation

  • 2026-09-06: 全局导航使用菜单图标,编辑工具使用左右分栏图标。 WorkspacePanelReveal / EditorViewControls

  • 2026-09-06: 显示模式 · E / T / V / F · Segment.shortcut. EditorViewControls

  • 2026-09-06: PlatformHeader.workspaceNavigation 将全局导航放在 Logo 前 PlatformHeader.workspaceNavigation

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-06 - EditorViewControls

编辑与专注使用同一个双向按钮:编辑时显示“专注”,专注时显示“编辑”。点击或按 T 切换,E 仍可直接返回编辑。窄屏保留切换按钮,预览、全屏和附加操作收进更多菜单。 EditorViewControls

2026-09 · 管理工作区

窄屏 WorkspaceDataTable 和 AdminDataTable 默认显示带字段标签的记录,保留选择、自定义表头与操作。需要列对齐的比较矩阵使用 mobileLayout="scroll"。WorkspaceFilterToolbar 先放搜索与筛选,再放排序和视图控件。侧栏标题使用 h2,页面保留 h1。

2026-09-08 · Task focus

useSidebarTaskFocus(active) 在专注任务期间临时隐藏导航,退出时恢复先前显示方式;任务期间用户主动修改导航模式时,以用户选择为准。自动隐藏不会改写已保存的偏好。

本页目录