@moheng-design/ui-skill 2.0.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -126,7 +126,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
126
126
 
127
127
  **用途。** Foundation 按钮,是按钮排版、几何、圆角与基础交互的唯一 Foundation Owner。
128
128
 
129
- **何时使用。** 本组件只供库内组件使用。业务页面的按钮一律用 `SystemButton`,不存在降级到本组件的情形。已登记契约为 14/20 字号、12px 行内内边距、4px 图标间隙、16px 圆角、32px 默认高度;16px 圆角在 32px 高度下使等宽图标按钮自然成圆,系统内没有独立的 pill 或 circle token。
129
+ **何时使用。** 本组件只供库内组件使用。业务页面的按钮一律用 `SystemButton`,不存在降级到本组件的情形。已登记契约为 14/20 字号、12px 行内内边距、4px 图标间隙、12px 圆角、32px 默认高度;等宽图标按钮为 12 圆角方形,系统内没有独立的 pill 或 circle token。
130
130
 
131
131
  **何时改用其他组件。**
132
132
 
@@ -225,13 +225,14 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
225
225
 
226
226
  ## Input
227
227
 
228
- **用途。** 单行文本控件,承担表单行与筛选行内的自由文本、数字与日期录入。
228
+ **用途。** 单行文本控件,承担表单行与筛选行内的自由文本与数字录入。
229
229
 
230
- **何时使用。** 值由用户自由键入、不来自固定选项集合时,该控件是默认选择。最小高度 32px、圆角 8px、字号 14/20px,宽度撑满父容器。置于 `Field` 内构成标准表单行;置于 `InputGroup` 内构成带前后附加物的单一焦点单元;日期录入由该控件与 `Calendar` 一起放进 `Popover` 组成。
230
+ **何时使用。** 值由用户自由键入、不来自固定选项集合时,该控件是默认选择。最小高度 32px、圆角 12px、字号 14/20px,宽度撑满父容器。置于 `Field` 内构成标准表单行;置于 `InputGroup` 内构成带前后附加物的单一焦点单元。
231
231
 
232
232
  **何时改用其他组件。**
233
233
 
234
234
  - 纯文本搜索 → `SearchField`。产品内每一处搜索共用该入口,不得用该控件自行拼装工具栏搜索框。
235
+ - 单个日期 → `DateInput`;工具栏里的日期区间筛选 → `ApplicationDateRangeFilter`。
235
236
  - 多行备注、说明与事由 → `Textarea`。
236
237
  - 定长验证码 → `InputOTP`。
237
238
  - 值来自固定集合 → `Select`;选项极多或密集的行内编辑器 → `NativeSelect`;需要输入筛选 → `Combobox`;2–5 个选项且需全部可见 → `RadioGroup`。
@@ -571,13 +572,14 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
571
572
 
572
573
  **用途。** 月格日期选择器控件,周一为一周起始(一…日),固定 252px 宽;今日为淡强调色洗,选中为强调色实心填充。
573
574
 
574
- **何时使用。** 作为日期字段的取值面板使用,与 `Input` 一同放进 `Popover`。筛选区间由调用方持有起止两个值,各配一个该组件。**该组件是控件,不是承载面** —— `CALENDAR` 页面模式与它同名但不同层,不得混用。
575
+ **何时使用。** 作为日期取值面板使用。表单里的单个日期直接用已封装好的 `DateInput`,工具栏的日期区间筛选用 `ApplicationDateRangeFilter`,两者内部都是本组件;只有这两者都不适用的自定义面板才直接把本组件放进 `Popover`。**该组件是控件,不是承载面** —— `CALENDAR` 页面模式与它同名但不同层,不得混用。
575
576
 
576
577
  **何时改用其他组件。**
577
578
  - 整页的日历承载面(`pageMode` 为 `CALENDAR`):`ApplicationDataDisplay` 的 `presentation="Calendar"`,月格按 SKILL.md「呈现配方」的月历写法拼装。
578
579
  - 粒度切换加月格加当日议程栏的工作台面:`ScheduleCollaborationWorkspace`。
579
580
  - 查询工具栏中作为 `dataPresentation` 的日历呈现方式:由数据呈现区承担,不是本控件。
580
- - 日期已知且可直接键入:`Input`。
581
+ - 表单里的单个日期字段:`DateInput`。
582
+ - 查询工具栏里的日期区间筛选:`ApplicationDateRangeFilter`。
581
583
 
582
584
  **组合约定。** `onSelect` 收到的是本地零点的 `Date`;落库、比较与按日期匹配一律使用本地时区的 ISO 日期串。翻月游标由组件内部持有;`month` 的年月变化时视图跟随,年月不变的重渲染不重置用户已翻到的月份。网格只占一个 Tab 停顿,方向键逐日 / 逐周、Home / End 到周首 / 周末、PageUp / PageDown 跨月(加 Shift 跨年),Enter / 空格选中;日格的无障碍名称为完整日期加星期。`selected` 为单值,该组件不表达区间高亮。「今天」默认取当前本地日期;以服务端时间为准、服务端渲染或测试需要固定日期时传 `today`(`Date`,只取本地年月日),它同时决定今日高亮、未传 `month` 时的初始月份与无选中日时的 Tab 停顿。置于 `Popover` 内时面板宽度不得小于 252px,`Popover` 的默认 320px 已足够容纳。星期名、上一月与下一月的无障碍名称、以及「年」「月」标题为中文常量,本库单语言。
583
585
 
@@ -587,6 +589,26 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
587
589
  - 不得用该组件拼装 `CALENDAR` 页面模式的整页承载面。
588
590
  - 禁止覆盖 252px 宽度与日期格的几何。
589
591
 
592
+ ## DateInput
593
+
594
+ **用途。** 单个日期的录入控件:与 `Input` 同高同壳(32px、12px 圆角、1px 描边),右侧带 16px 日历图标,点击弹出 `Calendar` 月格,选中即回填并收起。
595
+
596
+ **何时使用。** 表单里需要录入一个日期(开票日期、到期日、生效日)时,必须使用本组件。值一律是本地时区的 ISO 日期串 `yyyy-mm-dd`,经 `value` / `onValueChange` 受控,或经 `defaultValue` 非受控;清空时回调给出空串。外壳是按钮而不是可键入的输入框,日期只能从月格里选。
597
+
598
+ **何时改用其他组件。**
599
+ - 查询工具栏里的日期区间筛选:改用 `ApplicationDateRangeFilter`。
600
+ - 自由文本或数字:改用 `Input`。
601
+ - 需要月格常驻展开、不收起的面板:直接用 `Calendar`。
602
+ - 整页的日历承载面:`ApplicationDataDisplay` 的 `presentation="Calendar"`。
603
+
604
+ **组合约定。** 置于 `Field` 内时,`Field.htmlFor` 与本组件的 `id` 成对设置,`id` 落在触发按钮上。`Field.error` 与本组件的 `invalid` 必须同时设置,两者不联动,与 `Input` 相同。`placeholder` 写明字段含义,如「选择开票日期」。以服务端时间为准、服务端渲染或测试需要固定日期时传 `today`,它透传给 `Calendar`。该组件不自带外边距,宽度撑满父容器,列宽由字段网格负责。
605
+
606
+ **禁止 / 使用边界。**
607
+ - 不得用 `Input` 加占位示例(「2026-07-28」)代替本组件录入日期。
608
+ - 不得用 `toISOString()` 生成或换算 `value` —— 在 UTC+8 下会错一天,一律用本地时区的 `yyyy-mm-dd`。
609
+ - 不得用两个本组件拼装工具栏里的日期区间筛选,那是 `ApplicationDateRangeFilter` 的职责,且它带「应用」提交与筛选标签回写。
610
+ - 禁止覆盖触发器的高度、圆角与描边,`className` 只用于布局定位。
611
+
590
612
  ## Accordion
591
613
 
592
614
  **用途。** 同一页内的堆叠式渐进披露,多个折叠区以 1px 分隔线相隔,无卡片、无阴影。
@@ -615,7 +637,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
615
637
  **组合约定。** 该组件只能作为 `ApplicationPageHeader` 的 `breadcrumb` 内容传入,间距与位置由上下文区负责,组件自身无外边距。中间层级按三态渲染:提供 `href` 渲染链接,仅提供 `onClick` 渲染按钮,两者都不提供渲染静态文本 —— 不可点击的层级必须走第三态,不得以空字符串或占位地址伪造链接。使用前端路由时必须同时提供 `href` 与 `onClick`,并在 `onClick` 内自行阻止默认跳转,组件不代为调用 `preventDefault`。末项无论是否提供 `href` 或 `onClick` 都渲染为当前页文本,两者在末项上均无效果。组件输出 `nav > ol > li` 结构,分隔字形在 `li` 内且对读屏隐藏。
616
638
 
617
639
  **禁止 / 使用边界。**
618
- - 不得放进 Shell 的三条导航带 —— `TopNavigationPrimaryBar` 契约已明令禁止在其中添加面包屑。
640
+ - 不得放进 Shell 的导航带 —— `TopNavigationPrimaryBar` 契约已明令禁止在其中添加面包屑。
619
641
  - 不得在页面并无真实层级时把面包屑作为装饰渲染。
620
642
  - 不得把末项写成链接,当前页不是可跳转目标。
621
643
  - 禁止用面包屑承担模块导航或页面动作。
@@ -694,20 +716,21 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
694
716
 
695
717
  ## Pagination
696
718
 
697
- **用途。** 裸分页步进器,只承担页码窗口与翻页。
719
+ **用途。** 裸分页步进器,承担「首页 · 上一页 · 页码窗口 · 下一页 · 末页」。
698
720
 
699
- **何时使用。** 仅在确实不需要结果总数与每页条数时使用该组件。页码窗口固定为「首页 + 当前页前后各 1 页 + 末页」,跳空处插省略号,最多 7 个槽位,不可配置。当前页带 `aria-current="page"`、强调色描边与淡强调色底,不只靠颜色表达。页码按钮视觉上只显示数字,可访问名为「第 N 页」。按钮高 28px,页码使用等宽数字,翻页时按钮不左右跳动。
721
+ **何时使用。** 仅在确实不需要结果总数与每页条数时单独使用该组件。页码窗口固定为「首页 + 当前页前后各 1 页 + 末页」,跳空处插省略号,最多 7 个槽位,不可配置。外观按 GAP Design kit「分页元素」:每一格 32×32、1px 线条描边、圆角 12、白底,间隔 4;四个步进键是 16px 纯图标,可访问名为「首页」「上一页」「下一页」「末页」。当前页带 `aria-current="page"`、强调色描边与主色 6% 底,不只靠颜色表达。页码按钮视觉上只显示数字(14/20 medium),可访问名为「第 N 页」;页码使用等宽数字,翻页时按钮不左右跳动。
700
722
 
701
- **何时改用其他组件。** 数据展示区的列表与表格页脚一律改用 `ListTablePagination`,它额外承载结果区间、总数与每页条数选择器。两者是替代关系而非包含关系:`ListTablePagination` 的形态是「上一页 · 当前页/总页数 · 下一页」两键步进,不渲染页码窗口。系统内无限滚动不作为分页的替代方案。
723
+ **何时改用其他组件。** 数据展示区的列表与表格页脚一律改用 `ListTablePagination`。两者是包含关系:`ListTablePagination` 内部渲染本组件作为页码区,另外承载摘要、每页条数选择器与跳页框(业财平台 round-01 起,兑现 04 · T6 的原裁决)。系统内无限滚动不作为分页的替代方案。
702
724
 
703
- **组合约定。** 调用方必须保证 `1 ≤ page ≤ pageCount`,组件不对越界值做钳制。`pageCount` 为 1 时组件仍渲染两枚禁用的翻页按钮与单个页码,只有一页时调用方应自行不渲染整个组件。分页状态在数据展示区内的规则与 `ListTablePagination` 相同(按业务视图各记一份,搜索、筛选、排序变化时复位到第 1 页,07 · C-13),该状态由调用方 Module 持有 —— 组件不持有任何页码状态。组件自身无外边距,与数据展示区的间距由容器负责。
725
+ **组合约定。** 调用方必须保证 `1 ≤ page ≤ pageCount`,组件不对越界值做钳制。`pageCount` 为 1 时组件仍渲染四枚禁用的步进键与单个页码,只有一页时调用方应自行不渲染整个组件。分页状态在数据展示区内的规则与 `ListTablePagination` 相同(按业务视图各记一份,搜索、筛选、排序变化时复位到第 1 页,07 · C-13),该状态由调用方 Module 持有 —— 组件不持有任何页码状态。组件自身无外边距,与数据展示区的间距由容器负责。
704
726
 
705
727
  **禁止 / 使用边界。**
706
728
  - 不得在列表或表格的标准页脚使用该组件。
707
729
  - 不得把该组件用作步骤指示器、轮播指示器或进度表达。
708
730
  - 禁止传入越界的 `page`。
709
731
  - 不得依赖该组件表达结果总数或每页条数,它不承载这两项。
710
- - 不得在同一数据展示区内同时渲染 Pagination 与 `ListTablePagination`。
732
+ - 不得在同一数据展示区内同时渲染 Pagination 与 `ListTablePagination` —— 后者已经包含前者。
733
+ - 不得把四个步进键改回文字按钮,也不得去掉首页与末页。
711
734
 
712
735
  ## Sidebar
713
736
 
@@ -717,7 +740,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
717
740
 
718
741
  **何时改用其他组件。** 工作台左侧 72px 图标栏改用 `GlobalSidebar`,它由 `SidebarRailButton` 构成,是另一个组件,两者不可互相替代。SPLIT 页面模式的左栏改用 `ApplicationSplitListSidebar`,它已登记目录搜索、结果数与目录设置三件事。水平方向的导航改用 `NavigationMenu` 或 `Tabs`。
719
742
 
720
- **组合约定。** 该组件不是 Shell —— 应用外层 Shell 是刻意设计的无侧栏四带堆叠,不得因为存在本组件就往 Shell 上加一条全局左栏。组件是 `flex: 0 0 auto` 且高度 100% 的 flex 项,必须置于一个高度确定的横向 flex 容器内。该组件只有受控模式:`value` 与 `onValueChange` 必须成对提供,缺少 `onValueChange` 时点击不产生任何变化。`collapsed` 为 true 时图标是唯一可见内容,因此可能折叠的侧栏中每个 `SidebarItem` 都必须提供 `icon`;`label` 为非字符串时还必须提供 `labelText`,否则折叠态条目既无可访问名也无提示。折叠态条目以 `aria-label` 命名,并由内置 `Tooltip` 在悬停与聚焦时向右提示同一名称,调用方不得再包一层 `Tooltip`。有标题的分组输出以标题命名的 `role="group"`。折叠态不渲染分组标题与 `badge`,唯一的状态提示不得只放在 `badge` 上。`width` 只作用于展开态,折叠宽固定 56px 不随其变化。`SidebarGroup.label` 用作 React key,应在侧栏内唯一。
743
+ **组合约定。** 该组件不是 Shell —— 应用外层 Shell 是刻意设计的无侧栏导航带堆叠(基础版两带、集团版三带),不得因为存在本组件就往 Shell 上加一条全局左栏。组件是 `flex: 0 0 auto` 且高度 100% 的 flex 项,必须置于一个高度确定的横向 flex 容器内。该组件只有受控模式:`value` 与 `onValueChange` 必须成对提供,缺少 `onValueChange` 时点击不产生任何变化。`collapsed` 为 true 时图标是唯一可见内容,因此可能折叠的侧栏中每个 `SidebarItem` 都必须提供 `icon`;`label` 为非字符串时还必须提供 `labelText`,否则折叠态条目既无可访问名也无提示。折叠态条目以 `aria-label` 命名,并由内置 `Tooltip` 在悬停与聚焦时向右提示同一名称,调用方不得再包一层 `Tooltip`。有标题的分组输出以标题命名的 `role="group"`。折叠态不渲染分组标题与 `badge`,唯一的状态提示不得只放在 `badge` 上。`width` 只作用于展开态,折叠宽固定 56px 不随其变化。`SidebarGroup.label` 用作 React key,应在侧栏内唯一。
721
744
 
722
745
  **禁止 / 使用边界。**
723
746
  - 不得把该组件当作应用外层 Shell 的全局左栏。
@@ -732,7 +755,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
732
755
 
733
756
  **何时使用。** 同一块区域内需要在 2 个及以上互斥内容之间切换时使用该组件。标签高 32px、内边距 6/12、文字 14/20,激活态是 2px 强调色下划线加 medium 字重,明确不是 pill 背景。标签行下方有 1px 分隔线,`count` 徽标为 12px 等宽数字。标签行只占一个 Tab 停靠点,左右方向键在可用标签之间移动焦点、首尾相接,Home / End 跳到首末项,选中须再按回车或空格;焦点离开后停靠点回到选中标签。
734
757
 
735
- **何时改用其他组件。** Shell 第三带的业务标签改用 `ApplicationSecondaryNavigation`,那里的图标是必填。L3 业务视图标签由 `ApplicationQueryToolbar` 承担,其第一行内部已组合本组件,不得在工具栏之外另起一行 Tabs 表达业务视图。Page Mode Switch 属于 `ApplicationPageHeader`,不得用 Tabs 或 `ToggleGroup` 搭建。密度、对齐这类局部显示选择改用 `ToggleGroup`。带浮层面板的水平导航改用 `NavigationMenu`。
758
+ **何时改用其他组件。** Shell 应用二级导航带的业务标签改用 `ApplicationSecondaryNavigation`,那里的图标是必填。L3 业务视图标签由 `ApplicationQueryToolbar` 承担,其第一行内部已组合本组件,不得在工具栏之外另起一行 Tabs 表达业务视图。Page Mode Switch 属于 `ApplicationPageHeader`,不得用 Tabs 或 `ToggleGroup` 搭建。密度、对齐这类局部显示选择改用 `ToggleGroup`。带浮层面板的水平导航改用 `NavigationMenu`。
736
759
 
737
760
  **组合约定。** `children` 原样渲染,组件不做面板切换 —— 调用方必须自行依据当前 `value` 渲染对应内容。面板的 12px 上边距由组件负责,调用方不得再补上边距。根与面板都是列向 flex,面板吃掉根的剩余高度:要让面板内的 `ApplicationDataDisplay` 拿到有界高度、自己滚动,调用方只需让 Tabs 根在定高父级里拿到高度(给根加 `flex: 1; min-block-size: 0` 的类名),不得再在面板外另造一个 `role="tabpanel"` 容器;面板的直接子节点各成一个 flex 项,行内混排的文字须包一层块级元素。可访问名称以 `aria-label` 或 `aria-labelledby` 传入,组件把它落在 `role="tablist"` 上;渲染面板时激活标签与面板以 `aria-controls` / `aria-labelledby` 互相关联,调用方不必补。`items` 为空数组时整个组件渲染 `null`,不渲染空标签行、不画分隔线、不保留高度,因此调用方不得为「暂无标签」另行渲染占位。未提供 `defaultValue` 时组件默认选中 `items[0].value` 且不检查其禁用状态,`items[0]` 为 `disabled` 时必须显式提供 `defaultValue`。受控使用时 `value` 与 `onValueChange` 必须成对提供。`count` 只接受数字。
738
761
 
@@ -779,7 +802,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
779
802
  **组合约定。** 本组件不持有外边距,卡片之间的间距(Standard 12px、Condensed 10px、Compact 8px)由父级栅格或 `ApplicationPageLayoutContainer` 负责。`title` 与 `extra` 同处标题行,`extra` 只放一个状态 `Badge` 或一个安静的动作。内边距与内部间隙随视口密度档自动收紧:`default` 为 Standard 16px、Condensed 12px、Compact 10px,`sm` 为 12px、Compact 10px,由 token 层的 `@media` 驱动,调用方不得另写断点改卡片内边距。`footer` 自带上边框与一段上内边距,不需要再在它上面放 `Separator`。`interactive` 只是把光标与边框反馈打开,跳转行为仍由调用方自己挂在卡片上 —— 因此 `interactive` 为 true 时必须同时给出真实的跳转处理(`onClick`),只设 `interactive` 而不跳转会得到一个骗人的指针。`interactive` 且给了 `onClick` 时组件自带键盘入口:标题读作按钮、进 Tab 序列,Enter / 空格触发同一个 `onClick`,焦点环画在整张卡上;无标题时整卡可聚焦。调用方不得再自行补 `tabIndex` / `role` / `onKeyDown` —— 显式传入 `tabIndex` 或 `role` 即视为接管,组件不再加自己那一份。标题行最小高度 32px,有无 `extra` 都一样高。`interactive` 为 true 时卡内不得再放独立的可点控件,除非该控件自行阻止事件冒泡。
780
803
 
781
804
  **禁止 / 使用边界。**
782
- - 不得给卡片添加阴影 —— 已登记契约为 16px 圆角、1px 边框、无默认装饰阴影,边框负责分隔。
805
+ - 不得给卡片添加阴影 —— 已登记契约为 20px 圆角、1px 边框、无默认装饰阴影,边框负责分隔。
783
806
  - 禁止发明第三档密度:只有 `default`(16px 节奏)与 `sm`(12px)两档,随视口收紧的是这两档的取值,不是新的档。
784
807
  - 不得在只读的指标卡语义上设置 `interactive` —— 指标卡必须保持 `cursor: default`,整卡绝不成为导航入口。
785
808
  - 不得在 Card 外面再包一层自带 padding 的容器,那会与页面内容根的内边距叠成双重外边距。
@@ -889,7 +912,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
889
912
 
890
913
  **用途。** DataTable 呈现方式的承载面 —— LIST 页面模式、LEDGER 台账页、SPLIT 右栏共用同一份表。
891
914
 
892
- **何时使用。** 数据需要按列对齐、逐列比较、按列排序时,必须使用本组件。它是数据驱动的:列写在 `columns`,行数据写在 `rows`。表头位于 `--application-table-header`,行与行之间用 1px 分隔线而非阴影。密度分 `default` 与 `sm` 两档,只影响单元格内边距。
915
+ **何时使用。** 数据需要按列对齐、逐列比较、按列排序时,必须使用本组件。它是数据驱动的:列写在 `columns`,行数据写在 `rows`。表头位于 `--application-table-header`,高 44px;表体单元格四边 16px 内边距,行最小高 56px(两行内容 72px);选择列 48px;行与行之间、表头列与列之间是 0.5px 分隔线而非阴影。密度分 `default` 与 `sm` 两档,只影响单元格内边距与行高下限。
893
916
 
894
917
  **何时改用其他组件。**
895
918
  - 列数过剩、但行仍需扫视 —— 改用 `ApplicationRecordList`,它是非表格形态的结构化列表。
@@ -898,7 +921,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
898
921
  - 只是一组同构的目录行,无列对齐需求 —— 改用 `Item`。
899
922
  - 需要手写 `<table>` / `<tr>` / `<td>` —— 一律改用本组件,手写表格拿不到已登记的表头底色、行分隔线与列宽约定。
900
923
 
901
- **组合约定。** 本组件不持有外边距,与相邻区块的间隙由 `ApplicationDataDisplay` 与 `ApplicationPageLayoutContainer` 负责;横向溢出在组件内部消化,外部不得再套横向滚动容器。`selectable` 为 true 时必须同时提供 `selected` 与 `onSelectedChange`,否则勾选框点了没有任何反应;选择框由 `ListSelectionCheckbox` 承担,勾选不会顺带触发 `onRowClick`;它的可访问名是「选择」加标题列(首个 `priority: 'primary'` 的列,未声明取首列)单元格的内容。给了 `onRowClick` 的行可聚焦,Enter / 空格触发同一回调,行保留表格行语义、不改作按钮。行点击与按键忽略来自行内可交互元素(按钮、链接、勾选框、菜单等)的事件,`render` 里放这类控件时调用方不必再手动阻止冒泡。任一列设了 `sortable` 时必须同时提供 `sort` 与 `onSortChange`,同列再次点击在 `asc` 与 `desc` 间切换。放进 `ApplicationDataDisplay` 时,表头排序是工具栏 `sort` 槽位(`Select`)的第二入口,`sort` 必须与工具栏取自同一份排序状态(07 · C-2)。`rowKey` 必须指向 `rows` 中真实存在且唯一的字段,缺省值是 `id`。每一列都应显式设置 `priority`:`low` 列在 1180px 宽或 720px 高以下整列隐藏,单元格内边距在 1439px 以下先行压缩,顺序即「先压间距,再压列数,再压优先级」。单独使用时 `rows` 为空必须提供 `empty`,且应当传 `<Empty />`;放进 `ApplicationDataDisplay` 时不另设 `empty`,空结果由数据展示区的 `state="empty"` 与 `empty` 槽位承担(07 · C-6)。批量动作条与分页不属于本组件,分别走 `ApplicationDataDisplay` 的 `batchBar` 与 `pagination` 槽位,前者传 `ListBatchActionBar`,后者传 `ListTablePagination`。
924
+ **组合约定。** 本组件不持有外边距,与相邻区块的间隙由 `ApplicationDataDisplay` 与 `ApplicationPageLayoutContainer` 负责;横向溢出在组件内部消化,外部不得再套横向滚动容器。`selectable` 为 true 时必须同时提供 `selected` 与 `onSelectedChange`,否则勾选框点了没有任何反应;选择框由 `ListSelectionCheckbox` 承担,勾选不会顺带触发 `onRowClick`;它的可访问名是「选择」加标题列(首个 `priority: 'primary'` 的列,未声明取首列)单元格的内容。给了 `onRowClick` 的行可聚焦,Enter / 空格触发同一回调,行保留表格行语义、不改作按钮。行点击与按键忽略来自行内可交互元素(按钮、链接、勾选框、菜单等)的事件,`render` 里放这类控件时调用方不必再手动阻止冒泡。任一列设了 `sortable` 时必须同时提供 `sort` 与 `onSortChange`,同列再次点击在 `asc` 与 `desc` 间切换。放进 `ApplicationDataDisplay` 时,表头排序是工具栏 `sort` 槽位(`Select`)的第二入口,`sort` 必须与工具栏取自同一份排序状态(07 · C-2)。`rowKey` 必须指向 `rows` 中真实存在且唯一的字段,缺省值是 `id`。每一列都应显式设置 `priority`:`low` 列在 1180px 宽或 720px 高以下整列隐藏,单元格内边距在 1439px 以下先行压缩,顺序即「先压间距,再压列数,再压优先级」。单独使用时 `rows` 为空必须提供 `empty`,且应当传 `<Empty />`;放进 `ApplicationDataDisplay` 时不另设 `empty`,空结果由数据展示区的 `state="empty"` 与 `empty` 槽位承担(07 · C-6)。批量动作条与分页不属于本组件,分别走 `ApplicationDataDisplay` 的 `batchBar` 与 `pagination` 槽位,前者传 `ListBatchActionBar`,后者传 `ListTablePagination`。有设计稿时,每一列的 `width` 取设计稿的列宽:固定宽的列写数字,弹性列不写 `width`,由表格均分剩余宽度 —— 不得全部留空交给浏览器按内容分配。列数多、需要横向滚动时,末列「操作」写 `fixed: 'right'` 贴住右缘,首列标题列可写 `fixed: 'left'`;只允许首列声明 `left`、末列声明 `right`,每侧至多一列。附着在列表末尾的进行中状态(「识别中…」「正在加载更多」)经 `trailingRow` 渲染为一条横跨全部列的通栏行,`busy` 为 true 时带扫光动效;`rows` 为空时它不渲染。
902
925
 
903
926
  **禁止 / 使用边界。**
904
927
  - 禁止手写 `<tr>` / `<td>` 作为子元素传入 —— 本组件不接受复合子组件,列与行只能来自 `columns` 与 `rows`。
@@ -906,6 +929,8 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
906
929
  - 不得为 LIST 页面模式与 SPLIT 右栏各写一份近乎相同的表,同一份业务数据只允许一份实现。
907
930
  - 不得在单元格内嵌套第二个 `Table`。
908
931
  - 不得省略 `priority`,缺省会让窄视口下的降级顺序不可预期。
932
+ - 不得用 `trailingRow` 承载数据行、合计行或分组标题,它只表达列表末尾的进行中状态。
933
+ - 不得给中间列声明 `fixed`,也不得在同一侧固定两列 —— 组件不计算多列叠加偏移,滚动时会重叠。
909
934
 
910
935
  ## Empty
911
936
 
@@ -950,18 +975,18 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
950
975
 
951
976
  ## Badge
952
977
 
953
- **用途。** 紧凑的状态或分类标签,20px 高、4px 圆角、12/16 字号。
978
+ **用途。** 紧凑的状态或分类标签,24px 高、20px 圆角(胶囊)、左右 10 上下 4 内边距、12/16 字号。
954
979
 
955
980
  **何时使用。** 列表行、卡片、指标、详情头需要一个短状态词或分类词时,必须使用该组件。`RecordListItem` 与 `WorkspacePerson` 的 `status` 槽位、`Card` 的 `extra` 槽位、`Item` 的 `trailing` 槽位登记的默认内容即为本组件。`tone` 的六档全部来自功能状态色板,一个 tone 在同一维度内只能有一个含义。
956
981
 
957
982
  **何时改用其他组件。**
958
983
  - 指标区里的「功能状态 + 计数」改用 `ApplicationMetricStatus`,该卡由圆点、文字、颜色三者共同承载状态。
959
- - 已生效的筛选条件改用 `ApplicationQueryToolbar` 的 `appliedTags`,它自带逐项移除与重置全部。
984
+ - 已生效的筛选条件改用 `ApplicationQueryToolbar` 的 `appliedTags`,它自带逐项移除与「清空」。
960
985
  - 需要说明成因并给出重试出路的整段提示改用 `Alert`。
961
986
  - 一级导航上的未读提示改用 `ApplicationPrimaryNavigation` 的 `actionBadges` 圆点;消息条目的未读态改用 `Message` 的 `unread`。
962
- - 键盘按键提示改用 `Kbd`,二者同为 20px 高,语义不同,不得互换。
987
+ - 键盘按键提示改用 `Kbd`,二者语义不同,不得互换。
963
988
 
964
- **组合约定。** `tone` 与业务状态的对应关系必须在应用侧集中定义一次,禁止逐页面各写一份。tone 只在同一维度内含义唯一:同屏出现两个状态维度(如处理状态与风险等级)时,用 `variant` 区分维度 —— 一个维度用 `soft`(淡色实底),另一个用 `outline`(描边),两个维度可以各用到同一个 tone(07 · C-9);同一维度内的不同取值不得共用 tone。外边距由宿主槽位负责,本组件自身不带 margin 且不换行,内容超长时由宿主决定截断。`variant="outline"` 的边框取 tone 的语义色,而 `warning` 的前景为保证对比度取中性色,这是已裁决的刻意不同构(04 · D3),应用侧不得把前景「修正」回同色系。`children` 必须是 2–4 字裸名词短语。
989
+ **组合约定。** `tone` 与业务状态的对应关系必须在应用侧集中定义一次,禁止逐页面各写一份。tone 只在同一维度内含义唯一:同屏出现两个状态维度(如处理状态与风险等级)时,用 `variant` 区分维度 —— 一个维度用 `soft`(淡色实底),另一个用 `outline`(描边),两个维度可以各用到同一个 tone(07 · C-9);同一维度内的不同取值不得共用 tone。外边距由宿主槽位负责,本组件自身不带 margin 且不换行,内容超长时由宿主决定截断。`soft` 档的底色一律是 tone 语义色的 10% 透明(`neutral` 为文字色 6%),前景与描边取 tone 的语义色,`warning` 也不例外(GAP Design kit;此前 `warning` 前景取中性灰,已随警示色调深为 #ff7b00 改回同色系)。`children` 必须是 2–4 字裸名词短语。
965
990
 
966
991
  **禁止 / 使用边界。**
967
992
  - 不得用图表分类色表达状态 —— 分类色只编码分类。
@@ -1040,7 +1065,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1040
1065
  - 业务记录行改用 `ApplicationRecordList`;表格行改用 `Table`。
1041
1066
  - 需要说明成因并提供重试出路的整段提示改用 `Alert`。
1042
1067
 
1043
- **组合约定。** `avatar` 槽位应传 `Avatar`。一组本组件作为 `ApplicationGlobalActionPanel` 的 `children` 传入,该面板是消息、待办、运行总览、风险预警四个全局动作共享的同一个面板,绝不为每个动作单独造一个弹层。行内边距由本组件自身承担,条目之间不得再加外边距,间距由容器的排列负责。`unread` 为 true 时淡色底与圆点必须同时出现,不得只保留其一。`author` 为 14/20,`time` 为 12/16,二者按基线对齐,因此传入内容应是短文本,不得塞入块级结构。整条可点开时直接给 `onClick`:组件随之给出指针与 hover 反馈,读作按钮、进 Tab 序列,Enter / 空格触发同一回调,调用方不得再自行补键盘处理。无条目时的空态由 `ApplicationGlobalActionPanel` 的 `emptyState` 承担,应传 `Empty`,其文案须区别于无权限与加载失败。
1068
+ **组合约定。** `avatar` 槽位应传 `Avatar`。一组本组件作为 `ApplicationGlobalActionPanel` 的 `children` 传入,该面板是消息、待办、总览、风险预警四个全局动作共享的同一个面板,绝不为每个动作单独造一个弹层。行内边距由本组件自身承担,条目之间不得再加外边距,间距由容器的排列负责。`unread` 为 true 时淡色底与圆点必须同时出现,不得只保留其一。`author` 为 14/20,`time` 为 12/16,二者按基线对齐,因此传入内容应是短文本,不得塞入块级结构。整条可点开时直接给 `onClick`:组件随之给出指针与 hover 反馈,读作按钮、进 Tab 序列,Enter / 空格触发同一回调,调用方不得再自行补键盘处理。无条目时的空态由 `ApplicationGlobalActionPanel` 的 `emptyState` 承担,应传 `Empty`,其文案须区别于无权限与加载失败。
1044
1069
 
1045
1070
  **禁止 / 使用边界。**
1046
1071
  - 不得把本组件当作会话气泡使用。
@@ -1139,13 +1164,14 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1139
1164
  - 可撤销的已完成事实改用 `Sonner`,并把撤销放进它的 `action`。
1140
1165
  - 不阻断主任务的失败提示改用 `Alert`。
1141
1166
 
1142
- **组合约定。** 该组件宽度固定为 420px,不接受尺寸调整。点击遮罩不关闭 —— 破坏性确认必须是显式选择;Esc 仍然可用,等同于取消,不会误触发确认。`onCancel` 同时承担取消按钮、右上角关闭按钮与 Esc 三条路径,缺省它会使该组件无法关闭。右上角关闭按钮的无障碍名称固定为「关闭」,与取消按钮可区分;打开时初始焦点落在取消按钮,误按 Enter 不会触发确认。`cancelText` 必须是 2–4 字裸名词短语,不得写成句子。面板以 `role="alertdialog"` 输出,`title` 与 `description` 分别作为它的可访问名与描述。确认与取消按钮由该组件内部渲染,调用方不得再在 `children` 中放置一组按钮;`children` 只用于列出受影响对象。
1167
+ **组合约定。** 该组件宽度固定为 680px、最小高 240px,不接受尺寸调整;面板圆角 20(GAP Design kit「弹窗 / 提示」),与其余模态弹窗同一角色。页头、主体、页脚与 `Dialog` 同一套三段结构:页头在标题前固定显示 20px 的 `circle-alert` 提示图标(警示色,`destructive` 与否都不变 —— 破坏性只由确认按钮的 danger 色表达),`description` 在主体内上下居中、16/20 居中排版。点击遮罩不关闭 —— 破坏性确认必须是显式选择;Esc 仍然可用,等同于取消,不会误触发确认。`onCancel` 同时承担取消按钮、右上角关闭按钮与 Esc 三条路径,缺省它会使该组件无法关闭。右上角关闭按钮的无障碍名称固定为「关闭」,与取消按钮可区分;打开时初始焦点落在取消按钮,误按 Enter 不会触发确认。`cancelText` 必须是 2–4 字裸名词短语,不得写成句子。面板以 `role="alertdialog"` 输出,`title` 与 `description` 分别作为它的可访问名与描述。确认与取消按钮由该组件内部渲染,调用方不得再在 `children` 中放置一组按钮;`children` 只用于列出受影响对象。
1143
1168
 
1144
1169
  **禁止 / 使用边界。**
1145
1170
  - 不得在 `children` 中放置输入控件或表单字段。
1146
1171
  - 禁止把标题写成不含数量与后果的泛化问句。
1147
1172
  - 不得在本组件之上再叠加任何模态浮层 —— 它本身就是「模态之上放行的那一层」,再往上即超过一层(06 · D-3)。
1148
1173
  - 不得依赖点击遮罩关闭,该路径已按契约关闭。
1174
+ - 不得在 `title` 或 `children` 里再放一个警示图标 —— 页头已固定显示,重复出现即为两枚。
1149
1175
 
1150
1176
  ## Collapsible
1151
1177
 
@@ -1171,17 +1197,17 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1171
1197
 
1172
1198
  **用途。** 模态容器,用于用户必须完成或放弃的聚焦任务 —— 新建、编辑、导入映射。
1173
1199
 
1174
- **何时使用。** 当任务需要用户在离开前完成或明确放弃、且不适合占用整页时,该组件是默认的物理容器。已登记宽度为 `small` 720px、`large` 960px;`size` 也接受任意数字,但无论取值如何都受 `max-width: 100%` 与视口边距约束。
1200
+ **何时使用。** 当任务需要用户在离开前完成或明确放弃、且不适合占用整页时,该组件是默认的物理容器。已登记宽度为 `small` 720px、`large` 960px;`size` 也接受任意数字,但无论取值如何都受 `max-width: 100%` 与视口边距约束。面板圆角 20(GAP Design kit「抽屉弹窗 / 弹窗」),取模态弹窗角色 `--ds-radius-dialog`,与 `AlertDialog`、`ApplicationFormDialog`、`PeoplePickerDialog` 一致。版式照 kit 类型=默认:页头、主体、页脚三段同为导航背景色,页头最小高 48、标题 16/20 medium、右侧 32×32 关闭键,页脚动作间隔 4,两处分隔线均为 0.5px;面板最小高 240。
1175
1201
 
1176
1202
  **何时改用其他组件。**
1177
1203
  - 完整业务表单改用 `ApplicationFormDialog`,它拥有已登记的字段网格与提交语义。
1178
1204
  - 不可逆动作的确认改用 `AlertDialog`。
1179
1205
  - 业务对象详情改用 `Drawer` 或独立详情页。
1180
- - 辅助性内容(设置、帮助、附件预览)改用 `Sheet`。
1206
+ - 辅助性内容(帮助、附件预览)改用 `Sheet`;全局设置是 `ApplicationSecondaryNavigation` 里的设置模块,不进任何浮层。
1181
1207
  - 无需阻断背景的锚定面板改用 `Popover`。
1182
1208
  - 全局命令面板改用 `Command` 的 `dialog` 形态,不要把 `Command` 放进本组件。
1183
1209
 
1184
- **组合约定。** 该组件与 `AlertDialog`、`Drawer`、`Sheet` 共用同一个模态基座,因此自带遮罩、Esc 关闭、焦点陷阱、关闭后焦点恢复与背景滚动锁定,调用方不得再自行实现这五件事,也不得自行设置 `z-index`。`onClose` 同时承担遮罩点击与关闭按钮两条路径。打开时焦点默认落在面板内首个可聚焦元素,即标题栏的关闭按钮;主体以输入为主(新建、编辑)时应以 `initialFocus` 传入首个字段的 ref,焦点一次落定,不先经过关闭按钮。`footer` 右对齐,取消在左、主操作在右,其中至多一个 `SystemButton` 用 `intent="primary"`。主体区域内部滚动而标题与页脚固定,调用方不得在 `children` 外层再套一个滚动容器。`open` 为 false 时该组件渲染 null,内部状态随之丢失 —— 需要保留草稿的调用方必须自行持有该状态。
1210
+ **组合约定。** 该组件与 `AlertDialog`、`Drawer`、`Sheet` 共用同一个模态基座,因此自带遮罩、Esc 关闭、焦点陷阱、关闭后焦点恢复与背景滚动锁定,调用方不得再自行实现这五件事,也不得自行设置 `z-index`。`onClose` 同时承担遮罩点击与关闭按钮两条路径。打开时焦点默认落在面板内首个可聚焦元素,即标题栏的关闭按钮;主体以输入为主(新建、编辑)时应以 `initialFocus` 传入首个字段的 ref,焦点一次落定,不先经过关闭按钮。`footer` 右对齐,取消在左、主操作在右,其中至多一个 `SystemButton` 用 `intent="primary"`。页脚左侧的补充信息(条数、当前位置、保存状态)传 `footerNote`,由该组件排成 12/16 label 色并把动作挤到右侧,调用方不得在 `footer` 里自行拼一段说明文字。主体区域内部滚动而标题与页脚固定,调用方不得在 `children` 外层再套一个滚动容器。`open` 为 false 时该组件渲染 null,内部状态随之丢失 —— 需要保留草稿的调用方必须自行持有该状态。
1185
1211
 
1186
1212
  **禁止 / 使用边界。**
1187
1213
  - 不得在本组件内改变 `pageType` 或 `pageMode` —— 浮层只是物理容器,绝不创造新的页面类型或页面模式。
@@ -1197,7 +1223,8 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1197
1223
 
1198
1224
  **何时改用其他组件。**
1199
1225
  - 已登记的业务详情结构改用 `ApplicationDetailDrawer`,其主体须传 `ApplicationRecordDetailBody`。
1200
- - 辅助性内容(帮助、附件预览)改用 `Sheet`,它在结构上更轻,不承载业务记录。全局设置是例外,它由 `ApplicationPrimaryNavigation` 的 settings 动作以 `kind='drawer'` 打开,本组件与 `Sheet` 均可承载。
1226
+ - 辅助性内容(帮助、附件预览)改用 `Sheet`,它在结构上更轻,不承载业务记录。
1227
+ - 全局设置改用 `ApplicationSecondaryNavigation` 的设置模块 —— `ApplicationPrimaryNavigation` 的设置动作给出的 `kind` 是 `'module'`,不打开抽屉(GAP Design kit「框架结构 / 结构=设置」)。
1201
1228
  - 需要用户完成或放弃的聚焦任务改用 `Dialog`。
1202
1229
  - 需要深链接指向的详情改用独立详情页,不得用抽屉承接。
1203
1230
 
@@ -1207,7 +1234,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1207
1234
  - 不得把深链接指向抽屉状态。
1208
1235
  - 禁止把关闭动作的文案写成「返回」。
1209
1236
  - 不得在抽屉内再打开第二个抽屉、对话框或侧板。模态之上至多再叠一层确认框(`AlertDialog`)或选择器(`PeoplePickerDialog`),更深的嵌套一律禁止(06 · D-3):抽屉里的删除必须经 `AlertDialog` 确认,确认框直接叠在抽屉之上,不得为此先关抽屉。
1210
- - 不得承载帮助、附件预览一类辅助性面板 —— 那些走 `Sheet`;全局设置是唯一例外,它由 `ApplicationPrimaryNavigation` 的 settings 动作以 `kind='drawer'` 打开。
1237
+ - 不得承载帮助、附件预览一类辅助性面板 —— 那些走 `Sheet`;也不得承载全局设置 —— 它是二级导航里的设置模块。
1211
1238
 
1212
1239
  ## DropdownMenu
1213
1240
 
@@ -1259,7 +1286,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1259
1286
  - 条目清单式的低频动作改用 `DropdownMenu`。
1260
1287
  - 表单与筛选行中的取值改用 `Select`,需要输入筛选改用 `Combobox`。
1261
1288
  - 查询工具栏的筛选维度改用 `ApplicationFilterMenu`。
1262
- - 消息 / 待办 / 运行总览 / 风险预警四个全局动作共享的弹层改用 `ApplicationGlobalActionPanel`,其 720px 宽、20px 圆角、680px 最高的几何已登记。
1289
+ - 消息 / 待办 / 总览 / 风险预警四个全局动作共享的弹层改用 `ApplicationGlobalActionPanel`,其 720px 宽、20px 圆角、680px 最高的几何已登记。
1263
1290
  - 用户必须完成或放弃的任务改用 `Dialog`。
1264
1291
 
1265
1292
  **组合约定。** 该组件是非模态浮层:不锁背景滚动、不陷阱焦点,Esc、外部点击与焦点离开(焦点从 `trigger` 或面板移到两者之外,如 Tab 出去)都会关闭并触发 `onOpenChange`;焦点离开引起的关闭不归还焦点。关闭时焦点若在面板内(Esc,或面板内的控件经 `onOpenChange(false)` 收起),焦点回到 `trigger`,因此在 `Dialog` 内使用时焦点不会逃出对话框。受控模式下 `open` 与 `onOpenChange` 必须成对出现。组件向 `trigger` 注入 `aria-expanded`,因此 `trigger` 必须是单个能接收该属性的 React 元素,调用方不得在 `trigger` 上再写一个;传入纯字符串时属性不会注入。触发器由别的组件渲染、只经回调交出元素时(`TopNavigationPrimaryBar` 的 `onAppSwitch` / `onAccount`),把该元素传给 `anchor` 并受控使用:面板贴它定位,点它不算外部点击,收起时焦点还给它,Tab 从它直接进入面板、从面板末项接着走它之后的元素;此时不渲染 `trigger`、组件根不占布局,`aria-expanded` 由渲染触发器的那个组件输出。`radius` 应传 token 而非字面值。作为「更多筛选」入口时,生效条件必须回写到 `ApplicationQueryToolbar` 第三行的筛选标签行。层级由已登记的浮层 z-index 承担,调用方不得自行设置。
@@ -1272,23 +1299,24 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1272
1299
 
1273
1300
  ## Sheet
1274
1301
 
1275
- **用途。** 从任意边缘滑出的面板,用于辅助性内容 —— 从一级导航打开的「设置」面板、帮助面板、附件预览。
1302
+ **用途。** 从任意边缘滑出的面板,用于辅助性内容 —— 帮助面板、附件预览。
1276
1303
 
1277
- **何时使用。** 当内容是全局性的辅助配置或参考信息、不属于任何一条业务记录时,该组件是默认选择。四个 `side` 方向均实际生效:左右向时 `size` 为宽度,上下向时为高度,正交方向一律铺满。默认尺寸 420px。
1304
+ **何时使用。** 当内容是辅助性的参考信息、不属于任何一条业务记录时,该组件是默认选择。四个 `side` 方向均实际生效:左右向时 `size` 为宽度,上下向时为高度,正交方向一律铺满。默认尺寸 420px。
1278
1305
 
1279
1306
  **何时改用其他组件。**
1280
1307
  - 业务对象详情改用 `Drawer`(680px)或独立详情页 —— 本组件在结构上比抽屉更轻,不承载业务记录。
1281
1308
  - 已登记的业务详情结构改用 `ApplicationDetailDrawer`。
1282
1309
  - 需要用户完成或放弃的聚焦任务改用 `Dialog`。
1283
- - 消息 / 待办 / 运行总览 / 风险预警四个全局动作改用 `ApplicationGlobalActionPanel`;设置不走该面板,走本组件或 `Drawer`。
1284
- - 工具栏的呈现设置面板(列设置、看板设置等)改用 `Popover`,与更多筛选同一承载 —— 本组件的「设置」指全局设置(07 · C-7)。
1310
+ - 消息 / 待办 / 总览 / 风险预警四个全局动作改用 `ApplicationGlobalActionPanel`。
1311
+ - 全局设置改用 `ApplicationSecondaryNavigation` 的设置模块 —— 一级导航的设置动作让二级导航整带换成设置模块,不打开本组件(GAP Design kit「框架结构 / 结构=设置」)。
1312
+ - 工具栏的呈现设置面板(列设置、看板设置等)改用 `Popover`,与更多筛选同一承载(07 · C-7)。
1285
1313
 
1286
- **组合约定。** 该组件与 `Dialog`、`AlertDialog`、`Drawer` 共用同一个模态基座,因此自带 Esc 关闭、焦点陷阱、焦点恢复与背景滚动锁定。该组件没有固定底部动作区 —— 需要提交按钮常驻底部的载体改用 `Drawer`。主体区域内部滚动,标题栏高度对齐内容区标题栏。全局设置在整个产品中只能有一个入口,该入口打开本组件或 `Drawer`,不得同时存在第二处。
1314
+ **组合约定。** 该组件与 `Dialog`、`AlertDialog`、`Drawer` 共用同一个模态基座,因此自带 Esc 关闭、焦点陷阱、焦点恢复与背景滚动锁定。该组件没有固定底部动作区 —— 需要提交按钮常驻底部的载体改用 `Drawer`。主体区域内部滚动,标题栏高度对齐内容区标题栏。全局设置在整个产品中只有一个入口(一级导航的设置动作),它打开的是二级导航里的设置模块,不经本组件承载。
1287
1315
 
1288
1316
  **禁止 / 使用边界。**
1289
1317
  - 不得用本组件承载业务对象详情。
1290
1318
  - 禁止在本组件内放置需要固定在底部的提交动作。
1291
- - 不得为「设置」建立第二个入口。
1319
+ - 不得用本组件承载全局设置,也不得为「设置」建立第二个入口。
1292
1320
  - 不得在本组件之上再叠加抽屉或对话框。
1293
1321
 
1294
1322
  ## Sonner
@@ -1373,7 +1401,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1373
1401
 
1374
1402
  **用途。** 查询工具栏主控制行中的常驻快捷筛选触发器,承载**一个**高频筛选维度的取值。
1375
1403
 
1376
- **何时使用。** 该维度在结果集上高频使用、取值为短词且数量有限时,必须选用本组件。面板已登记 180px 最小宽与 280px 最高,取值控制在 8 项以内方能一屏读完。工具栏内至多常驻 2–3 个,其余维度一律下沉到「更多筛选」。触发器高 32px、圆角 16px,与同排的 `SearchField` 读作一行。
1404
+ **何时使用。** 该维度在结果集上高频使用、取值为短词且数量有限时,必须选用本组件。面板已登记 180px 最小宽与 280px 最高,取值控制在 8 项以内方能一屏读完。工具栏内至多常驻 2–3 个,其余维度一律下沉到「更多筛选」。触发器高 32px、圆角 12px,与同排的 `SearchField` 读作一行。
1377
1405
 
1378
1406
  **何时改用其他组件。**
1379
1407
  - 低频维度、或需要一次性提交多个维度:改用 `ApplicationFilterList`,它是「更多筛选」的面板主体,持有草稿并由「应用」提交。
@@ -1382,6 +1410,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1382
1410
  - 需要输入即筛选:改用 `Combobox`。
1383
1411
  - 局部显示选择(密度、对齐方式、局部视图标记):改用 `ToggleGroup`。
1384
1412
  - 键盘优先的全局搜索与执行:改用 `Command` 的 `dialog` 形态。
1413
+ - 日期区间维度:改用 `ApplicationDateRangeFilter`,同样放进 `commonFilters`。
1385
1414
 
1386
1415
  **组合约定。** 该组件必须作为 `ApplicationQueryToolbar` 的 `commonFilters` 内容出现,传 2–3 个;不得独立散落在页面其他位置。该组件只持有本维度的取值,已生效条件必须由调用方回写到 `ApplicationQueryToolbar` 的 `appliedTags`,并实现 `onRemoveTag` 与 `onResetTags`;筛选状态只存在于菜单内部是不合规的。`ApplicationFilterOption.label` 传入非字符串时,必须同时提供 `labelText`,否则触发器回显退化为 `[object Object]`。`multiple` 为 true 时 `value` 与 `defaultValue` 必须是数组,为 false 时必须是字符串;单选状态下再次点选当前值会清空该维度,`onValueChange` 必须能接收空字符串。面板自带定位、碰撞翻转与外点击关闭,调用方不得再包一层 `Popover` 或 `DropdownMenu`。`count` 必须与数据展示区当前口径下的结果数一致。该组件不自带外边距,横向间距由工具栏的 `--ui-control-gap` 负责。
1387
1416
 
@@ -1392,6 +1421,26 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1392
1421
  - 不得用它切换 `pageMode` 或 `dataPresentation`,这两者各有专属控件。
1393
1422
  - 不得覆盖触发器的高度、圆角与已生效态的三重信号(描边、淡底、回显)。
1394
1423
 
1424
+ ## ApplicationDateRangeFilter
1425
+
1426
+ **用途。** 查询工具栏主控制行中的日期区间快捷筛选,承载**一个**日期维度(接收时间、开票日期)的起止区间。
1427
+
1428
+ **何时使用。** 结果集需要按某个日期维度的区间筛选、且该维度高频使用时,必须使用本组件。触发器与 `ApplicationFilterMenu` 同高同壳,生效时回显「维度名:起 – 止」;面板里起止各一张 `Calendar`,选择是草稿,「应用」提交、「清空」撤销。值为 `{ start?, end? }`,两端都是本地时区 ISO `yyyy-mm-dd`,缺省一端表示该端不限。
1429
+
1430
+ **何时改用其他组件。**
1431
+ - 取值为有限枚举的维度:改用 `ApplicationFilterMenu`。
1432
+ - 表单里的单个日期字段:改用 `DateInput`。
1433
+ - 低频的日期维度:收进 `moreFilters` 的 `ApplicationFilterList` 面板,不常驻工具栏。
1434
+ - 整页按日期浏览:改用 `pageMode` 为 `CALENDAR` 的日历承载面。
1435
+
1436
+ **组合约定。** 该组件必须作为 `ApplicationQueryToolbar` 的 `commonFilters` 内容出现,与 `ApplicationFilterMenu` 合计常驻不超过 3 个。生效区间必须由调用方回写到 `appliedTags`(标签文案如「接收时间:2026-07-01 – 2026-07-28」),并在 `onRemoveTag` 里把区间清回 `{}`。`label` 为非字符串时必须提供 `labelText`,它同时是触发器回显与可访问名的来源。结束日期早于开始日期时「应用」禁用,组件不替调用方交换两端。区间两端都是闭区间(含当天),调用方换算成接口参数时自行补足时分。
1437
+
1438
+ **禁止 / 使用边界。**
1439
+ - 不得让已生效的区间只停留在触发器上而不回写筛选标签行。
1440
+ - 不得在面板外再包一层 `Popover` 或 `DropdownMenu`,面板自带定位与外点击关闭。
1441
+ - 不得放进 `ApplicationPageHeader` —— 上下文区禁止出现筛选。
1442
+ - 禁止在选到一半时发起查询,区间只经「应用」提交。
1443
+
1395
1444
  ## ListSelectionCheckbox
1396
1445
 
1397
1446
  **用途。** 结果集内的记录选择框,拥有选择语义,并承载表头的 mixed(半选)态。
@@ -1413,15 +1462,15 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1413
1462
 
1414
1463
  ## ListTablePagination
1415
1464
 
1416
- **用途。** 数据展示区的标准页脚 —— 结果区间、结果总数、每页条数与翻页步进。
1465
+ **用途。** 数据展示区的标准页脚 —— 摘要、每页条数、页码窗口与跳页。
1417
1466
 
1418
- **何时使用。** 结果集同时具备总数与每页条数需求时必须使用本组件,它是 LIST 页面模式的默认配置。形态固定为「第 X–Y 条 / 共 Z 条」加每页条数选择器加上一页 / 位置 / 下一页三件;位置视觉上是「3 / 10」,读屏读作「第 3 页,共 10 页」。每页条数默认档为 20 / 50 / 100,业务确有别的档位时通过 `pageSizeOptions` 覆盖。
1467
+ **何时使用。** 结果集同时具备总数与每页条数需求时必须使用本组件,它是 LIST 页面模式的默认配置。形态按 GAP Design kit「分页行」固定为:左侧「每页 N 条,共 Z 条数据」摘要(12/20 三级文字色),右侧依次为每页条数选择器、`Pagination`(首页 · 上一页 · 页码窗口 · 下一页 · 末页)与「第 [ ] 页」跳页框,控件一律 32 高、圆角 12、间隔 4。跳页框回车提交,输入越界时夹到 1 与总页数之间,提交后清空;总页数很少时可传 `showJumper={false}` 隐去。每页条数默认档为 20 / 50 / 100,业务确有别的档位时通过 `pageSizeOptions` 覆盖。
1419
1468
 
1420
1469
  **何时改用其他组件。**
1421
- - 既无总数也无每页条数需求:改用 `Pagination`,它是裸页码步进器,带首页 + 当前页 ±1 + 末页的页码窗口。
1422
- - 两者是替代关系而非包含关系:同一个数据展示区内只能出现其中一个。
1470
+ - 既无总数也无每页条数需求:改用 `Pagination`,它是本组件内部的页码区,可以单独使用。
1471
+ - 两者是包含关系:本组件已经渲染了 `Pagination`,同一个数据展示区内不得再另放一个。
1423
1472
 
1424
- **组合约定。** 该组件必须放进 `ApplicationDataDisplay` 的 `pagination` 槽位,固定在区域底部;该槽位不随 `state` 隐藏,因此 `state` 不为 `ready` 时调用方不得传入分页。分页状态按业务视图各记一份:切换 `businessView` 时回到该视图上次所在的页,切换 `pageMode` 与从详情返回时保持当前页;搜索、筛选、排序变化时复位到第 1 页(07 · C-13)。该组件是全受控的,这份状态由调用方持有。`onPageSizeChange` 之后通常应重置到第 1 页,调用方必须显式再调一次 `onPageChange`,组件不代劳。`total` 与 `ApplicationQueryToolbar` 的 `resultSummary` 必须取自同一口径的同一个数,否则页脚与摘要会互相打脸。每页条数选择器内部已复用 `NativeSelect`,调用方不得在旁边再挂一个 `Select`。该组件不自带外边距,与上方结果集的间距由数据展示区负责。
1473
+ **组合约定。** 该组件必须放进 `ApplicationDataDisplay` 的 `pagination` 槽位,固定在区域底部;该槽位不随 `state` 隐藏,因此 `state` 不为 `ready` 时调用方不得传入分页。分页状态按业务视图各记一份:切换 `businessView` 时回到该视图上次所在的页,切换 `pageMode` 与从详情返回时保持当前页;搜索、筛选、排序变化时复位到第 1 页(07 · C-13)。该组件是全受控的,这份状态由调用方持有。`onPageSizeChange` 之后通常应重置到第 1 页,调用方必须显式再调一次 `onPageChange`,组件不代劳。`total` 与 `ApplicationQueryToolbar` 的 `resultSummary` 必须取自同一口径的同一个数,否则页脚与摘要会互相打脸。每页条数选择器内部已复用 `NativeSelect`、页码区已复用 `Pagination`、跳页框已复用 `Input`,调用方不得在旁边再挂一个 `Select`、页码条或跳页输入。该组件不自带外边距,与上方结果集的间距由数据展示区负责。
1425
1474
 
1426
1475
  **禁止 / 使用边界。**
1427
1476
  - 不得在同一数据展示区内出现两处分页控件。
@@ -1481,7 +1530,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1481
1530
  - 该栏整体由 `GlobalSidebar` 渲染:改为向 `GlobalSidebar` 的 `items` 传数据(`icon` / `label` / `badge` / `separator`),本组件由它在内部渲染。栏底入口例外:`GlobalSidebar` 的 `footer` 直接放本组件(07 · C-15)。
1482
1531
  - 跨应用的快捷入口:改用 `SidebarAppLinkButton`。
1483
1532
  - Content Canvas 内部的通用垂直导航:改用 `Sidebar`,其折叠态即是 56px 图标栏。
1484
- - Shell 的四带导航:改用 `TopNavigationPrimaryBar`、`ApplicationPrimaryNavigation`、`ApplicationSecondaryNavigation`、`ApplicationModuleSwitcher`。
1533
+ - Shell 的导航带:改用 `TopNavigationPrimaryBar`、`ApplicationPrimaryNavigation`、`ApplicationSecondaryNavigation`、`ApplicationModuleSwitcher`。
1485
1534
 
1486
1535
  **组合约定。** `label` 不可省略 —— 规范禁止纯图标导航项。图标与标签是一个交互单元,禁用或淡化必须作用于整个条目。同一栏内至多一个条目设 `active`。`badge` 只承载未读计数或极短文本,长文案会溢出 14px 高的药丸;数字或文本徽标的视觉部分对读屏隐藏,条目名读作「标签,N 条」,调用方不得再把计数拼进 `label`。标签必须是 2–4 字裸名词短语,超出即被截断。分隔线通过 `GlobalSidebarEntry.separator` 表达,调用方不得在 `items` 之间手工插入 `Separator`。直接使用本组件时(即不经 `GlobalSidebar`),必须放进 56px 宽的列容器,条目之间的纵向间距由该容器负责,该组件不自带外边距。
1487
1536
 
@@ -1489,13 +1538,13 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1489
1538
  - 不得省略 `label`,纯图标导航项被规范禁止。
1490
1539
  - 不得只禁用图标或只淡化标签,二者必须整体一致。
1491
1540
  - 禁止在 `GlobalSidebar` 的 `items` 与 `footer` 之外再向该栏手工插入条目。
1492
- - 不得把它挪进应用外层 Shell —— Shell 是刻意设计的无侧栏、全宽四带堆叠。
1541
+ - 不得把它挪进应用外层 Shell —— Shell 是刻意设计的无侧栏、全宽导航带堆叠。
1493
1542
 
1494
1543
  ## SystemButton
1495
1544
 
1496
1545
  **用途。** 整个产品的默认动作按钮,是 Foundation `Button` 之上只承载应用意图、loading 与产品状态的薄适配层。
1497
1546
 
1498
- **何时使用。** 业务页面中的每一个按钮都必须使用本组件,没有例外;Foundation `Button` 只供库内组件使用。改一次应用强调色,全部 `SystemButton` 同时换肤,这个性质正是它存在的理由。该组件绝不重新实现按钮的排版与几何:14/20 字号、32px 高度、16px 圆角全部来自 Foundation `Button`。
1547
+ **何时使用。** 业务页面中的每一个按钮都必须使用本组件,没有例外;Foundation `Button` 只供库内组件使用。改一次应用强调色,全部 `SystemButton` 同时换肤,这个性质正是它存在的理由。该组件绝不重新实现按钮的排版与几何:14/20 字号、32px 高度、12px 圆角全部来自 Foundation `Button`。删除类动作分两档:`intent="destructive-outline"`(白底、危险色描边与文字)用于与次要按钮并排的删除,如表单里「删除此附件」;`intent="destructive"`(实心危险色)只用于 `AlertDialog` 里那个不可逆的最终确认,同一动作组内不得同时出现两档。
1499
1548
 
1500
1549
  **何时改用其他组件。**
1501
1550
  - 一组相关按钮需要拼接为分段控件或间隔簇:外层用 `ButtonGroup`,组内仍是 `SystemButton`。
@@ -1515,9 +1564,9 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1515
1564
 
1516
1565
  ## TopNavigationPrimaryBar
1517
1566
 
1518
- **用途。** Shell 第一带 `PLATFORM.TOP_USER_BAR`,承载平台级身份(品牌)与账户入口,跨全部应用与全部页面不变。
1567
+ **用途。** 集团版外壳的最上一带 `PLATFORM.TOP_USER_BAR`(GAP Design kit「集团顶部导航」),承载集团级身份(品牌)、应用切换与账户入口,跨全部应用与全部页面不变。
1519
1568
 
1520
- **何时使用。** 一个应用外壳必须且只能渲染一条本组件,作为四带堆叠的最上一层。它表达的是「用户在哪个平台、以什么身份」,与当前打开的是哪个应用、哪个模块、哪个页面全部无关。凡是随应用切换而变化的内容,均不属于本带。
1569
+ **何时使用。** 外壳有两种形态:基础版是「应用一级导航 + 应用二级导航」两带共 96px,不渲染本组件;集团版在两带之上再加本组件,三带共 144px。产品需要跨应用切换与集团品牌时用集团版,此时一个外壳必须且只能渲染一条本组件。它表达的是「用户在哪个集团、以什么身份」,与当前打开的是哪个应用、哪个模块、哪个页面全部无关。凡是随应用切换而变化的内容,均不属于本带。
1521
1570
 
1522
1571
  **何时改用其他组件。**
1523
1572
  - 应用身份(logo、应用名、应用说明)与五个全局动作:改用 `ApplicationPrimaryNavigation`。
@@ -1526,40 +1575,43 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1526
1575
  - 层级回溯路径:改用 `Breadcrumb`,且只能出现在上下文区。
1527
1576
  - 跨应用跳转的条目:改用 `SidebarAppLinkButton` 渲染在 `onAppSwitch` 打开的面板内。
1528
1577
 
1529
- **组合约定。** 本带高度由 `--ui-shell-primary-height` 决定(Standard 52px / Compact 44px),只有这两档;调用方不得用 `className` 或行内样式改高。三条导航带的 `position: fixed` 与层级由宿主布局承担(标准宿主 CSS 见 SKILL.md「五层 Canvas 模型 · 宿主布局」),组件本身按普通流元素渲染并输出 `data-shell-slot="top-navigation"` 供布局定位;堆叠总高读 `--ui-shell-application-total-height`,Content Canvas 据此让位。本带自持左右内边距与底部分隔线,宿主不得再加外边距。`brandLogoSrc` 缺省时自动回退到已登记 mock:28×28 纯色块 + 8px 间隙 + `brandName`;提供 `onAccount` 时应一并提供 `accountName`,账户按钮的可访问名与头像缩写均取自它,缩写规则与 `Avatar` 相同(中文取末字,「成员 A」→「A」;拉丁名取首字母)。`center` 默认为空,写入内容前必须确认该元素在 Shell 契约中已登记。 应用切换与账户两个面板用 `Popover` 承载:`onAppSwitch` / `onAccount` 的参数是被点的触发器,必须传给 `Popover` 的 `anchor` 锚定,不得另放空锚点凑位置;开合由调用方受控,回调里切换开合(再点触发器即收起),并把同一份状态回写到 `appSwitchOpen` / `accountOpen`,触发器据此输出 `aria-haspopup="dialog"` 与 `aria-expanded`,面板内容根相应声明 `role="dialog"` 与可访问名。
1578
+ **组合约定。** 本带高度由 `--ui-shell-primary-height` 决定(Standard 48px / Compact 40px),只有这两档;调用方不得用 `className` 或行内样式改高。导航带的固定与层级由宿主布局承担(标准宿主 CSS 见 SKILL.md「五层 Canvas 模型 · 宿主布局」),组件本身按普通流元素渲染并输出 `data-shell-slot="top-navigation"` 供布局定位;堆叠总高读 `--ui-shell-application-total-height`,Content Canvas 据此让位 —— 本组件在场时它的 CSS 把 `--ui-shell-top-bar-offset` 计入总高(96 → 144),宿主不必区分两种外壳。集团版的账户入口只在本带,`ApplicationPrimaryNavigation` 不得再传 `account`。本带自持左右内边距与 0.5px 底部分隔线,宿主不得再加外边距。品牌区按 GAP Design kit「集团顶部导航」:36×36 图形 + 8px 间隙 + `brandName`(20/30 semibold),宽度按内容;名称恒以文字渲染,图形位放 `brandLogoSrc`(图形标,按 36×36 `contain` 渲染,是装饰,`alt` 为空),缺省时自动回退到已登记 mock 纯色块 —— 不得传含企业名的横版字标,那会让名字出现两遍;提供 `onAccount` 时应一并提供 `accountName`,账户按钮的可访问名与头像缩写均取自它,缩写规则与 `Avatar` 相同(中文取末字,「成员 A」→「A」;拉丁名取首字母)。`center` 默认为空,写入内容前必须确认该元素在 Shell 契约中已登记。 应用切换与账户两个面板用 `Popover` 承载:`onAppSwitch` / `onAccount` 的参数是被点的触发器,必须传给 `Popover` 的 `anchor` 锚定,不得另放空锚点凑位置;开合由调用方受控,回调里切换开合(再点触发器即收起),并把同一份状态回写到 `appSwitchOpen` / `accountOpen`,触发器据此输出 `aria-haspopup="dialog"` 与 `aria-expanded`,面板内容根相应声明 `role="dialog"` 与可访问名。
1530
1579
 
1531
1580
  **禁止 / 使用边界。**
1532
1581
  - 不得在本带内加入搜索框、面包屑、通知铃铛、页面标题、卡片或阴影 —— Shell 契约禁止添加未登记元素。
1533
- - 禁止在 28×28 纯色块内部再绘制伪 Logo,该色块是占位而非标识。
1582
+ - 禁止在 36×36 纯色块内部再绘制伪 Logo,该色块是占位而非标识。
1534
1583
  - 不得出现第三种高度,也不得随 Condensed 档改变高度。
1535
1584
  - 不得在一个页面内渲染第二条本组件,也不得把它嵌进 Content Canvas。
1585
+ - 不得在基础版外壳里渲染本组件来承载账户入口 —— 基础版的账户入口是 `ApplicationPrimaryNavigation` 的 `account`。
1536
1586
 
1537
1587
  ## ApplicationPrimaryNavigation
1538
1588
 
1539
- **用途。** Shell 第二带 `APPLICATION.PRIMARY_NAV`,左侧是当前应用的身份,右侧是五个已登记全局动作的入口。
1589
+ **用途。** Shell 的应用一级导航带 `APPLICATION.PRIMARY_NAV`(GAP Design kit「应用一级导航」),左侧是当前应用的身份,右侧是五个已登记全局动作的入口;基础版外壳里账户头像也在这一带的最右端。
1540
1590
 
1541
- **何时使用。** 应用外壳必须在第一带之下渲染一条本组件。它是全局动作(消息、待办、运行总览、风险预警、设置)在整个产品中的唯一入口位置。应用级、跨页面、与当前业务页面无关的动作放在这里;只与当前页面有关的动作一律不放。
1591
+ **何时使用。** 应用外壳必须渲染一条本组件:基础版里它是第一带,集团版里它在 `TopNavigationPrimaryBar` 之下。它是全局动作(消息、待办、总览、风险预警、设置)在整个产品中的唯一入口位置。应用级、跨页面、与当前业务页面无关的动作放在这里;只与当前页面有关的动作一律不放。
1542
1592
 
1543
1593
  **何时改用其他组件。**
1544
1594
  - 页面级动作组(新建 / 导入 / 导出 / 更多、刷新):改用 `ApplicationPageHeader` 的动作槽位,按钮用 `SystemButton`。
1545
1595
  - 搜索、常用筛选、排序、列设置:改用 `ApplicationQueryToolbar`。
1546
1596
  - 模块切换与业务标签:改用 `ApplicationSecondaryNavigation`。
1547
- - 前四个动作打开的浮层内容:改用 `ApplicationGlobalActionPanel`;设置打开的浮层:改用 `Drawer` 或 `Sheet`。
1597
+ - 前四个动作打开的浮层内容:改用 `ApplicationGlobalActionPanel`;设置打开的设置模块:改用 `ApplicationSecondaryNavigation`(传 `onCloseSettings`)。
1548
1598
 
1549
- **组合约定。** 五个动作及其顺序(消息 → 待办 → 运行总览 → 风险预警 → 设置)固化在实现内部,不接受外部传入,「已登记」即指此。`onAction` 的第二个参数 `kind` 指明该动作应接哪一类浮层:四个 `popover` 动作必须共用同一个 `ApplicationGlobalActionPanel` 实例,一个面板四套内容;`drawer` 动作接抽屉。`activeAction` 与 `onAction` 必须成对使用,`activeAction` 只对 popover 动作产生 `aria-expanded`。`actionBadges` 的键只能取五个已登记动作键,且它只表达「有未读」而不表达数量。`appGlyph` 取图标 `registry.json` 中已登记的字形名,类型与 `<Icon name>` 同为 `IconName`。Compact 档(视口宽 ≤1180px 或高 ≤720px,与 Shell 三带高度切换同一断点)由 `@media` 自动隐藏 `appDescription`,logo、`appName` 与全部五个动作入口必须保留;宿主不得再读断点自行判定。`compact` 已弃用、下一个 minor 删除,新代码不得再传,传 `true` 仍强制紧凑。五个动作内置 `Tooltip`,悬停与聚焦时提示动作名,外观读 `--ui-shell-global-action-tooltip-*`,对应面板展开期间不提示;调用方不得再为它们包一层 `Tooltip`。本带自持内边距与底部分隔线,宿主不得再加外边距。
1599
+ **组合约定。** 五个动作及其顺序(消息 → 待办 → 总览 → 风险预警 → 设置)固化在实现内部,不接受外部传入,「已登记」即指此。`onAction` 的第二个参数 `kind`(`GlobalActionKind`)指明该动作的承载:四个 `popover` 动作必须共用同一个 `ApplicationGlobalActionPanel` 实例,一个面板四套内容;设置是唯一的 `module` 动作,调用方据此把 `ApplicationSecondaryNavigation` 换成设置模块并传 `onCloseSettings`(GAP Design kit「框架结构 / 结构=设置」),不打开任何浮层。`activeAction` 与 `onAction` 必须成对使用:设置模块开着时 `activeAction` 为 `'settings'`,设置动作随之带激活态;`activeAction` 只对 popover 动作产生 `aria-expanded`。`actionBadges` 的键只能取五个已登记动作键,且它只表达「有未读」而不表达数量。`appGlyph` 取图标 `registry.json` 中已登记的字形名(20px),类型与 `<Icon name>` 同为 `IconName`。几何按 kit:48 高(Compact 40)、内边距 8/12;logo 瓦片 32×32、圆角 8,应用名 14/20 regular,没有应用说明行;每个动作是「18px 字形 + 文字」,32 高、左右 10、圆角 12,文字 14/20 二级文字色,动作之间 4px。动作文字常显,不内置 `Tooltip`,调用方也不得再为它们包一层。基础版外壳传 `account`(`name` / `open` / `onToggle`),头像 24×24 圆形接在动作组之后 8px,面板接法与 `TopNavigationPrimaryBar.onAccount` 相同:`onToggle` 的参数是触发器,传给 `Popover` 的 `anchor`;集团版不得传 `account`。本带自持内边距与 0.5px 底部分隔线,宿主不得再加外边距。
1550
1600
 
1551
1601
  **禁止 / 使用边界。**
1552
1602
  - 禁止渲染第二个设置入口,无论它出现在本带、账户菜单还是页面内。
1553
1603
  - 不得增加、删除或重排五个全局动作,也不得把其中任意一个折叠进「更多」。
1554
1604
  - 不得把 logo 瓦片画成饱和强调色块 —— 它是 8% 强调色混入表面色的淡底。
1605
+ - 不得把五个动作改回纯图标,也不得在 Compact 档隐去它们的文字。
1555
1606
  - 不得为每个全局动作各造一个浮层,四个 popover 动作共用同一个面板。
1607
+ - 不得把设置接到 `Drawer`、`Sheet` 或 `ApplicationGlobalActionPanel` —— 它是二级导航里的设置模块。
1556
1608
  - 不得在本带承载页面标题、页面动作或数据控制。
1557
1609
 
1558
1610
  ## ApplicationSecondaryNavigation
1559
1611
 
1560
- **用途。** Shell 第三带 `APPLICATION.SECONDARY_NAV`,左侧是完整的模块切换器,右侧是当前模块的业务标签。
1612
+ **用途。** Shell 的应用二级导航带 `APPLICATION.SECONDARY_NAV`(GAP Design kit「应用二级导航」),左侧是完整的模块切换器,中间是当前模块的业务标签,最右是一枚已登记的尾部按钮 —— 平时是「导航设置」,设置模块里是「关闭设置」。
1561
1613
 
1562
- **何时使用。** 应用外壳必须在第二带之下渲染一条本组件。右侧标签表达的是「当前模块内的功能分区」,其集合随模块切换而整体更换。标签数量与内容由模块决定,不由页面决定。
1614
+ **何时使用。** 应用外壳必须在 `ApplicationPrimaryNavigation` 之下渲染一条本组件,它是外壳的最后一带。标签表达的是「当前模块内的功能分区」,其集合随模块切换而整体更换。标签数量与内容由模块决定,不由页面决定。全局动作「设置」打开时,本带整体换成设置模块(GAP Design kit「框架结构 / 结构=设置」):模块切换器显示设置模块名,标签换成设置项,尾部按钮变为关闭叉号 —— 设置不进任何抽屉、侧板或弹窗。
1563
1615
 
1564
1616
  **何时改用其他组件。**
1565
1617
  - 页面区域内的局部标签页(详情分节、SPLIT 右栏内容标签):改用 `Tabs`,那里图标是可选的。
@@ -1567,11 +1619,14 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1567
1619
  - Page Mode Switch:改用 `ApplicationPageHeader`。
1568
1620
  - 不强制图标的水平导航基元:改用 `NavigationMenu`。
1569
1621
  - Content Canvas 内的垂直导航:改用 `Sidebar`。
1622
+ - 导航设置打开的面板:改用 `Popover`,以 `onNavigationSettings` 交出的按钮为锚点。
1570
1623
 
1571
- **组合约定。** `moduleSwitcher` 槽位只接 `ApplicationModuleSwitcher`,不得传入 `Select`、`DropdownMenu` 或自制触发器。`SecondaryNavTab.icon` 在契约中是必填字段,图标必须来自已登记字形并通过 `Icon` 渲染,且其业务含义在 hover 与 active 下保持不变。`value` 与 `onValueChange` 必须成对使用;`tabs` 非空时 `value` 必须命中其中一项。切换模块时必须同时更换 `tabs` 与 `value`,不得让上一个模块的标签残留。标签行保持单行并横向滚动,滚动条已隐藏,调用方不得在外层再包一层滚动容器。激活态的 2px 下划线由组件绘制,调用方不得通过 `className` 叠加背景或边框。本带自持内边距与底部分隔线,宿主不得再加外边距。
1624
+ **组合约定。** `moduleSwitcher` 槽位只接 `ApplicationModuleSwitcher`,不得传入 `Select`、`DropdownMenu` 或自制触发器。`SecondaryNavTab.icon` 在契约中是必填字段,图标必须来自已登记字形并通过 `Icon` 渲染,且其业务含义在 hover 与 active 下保持不变。`value` 与 `onValueChange` 必须成对使用;`tabs` 非空时 `value` 必须命中其中一项。切换模块时必须同时更换 `tabs` 与 `value`,不得让上一个模块的标签残留。标签行保持单行并横向滚动,滚动条已隐藏,调用方不得在外层再包一层滚动容器。标签图标取 16px 档。几何按 kit:48 高(Compact 40),模块切换器贴左缘、右侧内边距 12,标签间隔 8;标签 32 高、内边距 6/12、文字 14/20 二级文字色;激活态为强调色 medium 文字加 2px 下划线(两端各缩进 12,贴标签底边);悬停为 6% 文字色淡底、圆角 12,文字不变色。激活态的下划线由组件绘制,调用方不得通过 `className` 叠加背景或边框。本带自持内边距与 0.5px 底部分隔线,宿主不得再加外边距。尾部按钮只有两种已登记形态,由回调决定,同一时刻至多一枚:传 `onNavigationSettings` 渲染「导航设置」(kit「二级导航设置」:32×32、圆角 12、透明底、16px `sliders-horizontal` 取二级文字色、悬停 6% 淡底,可访问名与提示「导航设置」),回调参数是点击事件,`event.currentTarget` 即 `Popover` 的锚点,面板开合回写 `navigationSettingsOpen`,按钮据此输出 `aria-haspopup="dialog"` 与 `aria-expanded`;传 `onCloseSettings` 即声明本带承载的是设置模块,尾部换成同一几何的关闭叉号(主要文字色,可访问名与提示「关闭设置」),根元素带 `data-mode="settings"`,此时不渲染导航设置。两个回调都不传时不渲染、不占位。设置模块由调用方组装:`ApplicationPrimaryNavigation` 的 `onAction` 收到 `kind='module'` 时,`moduleSwitcher` 照旧传 `ApplicationModuleSwitcher`(`moduleName` 为设置模块名、`modules` 为设置模块清单),`tabs` 换成设置项(同样必须带图标),`activeAction` 置为 `'settings'`,Content Canvas 渲染当前设置项的页面;`onCloseSettings` 里把模块切换器、`tabs` 与 `value` 换回进入设置前的那一组,并清掉 `activeAction`。
1572
1625
 
1573
1626
  **禁止 / 使用边界。**
1574
1627
  - 不得在本带承载 Page Mode、Business View、搜索、筛选、对象动作或页面级主操作。
1628
+ - 不得往尾部按钮的位置放其他元素 —— 它只有「导航设置」与「关闭设置」两种已登记形态。
1629
+ - 禁止把设置做成 `Drawer`、`Sheet` 或弹窗,也禁止在设置模块里省掉关闭叉号。
1575
1630
  - 禁止纯文字标签,也禁止为适应窄屏而丢弃全部图标。
1576
1631
  - 不得让标签换行 —— 单行横向滚动是已登记行为。
1577
1632
  - 不得把激活态改成 pill 背景,激活态是已登记的 2px 下划线。
@@ -1589,11 +1644,12 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1589
1644
  - 跨应用(而非跨模块)跳转:改用 `TopNavigationPrimaryBar` 的 `onAppSwitch`,条目用 `SidebarAppLinkButton`。
1590
1645
  - 工作台的图标菜单栏:改用 `GlobalSidebar`;Content Canvas 内的通用垂直导航:改用 `Sidebar`。
1591
1646
 
1592
- **组合约定。** `open` 与 `onOpenChange` 必须成对提供 —— 触发器点击只调用 `onOpenChange`,不提供该回调时面板永远无法打开。`currentModule` 必须命中 `modules` 中的一项。点击当前模块既不触发 `onSelect` 也不关闭面板;路由计算由调用方在 `onSelect` 中完成,组件不做任何跳转。面板是 `position: fixed`,顶边贴 `--ui-shell-application-total-height`,底边贴视口底,宽读 `--ui-shell-module-switch-panel-width`(320px)并受视口宽度限制;因此本组件的任何祖先元素都不得设置 `transform`、`filter` 或 `contain`,否则固定定位会改以该祖先为包含块而错位。触发器最小宽 168px、高 40px(Compact 148 / 32),几何由 Shell token 决定,调用方不得改写。`ModuleItem.icon` 与触发器的 `glyph` 均走 `Icon`,`glyph` 的登记尺寸是 18px。键盘按 menu button 模式:打开即聚焦首个可用模块(触发器上按 ↑ 打开则聚焦末项),↑ / ↓ / Home / End 在模块间移动;Esc、外部点击与 Tab 都经 `onOpenChange(false)` 收起,Esc 后焦点回到触发器 —— 调用方不得再自行监听 Esc 或外部点击。
1647
+ **组合约定。** `open` 与 `onOpenChange` 必须成对提供 —— 触发器点击只调用 `onOpenChange`,不提供该回调时面板永远无法打开。`currentModule` 必须命中 `modules` 中的一项。点击当前模块既不触发 `onSelect` 也不关闭面板;路由计算由调用方在 `onSelect` 中完成,组件不做任何跳转。几何按 GAP Design kit「应用二级模块切换」:触发器 168×48(Compact 148×40)、内边距 4/12、没有图标块,模块名 16/20 medium,20px chevron 右对齐,右侧 0.5px 分隔线,悬停与展开时 6% 淡底;面板挂在触发器正下方,与触发器同宽 168(最窄 128),内边距 4、条目间隔 2,限高到视口底、自身滚动;条目 40 高、内边距 8/12、圆角 12,悬停取导航背景,当前模块为强调色 semibold 加 14px 对勾。几何由 Shell token 决定,调用方不得改写。`ModuleItem.icon` 可选,kit 的模块条目不带图标,需要时走 `Icon`。键盘按 menu button 模式:打开即聚焦首个可用模块(触发器上按 ↑ 打开则聚焦末项),↑ / ↓ / Home / End 在模块间移动;Esc、外部点击与 Tab 都经 `onOpenChange(false)` 收起,Esc 后焦点回到触发器 —— 调用方不得再自行监听 Esc 或外部点击。
1593
1648
 
1594
1649
  **禁止 / 使用边界。**
1595
1650
  - 不得把触发器简化成一个小图标,也不得在窄屏下移除它。
1596
- - 禁止给面板加圆角、阴影或遮罩 —— 它只有 1px 右边线,是被推开的一块面而非浮起的卡片。
1651
+ - 禁止给面板加圆角、阴影或遮罩 —— 它只有 1px 右边线,是从触发器垂下的一截而非浮起的卡片。
1652
+ - 不得给触发器加回图标块,也不得把面板做成贴视口的整高侧板。
1597
1653
  - 不得把本组件放到 `ApplicationSecondaryNavigation` 之外的位置。
1598
1654
  - 不得由本组件承担路由跳转,`onSelect` 只是通知。
1599
1655
  - 不得用它切换应用、切换页面模式或切换业务视图。
@@ -1614,7 +1670,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1614
1670
  **组合约定。** `items` 是数据而非元素 —— 组件内部渲染 `SidebarRailButton` 并自行控制 `active` 与点击,调用方不得先构造好按钮元素再传入。`GlobalSidebarEntry.label` 在类型上可选,在规范上必填:规范禁止纯图标导航项,只给 `icon` 不给 `label` 能通过类型检查但不合规。`icon` 的登记尺寸是 20px,走 `Icon`。`separator` 为 true 时其余字段被忽略,但该条目的 `key` 仍必须在栏内唯一。`value` 与 `onValueChange` 成对使用。`footer` 被推到栏底,与条目之间不需要额外间隔元素;栏底的入口(如「设置」)直接放 `SidebarRailButton`(07 · C-15)。本组件自持内边距与右侧 1px 边线,宿主用 flex 把它与内容区并排即可(写法见 SKILL.md「五层 Canvas 模型 · 宿主布局」),不得再加外边距。
1615
1671
 
1616
1672
  **禁止 / 使用边界。**
1617
- - 不得把本组件当作应用外壳的全局左栏 —— Shell 是刻意设计的无侧栏、全宽四带堆叠。
1673
+ - 不得把本组件当作应用外壳的全局左栏 —— Shell 是刻意设计的无侧栏、全宽导航带堆叠。
1618
1674
  - 不得给本组件设置 `position: fixed` 或让它跨出 Content Canvas。
1619
1675
  - 禁止渲染只有图标而没有标签的条目。
1620
1676
  - 不得用它替代 `Sidebar` 承载带分组标题的多层导航。
@@ -1632,7 +1688,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1632
1688
  - 行内或表格单元中的状态标签:改用 `Badge`。
1633
1689
  - 承载业务内容而非数字的卡片:改用 `Card`。
1634
1690
 
1635
- **组合约定。** 本组件必须放进 `ApplicationPageLayoutContainer` 的 `metrics` 槽位,区域之间的间隙由该容器的 `--ui-section-gap` 负责;卡片之间的间隙由本组件的 `--ui-card-gap` 负责(Standard 12px / Condensed 10px / Compact 8px)。单张指标卡不得自带外边距。`trend` / `status` / `chart` / `primary-secondary` 四种语义的卡片必须作为 `children` 写在本组件内部,与 `metrics` 生成的基础卡共用同一个 grid,等高才能成立;把它们平级另起一行会破坏等高。每区 4–6 张,`columns` 缺省取卡片总数(`metrics` 条目数加 `children` 中的卡片数,条件渲染为 `null` / `false` 的不计入)、上限 6。`Metric.key` 应显式提供 —— `label` 是 ReactNode,用它作 React key 在传入 JSX 时无效。`Metric.icon` 走 `Icon`,提供后该卡语义从 `numeric` 变为 `icon`。指标数据在途或失败时用 `state` 表达,取值只有 `ready` / `loading` / `error` 三种:`loading` 由组件渲染与指标卡同壳同高的骨架(张数同 `columns` 的缺省算法,无卡片时为 4),调用方不得自拼骨架卡;`error` 渲染一张横跨整行的失败卡,内容经 `error` 传入,应说明失败原因并提供「重试」,不传时显示内置的「指标加载失败」。两种状态下 `metrics` 与 `children` 都不渲染;读屏经组件内置的状态播报获知「指标加载中」/「指标加载失败」。
1691
+ **组合约定。** 本组件必须放进 `ApplicationPageLayoutContainer` 的 `metrics` 槽位,区域之间的间隙由该容器的 `--ui-section-gap` 负责;卡片之间的间隙由本组件的 `--ui-card-gap` 负责(Standard 12px / Condensed 10px / Compact 8px)。单张指标卡不得自带外边距。`trend` / `status` / `chart` / `primary-secondary` 四种语义的卡片必须作为 `children` 写在本组件内部,与 `metrics` 生成的基础卡共用同一个 grid,等高才能成立;把它们平级另起一行会破坏等高。每区 4–6 张,`columns` 缺省取卡片总数(`metrics` 条目数加 `children` 中的卡片数,条件渲染为 `null` / `false` 的不计入)、上限 6。`Metric.key` 应显式提供 —— `label` 是 ReactNode,用它作 React key 在传入 JSX 时无效。`Metric.icon` 走 `Icon`,提供后该卡语义从 `numeric` 变为 `icon`。`Metric.description` 是数值下方一行 12/16 的口径说明(「2026 年 · 不含已冲红」),只写统计口径,不写趋势或操作提示;有设计稿时照稿给出,同一区内要么都写要么都不写,否则等高的卡片里文字基线不齐。指标壳不是卡片:无边框、无底色、无内边距,直接落在页面底色上,高 76px,数值 32/32 semibold。指标数据在途或失败时用 `state` 表达,取值只有 `ready` / `loading` / `error` 三种:`loading` 由组件渲染与指标卡同壳同高的骨架(张数同 `columns` 的缺省算法,无卡片时为 4),调用方不得自拼骨架卡;`error` 渲染一张横跨整行的失败卡,内容经 `error` 传入,应说明失败原因并提供「重试」,不传时显示内置的「指标加载失败」。两种状态下 `metrics` 与 `children` 都不渲染;读屏经组件内置的状态播报获知「指标加载中」/「指标加载失败」。
1636
1692
 
1637
1693
  **禁止 / 使用边界。**
1638
1694
  - 不得用 `state="loading"` 长期占位来顶替「无真实指标」—— 无指标时整个区域不渲染。
@@ -1640,7 +1696,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1640
1696
  - 不得给指标卡挂点击跳转,整卡默认只读,`cursor: default` 是已登记行为。
1641
1697
  - 不得一行超过 6 张,也不得让同一区内的卡片高度不一致。
1642
1698
  - 不得在指标区放置页面动作按钮、搜索框或筛选控件。
1643
- - 禁止给指标卡加阴影 —— 卡片壳是 16px 圆角 + 1px 边框,无阴影。
1699
+ - 禁止给指标卡加阴影、边框或白底 —— 指标直接落在页面底色上。
1644
1700
 
1645
1701
  ## ApplicationMetricTrend
1646
1702
 
@@ -1756,22 +1812,26 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1756
1812
 
1757
1813
  **用途。** Canvas 的上下文区,承载页面身份、数据新鲜度与页面级 Page Mode Switch。
1758
1814
 
1759
- **何时使用。** 每个业务页面的第一个区域必须是该组件。页面标题、面包屑、数据状态与刷新、页面级动作组、Page Mode Switch 全部集中在这里,且只有这里。该组件回答的是「这是哪个页面、数据是什么时候的、用哪种模式看」。
1815
+ **何时使用。** 每个业务页面的第一个区域必须是该组件。返回、页面标题、面包屑、数据状态与刷新、页面级动作组、Page Mode Switch 全部集中在这里,且只有这里。该组件回答的是「这是哪个页面、数据是什么时候的、用哪种模式看」。
1760
1816
 
1761
1817
  **何时改用其他组件。**
1762
1818
  - 跨页身份与应用、模块导航属于 Shell,改用 `TopNavigationPrimaryBar`、`ApplicationPrimaryNavigation`、`ApplicationSecondaryNavigation`。
1763
1819
  - 搜索、常用筛选、排序、呈现设置、SPLIT 右栏的 View Mode Switch 一律改用 `ApplicationQueryToolbar`。
1764
1820
  - 批量动作改用 `ListBatchActionBar`,它出现在结果集上方而非上下文区。
1765
1821
  - 记录对象的头部改用 `ApplicationRecordDetailBody` 的 `summary` 与 `ApplicationDetailDrawer` 的标题区。
1766
- - 面包屑本体用 `Breadcrumb`,经 `breadcrumb` 槽位传入。
1822
+ - 面包屑本体用 `Breadcrumb`,经 `breadcrumb` 槽位传入;单纯回到上一层(二级页面)不用面包屑,改传 `onBack`。
1767
1823
 
1768
1824
  **组合约定。**
1769
1825
  - `actions` 承载页面级动作组,元素应为 `SystemButton`,至多一个 primary。中文标签为 2–4 字裸名词短语:`新建`、`导入`、`导出`、`更多`。
1770
1826
  - Page Mode Switch 由 `pageModes`、`pageMode`、`onPageModeChange` 三者共同驱动,三者必须成组提供;只给 `pageModes` 会得到一个点不动的开关。它按 radiogroup 模式只占一个 Tab 停靠点,← / → 切换模式并首尾相接,Home / End 跳到首末项 —— 方向键同样触发 `onPageModeChange`。
1771
1827
  - `pageModes` 只列该页面真正开放的模式。少于 2 个时开关完全不渲染且不占位。
1772
- - `dataStatus` 为 `normal` 时应同时提供 `updatedAt`,否则状态区只剩一个刷新按钮,数据新鲜度无从判断。`updatedAt` 只登记 `HH:mm` 一种写法(24 小时制、两位补零,如 `09:12`),组件渲染为「更新于 09:12」;不得传日期、秒或「刚刚」「5 分钟前」一类相对时间(07 · C-12)。
1773
- - 三种数据状态各有各的措辞与可用性:`normal` 显示更新时刻,`refreshing` 显示刷新中且刷新按钮禁用,`failed` 显示刷新失败且按钮读作 `重试`。
1828
+ - 左侧按 GAP Design kit「数据更新」排布:可选的「返回」→ 标题 → 12px 竖线 → 更新时间。传 `onBack` 时标题前渲染「返回」幽灵按钮(16px chevron + 文字,32 高、圆角 12),文案经 `backLabel` 可改,组件不跳转、回到哪里由调用方决定;二级页面用它回到来源页。`onBack` 与 `breadcrumb` 不得同时传。
1829
+ - `dataStatus` 为 `normal` 时应同时提供 `updatedAt`,否则数据新鲜度无从判断。`updatedAt` 写完整日期时间 `YYYY-MM-DD HH:mm`(24 小时制、两位补零,如 `2026-07-28 10:00`),组件原样显示为 14/20 正文色,不加「更新于」前缀;不得传秒或「刚刚」「5 分钟前」一类相对时间。此条取代 07 · C-12 的「只写 HH:mm」(业财平台 round-01 按 kit 裁决)。
1830
+ - 传了 `onRefresh` 时,更新时间与其后的 16px 刷新字形合成一枚幽灵按钮,点它即刷新,可访问名为「刷新,2026-07-28 10:00」;没有刷新能力的页面(草稿、向导、一次性结果)不传,时间按纯文字显示,不出现刷新字形。
1831
+ - 三种数据状态各有各的措辞与可用性:`normal` 显示更新时间,`refreshing` 显示刷新中、字形转圈且按钮不可点,`failed` 显示刷新失败(危险色)且按钮读作 `重试`。
1774
1832
  - `title` 为字符串时才会得到悬浮提示。需要悬浮提示又需要补充信息时,标题主体传 `title`,补充信息走 `subtitle`。
1833
+ - 页面级进行中任务(批量识别、批量导入)的进度经 `taskStatus` 渲染为页头正中的胶囊,`label` 写「正在识别 14/100」,`busy` 为 true 时带转圈;任务结束后移除 `taskStatus`,结果写进 `Sonner` 或页面内容。进度不得写进 `subtitle`。
1834
+ - 外观是 48px 通栏:落在页面底色上、只有一条 0.5px 下边线,不是卡片;放在 `ApplicationPageLayoutContainer` 的 `header` 槽位时自动吃掉顶部与两侧留白。
1775
1835
  - 该组件自身不带外边距,与相邻区域的间距由 `ApplicationPageLayoutContainer` 的区域间隙负责。
1776
1836
  - Page Mode Switch 的选中态与 `ToggleGroup` 同为分段控件表达(选中项抬升为表面色),不得改为淡色洗 —— 淡色洗属于独立开关 `Toggle`。
1777
1837
 
@@ -1781,6 +1841,9 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1781
1841
  - 不得让刷新重置业务视图、搜索、筛选、排序或页面模式 —— 刷新只更新数据。
1782
1842
  - 不得在 `actions` 中放置行级动作或批量动作。
1783
1843
  - 禁止渲染只有一种取值的 Page Mode Switch,也不得为它保留空位。
1844
+ - 不得用 `taskStatus` 显示数据刷新状态、页面说明或筛选摘要 —— 三者各有 `dataStatus`、`subtitle` 与工具栏。
1845
+ - 禁止同时传 `onBack` 与 `breadcrumb`,也不得用 `actions` 里的按钮充当返回。
1846
+ - 不得给 `updatedAt` 拼上「更新于」等前缀 —— 组件按 kit 原样显示时间。
1784
1847
 
1785
1848
  ## ApplicationQueryToolbar
1786
1849
 
@@ -1790,7 +1853,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1790
1853
 
1791
1854
  **何时改用其他组件。**
1792
1855
  - Page Mode Switch 属于 `ApplicationPageHeader`,不得在此重建。
1793
- - 单个高频筛选维度的触发器改用 `ApplicationFilterMenu`,经 `commonFilters` 传入。
1856
+ - 单个高频筛选维度的触发器改用 `ApplicationFilterMenu`,日期区间维度改用 `ApplicationDateRangeFilter`,都经 `commonFilters` 传入。
1794
1857
  - 完整的筛选维度面板改用 `ApplicationFilterList`,装进 `Popover` 后经 `moreFilters` 传入;不得装进 `Collapsible` 就地展开(06 · D-4)。
1795
1858
  - 纯文本搜索输入已由该组件内置的 `SearchField` 承担,不得在工具栏内另置搜索控件。
1796
1859
  - 分页改用 `ListTablePagination`,它属于 `ApplicationDataDisplay` 的底部。
@@ -1801,23 +1864,28 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1801
1864
  - `businessViews` 传 2–4 个稳定工作视角,`businessView` 与 `onBusinessViewChange` 必须成对提供。
1802
1865
  - 搜索经 `searchValue` 与 `onSearchChange` 受控,提交只经 `onSearchSubmit`,由 Enter 触发。
1803
1866
  - 搜索框的可访问名优先取 `searchAriaLabel`,其次取 `searchPlaceholder`,二者至少给一个且必须写明搜索范围;占位文字写示例、可访问名写范围时分开传,同文时只传 `searchPlaceholder`。`searchPlaceholder` 没有默认值,缺省时占位文字取 `searchAriaLabel`;二者都缺省时可访问名回落为「搜索当前结果」并在开发构建下告警一次。
1804
- - `commonFilters` 常驻 2–3 个 `ApplicationFilterMenu`,其余维度一律收进 `moreFilters`;常用筛选里出现的维度不再进更多筛选(07 · C-11)。折叠只改变入口,不移除能力。
1867
+ - `commonFilters` 常驻 2–3 个 `ApplicationFilterMenu` 或 `ApplicationDateRangeFilter`,其余维度一律收进 `moreFilters`;常用筛选里出现的维度不再进更多筛选(07 · C-11)。折叠只改变入口,不移除能力。
1868
+ - 第二行左组的顺序固定为「结果摘要 → 搜索 → 排序 → 常用筛选 → 更多」,右组只放 `viewModeSwitch` 与呈现设置(GAP Design kit「数据筛选搜索」:排序在搜索后面、筛选前面;业财平台 round-01 裁决)。
1869
+ - 间隔按 kit「数据筛选搜索」:三行之间 8;第二行左组控件之间 4、右组之间 4、左右两组之间 12;摘要与搜索之间由组件画一条 1×20 的线条色竖线,只在传了 `resultSummary` 时出现。间隔与竖线都由组件给出,传入的排序与筛选控件不带外边距。
1805
1870
  - `sort` 传 `Select`(无可见标签,用 `aria-label` 命名)。DataTable 呈现下表头排序是第二入口:`Table` 的 `sort` 与这里的 `Select` 读写同一份排序状态,任一处改动另一处同步回显(07 · C-2)。
1806
- - 生效条件必须回写 `appliedTags`,并同时提供 `onRemoveTag` 与 `onResetTags`。`AppliedFilterTag.label` 为非字符串时必须提供 `labelText`,否则移除按钮的无障碍名称为空。
1807
- - `presentation` 决定呈现设置按钮的文案,必须与 `ApplicationDataDisplay` 的同名 prop 取自同一处状态。
1871
+ - `resultSummary` 渲染为一枚胶囊,数字用 `<strong>` 包裹即加粗为正文色,如 `<>共 <strong>46</strong> 张</>`;有勾选时紧随写已选数。
1872
+ - 生效条件必须回写 `appliedTags`,并同时提供 `onRemoveTag` 与 `onResetTags`;清除全部的按钮文案为「清空」,与筛选标签同款胶囊。`AppliedFilterTag.label` 为非字符串时必须提供 `labelText`,否则移除按钮的无障碍名称为空。
1873
+ - 呈现设置按钮按 kit 是 32×32 纯图标(16px `sliders-horizontal`,白底描边、圆角 12),名字落在可访问名与悬停提示上;`presentation` 决定这个名字,必须与 `ApplicationDataDisplay` 的同名 prop 取自同一处状态。
1808
1874
  - `hasPresentationSettings` 缺省时按是否提供 `onPresentationSettings` 推断:给了回调即渲染设置按钮,不给即不渲染且不占位;显式传入优先。无真实可配置项时不传回调即可,或显式传 `hasPresentationSettings={false}`。
1809
1875
  - `onPresentationSettings` 收到设置按钮的点击事件,`event.currentTarget` 即按钮元素,可作面板锚点或关闭后的焦点归还目标;不读参数的无参回调照旧可用。面板由调用方持有,其开合状态经 `presentationSettingsOpen` 回传,按钮据此输出 `aria-expanded` —— 二者应当成对提供,不传则按钮不报开合。
1810
1876
  - 呈现设置面板一律用 `Popover` 承载、锚定在呈现设置按钮上,与 `moreFilters` 同一承载;不得改用 `Sheet`、`Dialog` 或 `Drawer`(07 · C-7)。
1811
1877
  - 每种呈现方式各自独立存储其设置,切换呈现方式不得沿用上一种的设置。
1812
1878
  - `viewModeSwitch` 仅允许出现在服务 SPLIT 右栏的那一份工具栏上,且只改 `dataPresentation`。
1813
- - 搜索框宽 240–320px 弹性:行内有余量时长到 320px,筛选多时退回 240px,以容下写明搜索范围的占位文字。该组件自身不带外边距,与相邻区域的间距由 `ApplicationPageLayoutContainer` 负责。
1879
+ - 搜索框宽 240px,白底、1px 描边、圆角 12(GAP Design kit),占位文字写短的搜索范围;确需更宽时调用方覆盖 `--mh-query-toolbar-search-max-width`。放进 `ApplicationPageLayoutContainer` 时,该组件与数据展示区同处一张白卡(圆角 20、内边距 12),自身不再画卡片;单独使用时自身就是那张卡的上半。该组件不带外边距,与相邻区域的间距由 `ApplicationPageLayoutContainer` 负责。
1814
1880
  - 数据展示区的 `state` 为 `no-permission` 或 `not-found` 时不渲染本组件;处于 `error` 时保留,条件改动后重新查询(07 · C-6)。
1815
1881
 
1816
1882
  **禁止 / 使用边界。**
1817
1883
  - 禁止逐字实时搜索,不得在 `onSearchChange` 中直接发起查询。
1818
1884
  - 不得同时省略 `searchAriaLabel` 与 `searchPlaceholder`,也不得把任一写成不含范围的「搜索」。
1819
1885
  - 不得显式传 `hasPresentationSettings` 为 true 而不给 `onPresentationSettings` —— 那是一个点了没反应的按钮。
1820
- - 禁止出现通用的「视图设置」按钮 —— 按钮必须按当前呈现方式命名:`列设置` / `列表设置` / `卡片设置` / `看板设置` / `日历设置` / `图表设置` / `时间轴设置`。
1886
+ - 禁止出现通用的「视图设置」或「自定义」按钮 —— 按钮必须按当前呈现方式命名:`列设置` / `列表设置` / `卡片设置` / `看板设置` / `日历设置` / `图表设置` / `时间轴设置`。
1887
+ - 不得把排序挪回右组,也不得把它排在常用筛选之后。
1888
+ - 不得在摘要与搜索之间自行再画分隔线,也不得给传入的排序与筛选控件加外边距来改间隔。
1821
1889
  - 不得在该组件内渲染 Page Mode Switch,也不得用 `viewModeSwitch` 改动 `pageMode`。
1822
1890
  - 不得让筛选状态只存在于菜单或面板内部而不回写 `appliedTags`。
1823
1891
  - 禁止为同一个结果集放置两份工具栏,也不得把搜索、筛选、排序下沉进 `ApplicationDataDisplay`。表头排序不算下沉,但不得另持一份与工具栏 `sort` 分离的排序状态。
@@ -1935,8 +2003,9 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1935
2003
  **组合约定。**
1936
2004
  - `summary` 承载对象头:标题、状态徽标(应为 `Badge`)、关键标识。
1937
2005
  - `sections` 按数组顺序渲染。`DetailSection.title` 为非字符串时必须提供 `key`;契约同样为 `DetailField` 登记了 `key`,`label` 为非字符串时必须提供。
1938
- - 字段以 `dl` / `dt` / `dd` 输出为名值对,列数随可用宽度自适应,字段列最窄 240px —— 680px 抽屉里排两列,独立详情页全宽下排更多列,两个载体不需要各写一套。
1939
- - 分节级动作经 `DetailSection.action` 右对齐于标题行;对象级主动作属于载体,写在抽屉右下角的固定动作区。
2006
+ - 字段以 `dl` / `dt` / `dd` 输出为横排名值对:字段名 160px 宽、14/20 三级文字色,值 14/20 medium。列数随可用宽度自适应,字段列最窄 360px,两个载体不需要各写一套。主体内容落在白卡里,载体负责灰底;分节间距 16,分节标题带 2×14 强调色竖条。
2007
+ - 伴随主内容一起看的一个分节(处理记录、审批流转)经 `aside` 传入,主体变为两栏:左栏弹性、右栏 360px,间距 12;可用宽度不足 960px 时侧栏落到主栏下方。主要字段分节不得挪进 `aside`。
2008
+ - 分节级动作经 `DetailSection.action` 右对齐于标题行;对象级主动作属于载体:抽屉写在页头右侧的动作区,独立详情页写在 `ApplicationPageHeader` 的 `actions`。
1940
2009
  - 时间轴、附件列表等非名值对内容走 `DetailSection.content`,排在字段之后。
1941
2010
  - 该组件不带外边距也不自持滚动,留白与滚动一律由载体负责。
1942
2011
  - 允许存在抽屉专用变体的条件是:超过 3 个分节、超过 15 个字段、动作流程有实质差异、性能要求不同,四者任一成立。即便成立,该变体只保留核心内容。
@@ -1948,6 +2017,7 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1948
2017
  - 不得在分节顺序可变时省略 `key` —— 重排序会导致内部状态错位。
1949
2018
  - 禁止在该组件内部再嵌套一个 `ApplicationRecordDetailBody`。
1950
2019
  - 不得在该组件内承载搜索、筛选、排序或分页。
2020
+ - 不得向 `aside` 放对象级动作或第二组主要字段,侧栏只放一个伴随分节。
1951
2021
 
1952
2022
  ## ApplicationRecordList
1953
2023
 
@@ -1995,22 +2065,24 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
1995
2065
 
1996
2066
  **用途。** 业务对象新建与编辑的模态表单载体,拥有已登记的字段网格与提交 / 取消语义。
1997
2067
 
1998
- **何时使用。** 用户必须完成或放弃的表单任务一律用本组件。已登记宽度只有 `small` 720px 与 `large` 960px 两档,字段默认排布在两列网格上。提交中由 `submitting` 表达,提交级失败由 `error` 表达。该组件建立在共享 Overlay 基座上,因此自带 Esc 关闭、焦点陷阱、关闭后焦点恢复与背景滚动锁定。
2068
+ **何时使用。** 用户必须完成或放弃的表单任务一律用本组件。已登记宽度只有 `small` 720px、`large` 960px 与 `xlarge` 1280px 三档(1280 是 GAP Design kit 弹窗宽度区间 680–1280 的上限,业财平台 round-01 裁决),字段默认排布在两列网格上。`xlarge` 只给字段多、需要原件与表单左右并排的编辑场景。提交中由 `submitting` 表达,提交级失败由 `error` 表达。该组件建立在共享 Overlay 基座上,因此自带 Esc 关闭、焦点陷阱、关闭后焦点恢复与背景滚动锁定。
1999
2069
 
2000
2070
  **何时改用其他组件。**
2001
2071
  - 不含表单的聚焦任务(导入映射、确认预览)改用 Foundation `Dialog`。
2002
2072
  - 不可逆动作的确认改用 `AlertDialog` —— 它的遮罩点击不关闭,破坏性确认必须是显式选择。
2003
2073
  - 人员、组织、审核人、通知接收人的目录式选择改用 `PeoplePickerDialog`。
2004
2074
  - 只读的业务对象详情改用 `ApplicationDetailDrawer` 或独立详情页。
2005
- - 设置、帮助、附件预览这类辅助性面板改用 `Sheet`。
2006
- - 字段规模超出两档宽度可承载的范围时,改用独立编辑页承载。
2075
+ - 帮助、附件预览这类辅助性面板改用 `Sheet`;全局设置是二级导航里的设置模块。
2076
+ - 字段规模超出三档宽度可承载的范围时,改用独立编辑页承载。
2007
2077
 
2008
- **组合约定。** 字段一律以 `Field` 子元素传入 `children`,一个 `Field` 管辖一个控件。需要跨列的字段给 `Field` 传 `span="full"`,不得用内联 `style` 写 `gridColumn`;需要单列或三列时改 `columns`,不要用外部 CSS 重排网格。字段级错误交给 `Field` 的 `error`,并且控件自身的 `invalid` 需另行设置 —— 两者不联动。提交级失败传 `error`,内容应是 `<Alert tone="danger">`,由组件渲染在主体顶部、字段网格之前。主体与底部动作区包在一个 `<form>` 里,主按钮是提交按钮,字段内按 Enter 即提交并调用 `onSubmit`;浏览器自带校验已关闭,字段校验一律走 `Field`。`submitting` 为 true 时组件禁用主按钮并置忙态,同时屏蔽 Esc 与遮罩点击两条关闭路径,取消按钮仍可用;调用方仍须在自己的提交回调里防止重复请求。底部动作区由组件持有,取消在左、主操作在右,文案经 `submitText` / `cancelText` 覆盖。`onCancel` 同时被取消按钮、Esc 与遮罩点击触发(提交中只剩取消按钮),因此它必须是幂等的。视口边距由 Overlay 基座负责,调用方不得再包一层定位容器。
2078
+ **组合约定。** 字段一律以 `Field` 子元素传入 `children`,一个 `Field` 管辖一个控件。需要跨列的字段给 `Field` 传 `span="full"`,不得用内联 `style` 写 `gridColumn`;需要单列或三列时改 `columns`,不要用外部 CSS 重排网格。字段级错误交给 `Field` 的 `error`,并且控件自身的 `invalid` 需另行设置 —— 两者不联动。提交级失败传 `error`,内容应是 `<Alert tone="danger">`,由组件渲染在主体顶部、字段网格之前。主体与底部动作区包在一个 `<form>` 里,主按钮是提交按钮,字段内按 Enter 即提交并调用 `onSubmit`;浏览器自带校验已关闭,字段校验一律走 `Field`。`submitting` 为 true 时组件禁用主按钮并置忙态,同时屏蔽 Esc 与遮罩点击两条关闭路径,取消按钮仍可用;调用方仍须在自己的提交回调里防止重复请求。底部动作区由组件持有,取消在左、主操作在右,文案经 `submitText` / `cancelText` 覆盖;逐条编辑这类需要「上一张」「下一张」的场景经 `secondaryActions` 传入 `SystemButton`(`intent="secondary"`),排在取消与提交之间;与本次提交相关的上下文(「共 100 条,当前第 6 条」)经 `footerNote` 渲染在动作区左侧。页头右侧恒有纯图标的关闭按钮,行为等同取消,提交中禁用。外观按 GAP Design kit「抽屉弹窗 / 弹窗」:面板圆角 20;48px 灰底页头,标题与关闭键间隔 10;主体灰底内含一张白卡承载字段网格,字段间距 10;底部动作区同为灰底,内边距 12、动作间隔 4、顶部 0.5px 分隔线。`onCancel` 同时被取消按钮、Esc 与遮罩点击触发(提交中只剩取消按钮),因此它必须是幂等的。视口边距由 Overlay 基座负责,调用方不得再包一层定位容器。
2009
2079
 
2010
2080
  **禁止 / 使用边界。**
2011
2081
  - 不得把提交失败呈现为 `Sonner` —— 用户必须处理的失败绝不能放进转瞬即逝的提示里。
2012
2082
  - 不得在 `children` 里自行渲染提交与取消按钮,底部动作区由组件持有。
2013
- - 禁止把宽度改到 720px / 960px 两档之外,也禁止让对话框超出有效视口。
2083
+ - 不得经 `secondaryActions` 放第二个 primary 或删除类动作,也不得把校验错误写进 `footerNote`。
2084
+ - 禁止把宽度改到 720px / 960px / 1280px 三档之外,也禁止让对话框超出有效视口。
2085
+ - 不得用 `className` 把面板圆角改回 16 或其他值 —— 四个模态弹窗同取 `--application-radius-dialog`。
2014
2086
  - 不得用本组件承载只读详情,详情有它自己的两个载体。
2015
2087
  - 不得在 `children` 内用内联 style 改写控件自身的边框、高度或圆角。
2016
2088
 
@@ -2018,32 +2090,34 @@ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`
2018
2090
 
2019
2091
  **用途。** DETAIL 的抽屉载体 —— 打开一条业务记录的详情,同时保持身后的列表上下文可见。
2020
2092
 
2021
- **何时使用。** 从列表打开单条记录且不希望丢失来源上下文时,该页面必须用本组件。推荐宽度 680px,底部动作区固定不随内容滚动。它与独立详情页共用同一个 `ApplicationRecordDetailBody`,是「一份详情,两个载体」中的抽屉那一个。
2093
+ **何时使用。** 从列表打开单条记录且不希望丢失来源上下文时,该页面必须用本组件。推荐宽度 680px,动作在页头右侧、没有底部动作区。它与独立详情页共用同一个 `ApplicationRecordDetailBody`,是「一份详情,两个载体」中的抽屉那一个。
2022
2094
 
2023
2095
  **何时改用其他组件。**
2024
2096
  - 非业务记录的侧边面板、或不需要已登记详情结构的裸抽屉,改用 Foundation `Drawer`。
2025
- - 设置、帮助、附件预览这类辅助性内容改用 `Sheet` —— 业务对象详情不属于那里。
2097
+ - 帮助、附件预览这类辅助性内容改用 `Sheet` —— 业务对象详情不属于那里;全局设置是二级导航里的设置模块,也不进抽屉。
2026
2098
  - 需要深链接的详情改用独立详情页,深链接永远只指向独立详情页。
2027
2099
  - 分节超过 3 个、字段超过 15 个、动作流程有实质差异或性能要求不同时,改用独立详情页承载完整内容;抽屉侧只保留核心内容。
2028
2100
  - 编辑与新建改用 `ApplicationFormDialog`;不可逆动作的确认改用 `AlertDialog`。
2029
2101
 
2030
- **组合约定。** `children` 必须传 `ApplicationRecordDetailBody`,不得为抽屉另写一份详情主体。`width` 默认 680px;`--application-drawer-width` 的 1280px 是宽 / 全屏变体,需要时经 `width` 显式传入。`side` 默认 `right`;来源在页面右侧(SPLIT 右栏的条目、月格的周末日格)时传 `left`,不得让抽屉盖住刚打开它的那一处。`primaryAction` 是唯一的主对象动作,固定在右下角,其余一律进 `secondaryActions`。关闭按钮由组件渲染并写作「关闭」,独立详情页写「返回」—— 这是结构区分,不是文案偏好。`onClose` 里调用方必须还原来源页面的八项上下文:业务视图、搜索、筛选、排序、分页、页面模式、当前对象、滚动位置,少还原任何一项都算缺陷。与列表配合时,来源侧用 `ApplicationRecordList` 的 `activeId` 或 `Table` 的 `onRowClick` 标记当前对象。视口边距、Esc、焦点陷阱、焦点恢复与滚动锁定由 Overlay 基座负责,调用方不得再实现一遍。
2102
+ **组合约定。** `children` 必须传 `ApplicationRecordDetailBody`,不得为抽屉另写一份详情主体。`width` 默认 680px;`--application-drawer-width` 的 1280px 是宽 / 全屏变体,需要时经 `width` 显式传入。`side` 默认 `right`;来源在页面右侧(SPLIT 右栏的条目、月格的周末日格)时传 `left`,不得让抽屉盖住刚打开它的那一处。`status` 紧邻抽屉标题,只在**抽屉标题就是对象名**时使用;抽屉标题是页面类型名(「进项发票详情」)、对象名写在 `ApplicationRecordDetailBody` 的 `summary` 里时,状态徽标随对象名放进 `summary`,不传 `status` —— 状态描述的是对象,必须紧邻对象名。抽屉为灰底、无投影,标题与副标题同行、均为 14/20。页头按 GAP Design kit「抽屉 / 常规」:右侧依次为 `primaryAction`、`secondaryActions` 与 32×32 纯图标关闭键,间隔 4,没有底部动作区(业财平台 round-01 裁决)。`primaryAction` 是唯一的主对象动作,其余一律进 `secondaryActions`,超过两三个时收进「更多」。关闭键由组件渲染,可访问名为「关闭」;独立详情页的退出是写着「返回」的按钮(`ApplicationPageHeader` 的 `onBack`)—— 这是结构区分,不是文案偏好。`onClose` 里调用方必须还原来源页面的八项上下文:业务视图、搜索、筛选、排序、分页、页面模式、当前对象、滚动位置,少还原任何一项都算缺陷。与列表配合时,来源侧用 `ApplicationRecordList` 的 `activeId` 或 `Table` 的 `onRowClick` 标记当前对象。视口边距、Esc、焦点陷阱、焦点恢复与滚动锁定由 Overlay 基座负责,调用方不得再实现一遍。
2031
2103
 
2032
2104
  **禁止 / 使用边界。**
2033
2105
  - 不得让深链接指向抽屉 —— 深链接只指向独立详情页。
2034
2106
  - 不得为抽屉与独立详情页各写一份详情主体。
2035
2107
  - 不得在 `onClose` 里做导航跳转 —— 抽屉是叠加层,关闭必须回到来源页面的原状态。
2036
- - 禁止把关闭按钮的文案写成「返回」,也禁止再加第二个退出入口。
2108
+ - 禁止把关闭键的可访问名写成「返回」,也禁止再加第二个退出入口。
2109
+ - 不得在抽屉底部另拼一条动作区 —— 动作一律在页头右侧。
2037
2110
  - 不得渲染第二个 `primaryAction`,主对象动作唯一。
2111
+ - 不得在抽屉标题是页面类型名时把对象状态传进 `status`,状态必须紧邻对象名。
2038
2112
 
2039
2113
  ## ApplicationGlobalActionPanel
2040
2114
 
2041
- **用途。** 消息、待办、运行总览、风险预警这四个 popover 型全局动作共享的同一个面板。
2115
+ **用途。** 消息、待办、总览、风险预警这四个 popover 型全局动作共享的同一个面板。
2042
2116
 
2043
2117
  **何时使用。** 该面板由 `ApplicationPrimaryNavigation` 的右侧动作簇触发,`onAction` 回调的 `kind` 为 `'popover'` 时打开本组件。四个动作复用同一个实例,切换的只是 `title`、`tabs` 与 `children`。它不是模态:背景仍可交互,因此不锁滚动、不陷阱焦点;但打开时焦点移入面板的首个可聚焦元素,Esc 关闭由本组件承担,并与库内其他浮层共用同一个 Esc 层级栈(上层浮层先响应),关闭后焦点归还给打开它的全局动作按钮。由于不陷阱焦点,面板在 DOM 中的挂载位置决定从它 Tab 出去之后的顺序,建议紧跟触发它的全局动作挂载。
2044
2118
 
2045
2119
  **何时改用其他组件。**
2046
- - 设置改用 `Drawer` 或 `Sheet` —— `onAction` 对它给出的 `kind` 是 `'drawer'`,它不走本面板。
2120
+ - 设置改用 `ApplicationSecondaryNavigation` 的设置模块 —— `onAction` 对它给出的 `kind` 是 `'module'`,它不走本面板。
2047
2121
  - 页面内的锚定浮层(常用筛选、更多筛选、呈现设置)改用 `Popover`,那是 Canvas 的事。
2048
2122
  - 必须完成或放弃的聚焦任务改用 `Dialog` 或 `ApplicationFormDialog`。
2049
2123
  - 业务页面内容一律留在 Canvas,不进入 Shell 层的任何浮层。