# 设计与交互基线

除非产品需求、页面原型或组件自身能力明确要求不同，否则页面必须遵循本基线。优先使用 Persagy Vant 已提供的能力；组件不支持时，只能在页面层实现，不得复制或改造组件内部实现。页面层级、面板深度和组件变量均以目标组件 README 与 demo 为准。

## 页面结构与导航

- 应用外页面层级不超过 `5` 级；动态面板嵌套不超过 `2` 层。复杂且相对独立的功能使用独立页面；需要即时录入、查看或回显当前页面数据的轻量任务使用动态面板。
- 所有触发的动态面板严格执行 `dynamic-panel-policy.md`：阅读/详情/确认用 `content-panel`，表单用 `form-panel`，扁平单选/多选用 `radio-panel` / `checkbox-panel`，树形选择用 `tree-select-panel`，上下文动作或专用面板不能承接的混合任务用 `action-sheet` 已有变体。不得用 `popup` 等通用容器替代；不得擅自修改面板样式。通用页面布局建议不覆盖面板既有视觉。
- 有动态面板可触发时，页面触发器优先使用 `cell` 的【单元格】右图标样式：设置 `right-icon="arrow"` 并使用 `click` 事件打开面板；需要展示当前选择结果时使用 `value` 或 `note`。不得手写同类行入口或箭头图标。
- 普通下钻页面进入和返回使用左右转场；从左上角关闭的页面优先使用上下转场；展开与收起提供缓动效果。优先复用组件内置动效。
- 带返回箭头的页面支持从左侧边缘左滑返回；仅在宿主框架支持时启用，不得以页面 CSS 模拟系统手势。

## 布局与视觉

- 页面含白色卡片时，优先使用 `background` 组件承载页面内容：一级页面（首页）使用 `theme="default"`，其他层级页面使用 `theme="gray"`。无白色卡片且无明确背景设计时，使用 `--van-gray-1`。
- 信息展示和录入控件以白色卡片承载；背景主题与页面层级不一致时，以明确的页面原型为准。
- 卡片内容与页面左右边缘保持 `16px` 间距；卡片之间间距 `8px`。
- 页面含白色卡片时，在滚动内容的最后一张卡片之后必须保留**唯一且恰好 `24px` 高**的页面级空白容器，避免卡片视觉贴近页面底部；该容器不承载业务内容、不计入卡片间距，也不使用自定义组件实现。滚动到末尾时，该 `24px` 即为滚动内容的终点；不得再叠加 `padding-bottom`、安全区占位、空白节点或额外卡片间距，避免出现超过 `24px` 的可滚动空白。存在固定底部操作栏时，空白容器仍位于可滚动内容末尾、操作栏之前；操作栏自身的安全区只作用于操作栏，不得计入或叠加到滚动内容末尾。
- 模块之间、控件之间使用 `8px` 或 `12px` 间距；仅左右排布的两组字段，纵向间距不得小于 `8px`。
- 白色卡片内容中存在两个及以上语义独立的信息模块时，每个模块必须以二次卡片封装：普通、中性模块使用 `--van-gradient-gray`，当前重点、选中或待处理模块使用 `--van-gradient-blue`。优先通过组件公开 `background` 能力或 `gradient-gray` / `gradient-blue` 公共工具类实现；不得自行调整渐变、圆角、边框或组件样式。单字段、同一模块内连续字段，以及已由 `info-card`、`work-order-card` 等提供层级的内容不重复封装。
- 白色卡片内有分割线的控件列表，最后一个可见控件必须隐藏末尾分割线；使用组件公开能力实现，例如 `cell`/`field` 设置 `border="false"`、`material-display-bar` 设置 `divider="false"`。根据条件渲染或 `visible` 判定最后一个实际可见项，不使用 CSS 强行隐藏分割线。
- 需要展示字段名称与回显值时，优先使用 `label`，不要手写同类标签和值的排版；左侧标签文本尽量自带冒号，保证名称和值之间的统一阅读间距。录入或选择入口仍使用 `field`、`cell` 等对应组件。多字段成组或存在多种字段展示类型（文字、强调文字、链接、标签、图片/视频或纵向字段）时，优先使用 `info-card` + `label`；按字段内容选择 `label` 的公开展示类型和纵向布局。字段无数据时整项隐藏，使用 `info-card` 时通过字段的 `visible: false` 实现。
- 触发器没有内置按压态时，叠加 `5%` 黑色透明遮罩作为按压反馈；有内置按压态的组件不重复添加。
- 字体跟随设备系统字体。常规层级使用：一级标题 `16px` 加粗、二级标题与正文 `14px`、补充说明 `12px`、底部菜单最小 `10px`；有明确业务需要时可调整。
- 页面标题层级统一使用组件：一级标题使用 `blue-mark-header`（【小蓝标】标题栏），放在白色卡片外层，与卡片内容左对齐；二级标题使用 `title-bar` 默认样式，放在白色卡片内。不得以普通文本、手写竖标或灰底加粗文本替代这两级标题。
- 一级标题需要必填标识、右侧操作或展开收起时，使用 `blue-mark-header` 的公开 `required`、`action-text`、`expandable`/`v-model` 能力；二级标题需要备注、图标、箭头或展开收起时，使用 `title-bar` 的默认规格及公开 Props。长文本允许换行或省略，换行时顶部对齐。
- 即时反馈控件（如开关、单选、多选、滚轮、滑块）可不额外设置按压态；所有其他可点击文本和自定义触发器必须提供按压态。
- 触控热区最小为 `24 × 24px`；视觉元素不足时用透明容器扩大热区，并在受限空间内尽量增大可点范围。

## 输入、上传与时间

- 识别到需要实际录入文本的字段时，统一使用 `field` 的【输入框】换行文本域样式：`type="textarea"` + `label-position="top"`，在白色表单卡片内展示标签与左对齐的输入内容；不要使用普通单行输入框或自绘文本域。按内容高度使用公开 `rows`、`autosize` 能力。
- 换行文本域最大输入 `200` 字，使用 `maxlength="200"` 和 `show-word-limit`，并在输入阶段限制或阻止超出内容。
- 识别到图片、视频、文件等上传内容时，统一使用 `uploader` 的【文件上传】表单示例样式：在白色表单卡片内以字段标签配合上传与预览区域呈现，不手写上传入口、预览网格或文件列表。按内容设置 `accept`，图片/视频可使用 `multiple`；样式沿用表单示例的 `preview-size="70"`，需要展示文件时仍使用同一表单布局。
- 图片/视频上传最多 `9` 个；表单示例的布局可复用，但 `max-count` 必须按全局限制设为 `9`，不能沿用 demo 的 `4`。已达上限再次触发上传时，通过 `click-upload` 等公开事件提示“最多支持上传9个”。
- 时间选择器默认定位到当前时间；需要时间节点时精确到秒。
- 涉及多个字段的编辑时，使用 `form` 承载于表单面板中完成；不得将同一编辑任务拆散到多个零散入口。
- 选项不超过 `3` 个且文案短时可外露单选；其他单选使用单选面板。多选枚举选项超过 `6` 个时，优先选用组件库提供的底部多选快捷操作能力。
- 必填或流程起点的输入框、搜索框可在进入页面时自动聚焦并唤起键盘；键盘主操作键应能直接触发后续搜索或保存。连续输入框支持键盘切换至下一项。

## 全局操作

- 作用于当前页面或当前数据集的操作统一集成到 `bottom-action-bar`。
- 根据操作数量选择组件文档中对应的操作栏变量、布局或溢出方案；先阅读 `bottom-action-bar` 的 README 和 demo，不得臆造变量或布局规则。
- 局部内容操作仍放置在其所属内容附近，不强行放入底部操作栏。

## 搜索、列表与加载

- 识别到搜索功能时，统一使用 `search` 的【搜索】纯净样式：设置 `variant="pure"`，不手写搜索输入区域或外层背景。使用既有 `v-model` 和 `search` 事件连接原有筛选逻辑；非业务必需时使用 `show-action` 和 `cancel` 事件提供取消操作。
- 点击搜索入口后自动聚焦并唤起键盘；非业务必需时，在搜索态提供取消操作。键盘唤起后内容区不保留无关内容。
- 列表使用 `pull-refresh` 处理下拉刷新，使用 `list` 处理滚动加载；无更多数据时展示明确的结束提示。
- 整个页面首次进入时，先以纯色页面背景叠加 `loading` 的 `type="illustration"` 作为过渡；数据就绪后再展示正常页面内容。局部请求或后续请求超过 `500ms` 时，使用 `loading` 或 `skeleton` 等相应加载反馈，不以页面级插画加载替代局部反馈。

## 页面状态与信息反馈

- 页面初始化展示插画加载状态；加载完成无数据时展示空状态页面。
- 操作成功或失败均提供全局反馈；重要或高风险信息使用 `dialog`、`notice-bar` 等强提醒样式。
- 所有不可用操作都必须可被点击或聚焦后说明具体不可用原因，提示文案为“`<具体原因>`”，不得只展示禁用态而无解释。
- 友好提示仅展示一次，点击空白区域后消失。
- 折叠/展开内容默认展开第一组数据；详情字段组优先使用 `info-card`，其他卡片内容使用 `collapse-toggle` 或 `blue-mark-header` 的公开展开能力。
- 保存筛选条件后，筛选对应数据并提示“保存成功”；筛选图标右上角显示徽标标记。
- 重要文本优先完整换行；采用省略时，提供下钻、展开、气泡或全局提示等方式查看完整内容。长度不稳定的内容可在最大高度后提供“展开”入口。

## 提交校验

- 底部主操作触发时先执行必填校验：存在未填必填项时提示“必填项未填写”。
- 名称或其他定义为唯一的内容重复时提示“内容已重复”。
- 提交成功时提示“提交成功”，并防止重复提交直至请求完成。

## 交付前自查

```md
## 规范落实项
- 布局与文本：<背景、卡片间距、末卡片后 24px 留白、文本溢出和空字段处理方式>
- 页面结构与触达：<页面/面板层级、导航动效、热区、信息层级；不涉及则说明>
- 输入与选择：<200 字限制、9 个上传限制、时间、键盘、单选/多选策略；不涉及则说明>
- 编辑与全局操作：<表单面板、底部操作栏及其变量/布局选择；不涉及则说明>
- 页面状态：<500ms 加载策略、空状态、禁用原因、展开默认值>
- 操作反馈：<保存筛选、提交校验和成功提示；不涉及则说明>
```