OpenChamber Settings UI Patterns：用共享原语构建可搜索、响应式的设置界面

AI Agent人工智能代码智能体交互助手【免费下载链接】openchamberAgentic Development Environment based on OpenCode AI agent项目地址https://gitcode.com/gh_mirrors/op/openchamber点击查看免费下载本指南以 OpenChamber 仓库中的.agents/skills/settings-ui-patterns/SKILL.md及其三份参考文档layout.md、controls.md、search.md为主体系统讲解 OpenChamber Settings设置页面的标准化构建规范从共享原语组件、页面骨架与层级、控件尺寸与宽度约束到描述策略、保存反馈契约和设置搜索注册表。读者在阅读后将掌握在 OpenChamber 桌面端、Web 端与移动端统一新增、调整设置项和设置页面的完整套路并能直接对照仓库源码在packages/ui中落地实现。一、规范总览Settings 不是自由发挥的 UI 沙盒OpenChamber 的设置界面有一条硬性规范所有设置页面必须由共享原语构建禁止用裸div手写页面骨架、区块标题、字段行、复选框行或信息气泡。这些原语集中在两个文件中packages/ui/src/components/sections/shared/SettingsSection.tsx —— 全部行级与区块级原语及SETTINGS_*样式常量packages/ui/src/components/sections/shared/SettingsPageLayout.tsx —— 页面级骨架滚动、页头、保存状态指示器、容器查询作用域packages/ui/src/components/sections/shared/SettingsInfoHint.tsx —— 唯一允许使用的信息图标实现。当确实缺少某个形状的原语时正确的做法是在共享文件里扩展原语而不是在页面内另起炉灶。与之配套的是四条“规范方向”Canonical Direction扁平层级通过间距与排版区分层级不使用卡片、盒式背景或行级装饰信息默认隐藏次要说明文本默认收在info图标之后默认视图保持安静统一控件尺寸控件只有一种标准尺寸h-9/ select 使用sizesettings且宽度有上限不允许全宽拉伸的输入框容器查询而非视口断点布局随设置面板宽度通过容器查询xl:/3xl:响应绝不使用视口sm:/lg:断点——因为设置面板位于对话框内部远比视口窄。配套技能Required Companion Skills构建设置界面不是单打独斗SKILL.md 明确要求同时加载三个配套技能theme-system负责颜色、按钮、图标与视觉状态契约locale-ui-patterns负责所有可见字符串、提示语、占位符与无障碍标签的本地化ui-api-decoupling当设置项读写运行时数据或新增能力时加载并在新增/移动设置页面前先按其中的 “Name The Surfaces Before Editing” 步骤写出 surface 清单——一个在桌面端存在、在手机上不可达的页面正是最常见出错方式。当示例之间存在冲突时共享组件/主题契约与本地化契约优先遇到无法消解的材料级冲突应立即停下来而不是强行绕过。二、共享原语速查表按需取用不要重复造轮子SKILL.md 给出了一张“需求 → 原语”的速查表这是写任何设置页面的起点需求共享原语页面外壳标题、描述、保存状态、滚动、containerSettingsPageLayout带标题的区块 分隔线第一个区块传divider{false}SettingsSection标签在左 / 控件在右SettingsFieldRow标签在控件上方双列单元格、宽控件SettingsStackedField布尔开关SettingsCheckboxRow互斥选项列表SettingsRadioGroupSettingsRadioOption短分段选项SettingsChipGroup区块内部带安静 L3 标题的子簇SettingsControlGroup宽面板上的双列区域SettingsTwoColumn按需显示的帮助文本悬停 点击info属性或SettingsInfoHint禁止事项SKILL.md 明确禁止引入基于原生Tooltip的自制信息图标、直接使用 Remixicon 组件、硬编码面向用户的字符串、自建一套颜色/按钮体系。新增图标时在代码中引用 Remix 图标名然后运行bun run icons:generate将图标加入 sprite 即可。从源码看原语的宽度约束设计SettingsSection.tsx中定义了一个共享宽度上限常量const SETTINGS_TRIGGER_WIDTH_CLASS w-full min-w-[16ch] max-w-[28ch];其设计动机在源码注释中说明得很清楚applyTypography会缩放--typography-*变量但不会改变根rem因此基于rem的上限如max-w-48在界面字号放大时会让值溢出而基于ch的上限会随控件自身typography-ui-label字体缩放从而跟随设置字号增长。宽度上限故意收紧让一列下拉框读起来宽度一致长值在内部截断而不是把触发器拉满整个面板。同理数字步进器使用SETTINGS_NUMBER_INPUT_CLASS typography-ui-label w-[16ch]把ch钉在会被缩放的同一字体上避免大字号下数字被裁切。三、页面布局规范references/layout.md页面骨架设置页面的标准骨架如下SettingsPageLayout负责滚动、页内边距、container上下文以及showSaveStatus保存指示器SettingsPageLayout title{t(settings.page.x.title)} description{t(settings.page.x.description)} showSaveStatus SettingsSection title{t(...sectionA)} divider{false}…/SettingsSection SettingsSection title{t(...sectionB)}…/SettingsSection /SettingsPageLayout区块之间用顶部分隔线divider默认true分隔页头下的第一个区块要传divider{false}。从源码看SettingsPageLayout还做了一个兜底[section:first-of-type]:border-t-0 [section:first-of-type]:pt-0保证无论平台条件区块渲染与否第一个可见区块都不出现顶部分隔线。区块标题是真正的 L2 标题不要用一个伞形区块包住一组各自值得拥有标题的SettingsControlGroup——此时应把分组提升为区块Chat 页面即此先例。层级体系L1–L4层级组件 / 类用途L1SETTINGS_PAGE_TITLE_CLASS经SettingsPageLayout页面标题L2SettingsSection标题SETTINGS_SECTION_TITLE_CLASS区块L3SettingsControlGroup标题SETTINGS_GROUP_TITLE_CLASS区块内子簇L4SETTINGS_FIELD_LABEL_CLASS字段 / 控件标签HelperSETTINGS_HELPER_CLASS、SETTINGS_DESCRIPTION_CLASS极少见的可见帮助文本大多数收进info导航分组与页面归属侧边栏分组由 packages/ui/src/lib/settings/metadata.tsSETTINGS_PAGE_METADATA与 SettingsView.tsx 中的pageOrder共同决定OpenChambergeneral组General、Appearance、Chat、Notifications、Sessions、Shortcuts、Voice、Usage、About源码pageOrder中还包括 routing、integrations、extensionsWorkspaceprojects组Projects、Remote Instances、External Tunnel、GitOpenCodeopencode组Providers、Agents、Behavior、Commands、MCP、PluginsLibrarycontent组Magic Prompts、Snippets、Skills、Skills Catalog。归属规则General 只放不属于任何功能页的应用级设置启动/托盘/窗口、网络访问与 UI 密码、passkeys、OpenCode CLI 二进制、终端 shell/导航、消息流传输、隐私功能页Appearance、Chat、Sessions…只保留与该功能相关的设置。如果一个设置在它的页面上读起来很别扭把它移到 General而不是发明新页面。新增页面需要metadata.ts中的元数据、SettingsView.tsx中的pageOrder与导航图标、每种语言下的settings.page.slug.title/description以及必要时移动端白名单MOBILE_SETTINGS_PAGES在MobileApp.tsx中。响应式一律使用容器查询设置面板比视口窄得多三栏对话框。面板内所有内容通过容器查询响应——xl:36rem与3xl:48rem绝不使用视口sm:/lg:断点。SettingsPageLayout提供container作用域源码中classNamew-full containerSettingsFieldRow、SettingsTwoColumn与触发器宽度常量已内置对应变体。唯一例外SettingsView的导航区位于面板之外使用视口sm:为手机提供 44px 触发行高与纯bg-background改动导航时保留这一模式。间距约定区块自己掌握纵向节奏SettingsSection自带divider py-8列内字段间距SETTINGS_FIELDS_STACK_CLASSspace-y-4复选框/单选列表间距SETTINGS_OPTION_STACK_CLASSspace-y-1.5需要标题与可见描述的分组用父级space-y-6与前序控件隔开简单复选框/单选列表保持紧凑双列区域用SettingsTwoColumn3xl:grid-cols-2单元格内使用SettingsStackedField——SettingsFieldRow会溢出半宽列没有明确 UX 价值时不加浮起背景、圆角行或悬停填充。四、控件规格references/controls.md标准尺寸与宽度上限整个 Settings 只有一种控件尺寸h-8SelectTriggersize{SETTINGS_SELECT_SIZE}settings→ h-8、rounded-md、px-3自定义下拉触发器ModelSelector / AgentSelectorSETTINGS_CUSTOM_TRIGGER_CLASSdropdownTriggerVariants() 宽度上限类与下拉并排的文本Inputh-8 rounded-md px-3与触发器足迹一致控件旁的图标动作SETTINGS_ICON_BUTTON_CLASSh-8 w-8 px-0。宽度一律有上限控件不允许横贯面板字段行控件簇 / 堆叠字段默认上限max-w-[24rem]内置于SettingsStackedField其他场景用SETTINGS_CONTROL_CLUSTER_CLASS字段行内的下拉SETTINGS_SELECT_ROW_TRIGGER_CLASS窄屏全宽、xl:w-56堆叠字段内的下拉SETTINGS_SELECT_TRIGGER_CLASS填满受限容器真正需要全宽的内容对话框文本框用controlClassNamew-full max-w-none显式退出。字段行SettingsFieldRow label{t(...label)} info{t(...hint)} // 帮助文本收在 info 图标后 settingsItempage.some-setting Select … SelectTrigger size{SETTINGS_SELECT_SIZE} className{SETTINGS_SELECT_ROW_TRIGGER_CLASS} aria-label{t(...aria)}…在SettingsTwoColumn单元格或控件较宽时改用SettingsStackedField标签在控件上方两者都支持info/settingsItem属性。从源码看SettingsFieldRow在xl之下堆叠为上下两行flex flex-col … xl:flex-row标签列固定xl:w-56控件列在桌面端默认右对齐alignEnd默认true。布尔开关自解释的开关设置只用一个复选框 标签不需要额外的组标题或描述SettingsCheckboxRow checked{value} onChange{setValue} label{t(...label)} ariaLabel{t(...aria)} info{t(...explanation)} // 可选见描述策略 settingsItempage.some-setting /行点击与键盘切换空格 / 回车已内置——源码中整行以rolebuttontabIndexaria-pressed实现toggle()统一处理鼠标与键盘。可见description只用于必须保持可见的文本警告、动态状态。互斥选项互斥模式用单选而不是一组独立复选框。自解释的选项保持紧凑标题或描述不是必须的当描述策略要求可见解释时用SettingsControlGroup包裹标题 → 描述 → 选项在组级解释一次SettingsControlGroup title{t(...group)} description{t(...description)} SettingsRadioGroup aria-label{t(...group)} SettingsRadioOption selected{…} onSelect{…} label{t(...)} ariaLabel{t(...)} / /SettingsRadioGroup /SettingsControlGroup标签本身已能自解释的选项跳过逐项描述。短分段选择用SettingsChipGroupchips 带aria-pressed。数值 / 覆盖值数值输入使用NumberInputSETTINGS_NUMBER_STEPPER_ROW_CLASS单位用SETTINGS_NUMBER_UNIT_CLASS旁边放SETTINGS_ICON_BUTTON_CLASS重置按钮。绝不让步进器 flex-grow源码注释强调否则 /- 按钮会被不均匀拉伸。可选覆盖空值表示“继承”提供fallbackValue、onClear、emptyLabel—。Info HintsSettingsInfoHint是唯一允许的信息图标实现悬停和点击都能打开触屏设备没有悬停点击外部关闭。优先使用外层原语的info属性只有紧挨裸标签/标题时才直接使用该组件。禁止用原生TooltipIcon nameinformation自制信息图标——它们在移动端不可用。移动端约束packages/ui/src/styles/mobile.css 可能强制.overflow-hidden滚动只在必要时使用显式 x/y 裁剪触屏 CSS 强制最小按钮高度不要把自定义分段按钮放进过矮的容器。选择器行与对话框图标/颜色面板放在标签下方选项尺寸与间距保持一致用稳定的 border/ring/background 表达选中态避免用 scale 变换导致布局位移。对话框复用同样的原语与尺寸SettingsCheckboxRow、SETTINGS_FIELD_LABEL_CLASS、SettingsStackedField对话框表单组之间的分隔线可接受向导步骤中引导活跃流程的说明保持可见不收进 info。五、描述策略Description Policy信息提示info hints的核心原则是默认安静解释性文字默认收在info图标之后当仅靠标签无法说明选项差异、后果或选择条件时才使用“标题 可见描述 复选框/单选控件”的组合选项标签本身已完整表达选择含义的如大文本粘贴模式、发送快捷键即使带例外说明也保持收在info之后。多个选项或一个组标题本身并不构成需要描述的充分理由必须保持可见的内容安全/数据丢失警告、破坏性后果、用户输入时需要对照的语法/占位符列表、动态状态、空状态、校验错误、活跃流程中的向导说明混合文本把警告句保持可见把解释移到info。六、保存反馈Save FeedbackSettingsPageLayout的showSaveStatus渲染共享的安静指示器成功是静默的“保存成功”不弹出任何东西只有超过约 500ms 的保存过程才显示 “Saving…”失败显示 “Save failed”。源码证据见 packages/ui/src/lib/persistence.tsgetSettingsSaveState()/subscribeToSettingsSaveState()管理一个idle | saving | error状态dispatchSettingsSaveState把saved归一为idle成功不渲染任何 UIerror在 6 秒后自动复位SettingsPageLayout中SAVE_SPINNER_DELAY_MS 500只有超过该延迟仍在saving时才显示 spinner——本地写入瞬间完成、保持静默远程/移动连接才有反馈。凡是通过updateDesktopSettings持久化的设置会自动上报状态页面自有的 API 必须调用reportSettingsSaveStatesaving | saved | error。禁止为普通设置写入添加逐页的保存徽章或成功 toast。七、设置搜索契约Settings Search ContractOpenChamber 的设置搜索使用显式注册表而不是扫描 JSX。任何稳定的设置控件新增或移动都必须在同一次变更中考虑搜索。搜索注册表位于 packages/ui/src/lib/settings/search.ts其条目接口为interface SettingsSearchItem { id: string; page: SettingsPageSlug; titleKey: I18nKey; descriptionKey?: I18nKey; keywords?: string[]; isAvailable?: (ctx: SettingsSearchAvailabilityContext) boolean; }五项集成要求可搜索项在search.ts中登记渲染处有匹配的data-settings-item...锚点共享原语通过settingsItem属性接收本地化的标题/描述键来自packages/ui/src/lib/i18n/messages/*.settings.ts各语言字典可用性与实际渲染条件一致控件移动到其他页面时同步更新条目的page条目的id即使带着旧页面前缀也保持稳定。新增顶级页面时还要在metadata.ts补充元数据与可搜索内容纯导航页除外并扩展SettingsView.tsx的pageOrder/导航图标以及移动端适用时的MOBILE_SETTINGS_PAGES。注册表规则索引稳定控件、区块标题和静态 create/connect 动作ID 匹配页面与目标如appearance.language优先用可见标签键作为titleKey仅当能改善上下文时才加descriptionKey为常用同义词/缩写添加 keywords如chat.activity-default带[activity, collapsed, expanded, live, tools, history]不要为动态实体单个 agents、providers、projects、skills、hosts、sessions生成条目。条件目标与可用性不索引藏在“已选中实体”状态之后的目标除非搜索选择先准备好该状态条目isAvailable必须与实际渲染可见性完全一致页面级可用性放metadata.ts条目级守卫放search.ts当功能需要本地权限时区分桌面 shell 与本地桌面来源SettingsSearchAvailabilityContext中区分isMobile、isDesktopLocalOrigin、isMac/isWindows/isLinux等平台条件对 split 页面索引可预测的静态表面并在结果需要先打开 draft/editor 再高亮时更新prepareSettingsSearchTarget。高亮锚点data-settings-item放在视觉上拥有该设置的最小稳定容器上不要仅为搜索添加纯布局包装高亮样式基于 token、保持细微定义在packages/ui/src/index.css的[data-settings-search-highlighttrue]下。审计清单每个注册表 ID 都有匹配的锚点每个标题/描述键存在于每个 Settings 语言环境每个非纯导航页面都有适当覆盖搜索可见性与平台/运行时/移动端渲染一致高亮前准备好条件状态空查询时的 Settings 导航保持原样。八、完成标准Completion CriteriaSKILL.md 以一份可直接用作代码评审清单的完成标准收尾全部由共享原语构建无临时页面/区块/行标记描述位置符合上述描述策略警告/语法/状态保持可见容器查询xl:/3xl:响应式面板内容中无视口断点控件使用标准尺寸与宽度上限无拉伸的全宽输入所有可见与无障碍文本均已本地化搜索注册表、锚点、页面、本地化与可用性彼此一致邻近 Settings 的先例与相关测试保持一致。九、参考资料索引本文核心依据与延伸阅读的仓库路径技能主文档.agents/skills/settings-ui-patterns/SKILL.md布局参考.agents/skills/settings-ui-patterns/references/layout.md控件参考.agents/skills/settings-ui-patterns/references/controls.md搜索参考.agents/skills/settings-ui-patterns/references/search.md原语实现SettingsSection.tsx、SettingsPageLayout.tsx、SettingsInfoHint.tsx页面元数据与导航metadata.ts、SettingsView.tsx搜索注册表search.ts持久化与保存状态persistence.ts设置模块总览packages/ui/src/lib/settings/DOCUMENTATION.md编写或评审 OpenChamber 设置界面时请以本文为“单一事实来源”的顺序先查速查表选原语再按 layout → controls → search 三份参考分类检查最后用完成标准逐项验收。赞分享AI Agent人工智能代码智能体交互助手【免费下载链接】openchamberAgentic Development Environment based on OpenCode AI agent项目地址https://gitcode.com/gh_mirrors/op/openchamber点击查看免费下载相关推荐OpenChamber 设置界面控件模式Settings Controls实战指南OpenChamber 设置界面控件模式Settings Controls实战指南 本文是 OpenChamber 设置界面开发的核心参考它以 settiAI Agent人工智能代码智能体交互助手构建响应式布局gh_mirrors/ui2/ui自适应界面设计构建响应式布局gh_mirrors/ui2/ui自适应界面设计 你是否还在为Go语言GUI应用的跨平台界面适配烦恼本文将带你使用gh_mirrors/ui2桌面应用UI组件跨平台OpenChamber 设置搜索Settings Search实现指南从显式注册表、可用性守卫到锚点高亮的完整链路OpenChamber 设置搜索Settings Search实现指南从显式注册表、可用性守卫到锚点高亮的完整链路 导读 OpenChamber 的设置页AI Agent人工智能代码智能体交互助手上一篇复现100券商金工研报QuantsPlaybook量化因子与择时策略实战指南下一篇WeFlow解锁跨平台前端工作流工具链实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考