# 组件变体与模拟器示例选型

组件选型不止确定“使用哪个组件”，还必须确定“使用该组件的哪个模拟器示例、哪些公开 Props/插槽/变量”。目标是用最贴近页面现状与产品意图的原生示例完成界面，避免把所有场景都退化为基础样式或用自定义 CSS 模拟示例变体。

## 必经流程

对每个可见或可交互 UI 单元执行以下流程：

1. **识别页面意图**：记录该单元是信息展示、进入下一层、单选/多选、状态回显、带头像的人员/对象、带标签的分类、紧凑操作入口，还是其他明确目的；同时识别已有页面的内容层级、行数、左右信息、选中态和分组关系。
2. **浏览完整示例集**：读取目标组件 README 的所有“代码演示”标题，并查看对应 demo。模拟器展示的变体、变量和样式示例均是候选方案；不得只查看基础用法后立即实现。
3. **比较候选变体**：从同一组件中至少比较语义接近的示例；按“业务语义优先、信息层级其次、现有视觉结构再次、最少公开扩展最后”的顺序选择。不得为了视觉相似而选择错误的交互语义，例如把可多选项实现成单击跳转项。
4. **使用公开能力落地**：先原样复用所选示例的 Props、事件、插槽和预置样式。未经产品经理明确提出具体样式调整，不得修改 Less/CSS 变量或组件视觉；不要复刻模拟器 DOM、私有 class 或自行拼出近似控件。
5. **记录决策**：每种实际使用的组件变体都写入交付中的“组件变体选型”，使产品经理能从组件官网/模拟器复查效果。

## 选择准则

- 有交互含义的变量优先于纯视觉变量：例如选择状态、导航箭头、输入/回显、禁用与加载必须与业务行为一致。
- 信息密度与行数必须匹配：单行信息不用三行样式；标题、编号、位置等稳定三层信息才用三行样式。
- 内容归属决定元素位置：影响当前项选择的控件使用前置/后置选择；对象身份使用头像；分类或状态集合使用标签组；辅助说明用 `label`、`note` 或 `description`，不要滥用标题插槽。
- 页面层级优先通过已有容器变体表达：例如卡片内容、分组标题、灰色承载区、圆角卡片，先检查容器组件的示例和变量，再考虑页面级布局。
- 多个示例都可用时，选择无需改动组件视觉、公开能力最少且后续维护最清晰的一种；在清单中说明取舍。

## 输入框与文件上传的示例匹配

| 页面意图 | 优先模拟器示例 | 典型公开能力 | 不适用时机 |
| --- | --- | --- | --- |
| 标题仅说明其下一块自由文本录入（执行反馈、处理说明、备注） | 【输入框】「换行文本域」 | 原标题作为 `label`，`v-model`、`type="textarea"`、`label-position="top"`、`input-align="left"`、`rows`/`autosize`、`maxlength="200"`、`show-word-limit`；按原规则传入 `required`、`rules`、`readonly` 或 `disabled` | 标题是独立信息分组，或字段只是只读回显时 |
| 图片与视频采集、回显或补充材料 | 【文件上传】「图片/视频表单」 | 原标题作为 `label`，原列表作为 `v-model`，`accept="image/*,video/*"`、`multiple`、`max-count="9"`、`preview-size="70"`；必填使用 `required`，保留 `after-read`、删除与 `click-preview` 事件 | 仅上传非媒体文件，或场景没有上传行为时 |

当“执行反馈”标题只描述其下方的输入区域时，标题必须合并进 `field` 的 `label`，而不是同时使用标题栏、普通文本和自绘文本框。文本域保持左对齐、使用组件内置字数统计和原校验数据；不得因视觉对齐覆盖组件样式。

当“照片/视频”标题只描述其下方上传区域时，标题必须合并进 `uploader` 的 `label`，使用「图片/视频表单」的既有卡片、上传和预览布局。视频通过 `accept="image/*,video/*"` 和既有预览事件处理；不得另绘拍照/上传入口、缩略图或必填星号。

## 动态面板的示例匹配

所有面板及二级触发严格执行 `dynamic-panel-policy.md`。以下仅作语义匹配提示；必须查看对应组件的完整 README/demo，选择已有样式变体与变量组合，不得擅改面板 CSS/Less 或通过主题覆盖修改视觉。

| 页面意图 | 优先模拟器示例 | 典型公开能力 | 不适用时机 |
| --- | --- | --- | --- |
| 内容阅读、详情或阅读后确认 | 【内容面板】 | `content-panel` 的公开内容与确认能力 | 实际任务为编辑或选择时 |
| 字段录入、校验与提交 | 【表单面板】 | `form-panel` 的公开表单与提交能力 | 仅展示或选择时 |
| 树形/层级选项单选或多选 | 【树选择面板】 | `tree-select-panel` 已有单/多选、搜索、级联与加载组合 | 选项实际是扁平枚举时 |
| 扁平选项只需要单选 | 【单选面板】 | `radio-panel` 的原选中值与 `select` 事件 | 树形数据，或同时存在非同构字段、复杂条目或批量操作时 |
| 扁平选项只需要复选 | 【多选面板】 | `checkbox-panel` 的原选中数组与 `confirm` 事件 | 树形数据，或同时存在非同构字段、复杂条目或批量操作时 |
| 当前上下文下的复杂选择、筛选或批量处理面板；内部同时有标题、关闭、多个非同构条目和确认操作 | 【动作面板】「自定义面板」 | `v-model:show`、`title`、`closeable`、`close-on-click-overlay`、`lock-scroll` 与默认插槽；在示例既有白色卡片内容区组合已有组件 | 仅阅读/确认、标准表单、纯单选或纯多选可完整由 `content-panel`、`form-panel`、`radio-panel`、`checkbox-panel` 承接时 |

自定义面板的默认插槽用于组合【标题栏】、【单元格】、【字段展示】、单选/多选和既有操作组件；例如空间选择可保留原选中数组、可选数量、位置字段、标签、全选与下一步事件。保持该模拟器已有的灰色面板背景、标题区与白色卡片内容结构，不复制其 DOM 或覆盖动作面板样式；不得改用 `popup` 或手写遮罩、弹层和固定底栏。

## 信息卡片的插槽组合

当一张任务/作业摘要卡中的主标题、状态、设备或位置、详情字段和标签都属于同一业务对象时，选择【信息卡片】承载整张卡，而非将它拆成普通白色容器、文本和标签。

- 优先用 `title`、`fields`、`extra-fields` 承接能直接映射的标题与字段；字段数组通过 `visible` 保持原空值隐藏规则。
- 需要在主字段之后补充组合内容时，选择模拟器示例「下方插槽样式」的 `#default` 插槽：字段回显插入【字段展示】`label`，任务标题加多标签、右侧状态和下钻入口插入【单元格】「换行标签栏」。
- 标签必须继续使用 `wrap-tags` 与 `show-wrap-tags`，右侧状态继续使用 `value`；只有原卡片存在跳转或触发行为时才使用 `right-icon="arrow"` 和原 `click`。
- 该插槽仅用于组合现有组件。不得在插槽内手写白色卡片、标签流、字段排版或覆盖信息卡片、字段展示、单元格的样式。

## 单元格的示例匹配

【单元格】的模拟器拥有大量变体。按下列业务意图选用对应 README 示例，而不是固定使用基础单元格：

| 页面意图 | 优先模拟器示例 | 典型公开能力 | 不适用时机 |
| --- | --- | --- | --- |
| 普通标题与回显值 | 基础用法 | `title`、`value`、`label` | 有明确选择状态或三层稳定信息时 |
| 点击进入详情、选择面板或下一层 | 展示箭头 / 扩展元素「右图标」 | `is-link` 或 `right-icon="arrow"`、`click`、`value`/`note` | 仅展示不可操作信息时 |
| 多选、单选列表项 | 扩展元素「前置选择」或「后置选择」 | `left-select` / `right-select`，并连接真实选择状态 | 点击仅为路由跳转或字段录入时 |
| 单选对象/空间列表：左侧单选圆点、名称与一条位置/说明 | 单选单元格-双行样式 | `v-model:left-select`、`select-type="radio"`、`show-left-select`、`title`、`label`；位置有图标时使用 `show-label-icon`、`label-icon="location-o"` | 实际需要复选、稳定三层文本或跳转入口时 |
| 人员、设备等有识别图片的对象 | 扩展元素「头像」 | `avatar` 或 `right-avatar` | 图片不承担对象识别、仅为装饰时 |
| 强调关键条目或分组内重点字段 | 标题加粗 / 前置小蓝标 | `title-bold` / `blue-mark` | 普通内容项；不能替代页面一级标题组件 |
| 标题旁呈现多个分类/状态 | 扩展元素「标签组」 | `tags` | 单一状态可用右侧值或状态组件时 |
| 任务/检查项的单行标题，下方标签可换行，右侧有状态和下钻箭头 | 扩展元素「换行标签栏」+「右图标」 | `title`、`wrap-tags`、`show-wrap-tags`、`value`、`right-icon="arrow"`、`click`；标题仅在原页面强调时使用 `title-bold` | 标签属于详情字段时应使用 `label type="tag"`；仅有稳定三层纯文本信息时使用三行样式 |
| 分组标题 + 多条同级说明、动作项、执行要求或检查内容 | 多行备注 | `title`、原说明数组 `multi-line-notes`、`show-multi-line-notes`；一个分组对应一个单元格 | 将多条说明拼成一个长段落或手写列表；无交互却增加箭头/折叠 |
| 标题 + 一条辅助信息 | 双行图标单元格 / 基础用法带 `label` | `label`、`icon`/`right-icon`、`center` | 需要固定三层业务信息时 |
| 标题、编号/位置、描述三层信息 | 三行样式 | `three-line`、`title`、`label`、`description`、可选 `value`/`right-icon` | 内容只有一到两层时 |
| 辅助信息在右侧且可独立操作 | 加粗与可点击备注 | `note`、`note-bold`、`note-clickable`、`click-note` | 整行都应作为唯一触发器时 |
| 成组的列表或录入入口 | 分组标题 / 卡片风格 | `cell-group` 的 `title`、`inset`、`gray-card` | 页面规范要求使用【背景】或其他业务卡片承载时，优先服从该规范 |

“前置选择”与“后置选择”由选择动作的视觉归属决定：选择控件与标题同属一项、需要先看到状态时使用前置；文本信息为主、选择控件作为结果或批量操作时使用后置。若现有页面无法明确判断，先保留原有交互位置并在选型记录中说明。

空间、对象等单选列表在“左侧圆点 + 名称 + 一条位置/说明”的结构下，固定使用【单元格】「单选单元格-双行样式」：将原单选状态绑定为 `v-model:left-select`，设置 `select-type="radio"` 与 `show-left-select`，名称传入 `title`，位置或说明传入 `label`；位置有图标时使用 `show-label-icon` 和 `label-icon="location-o"`。保留原点击、禁用、最多可选数量与提交逻辑；不得手写 radio、列表行或位置图标。

任务/检查项中的 EHS、要求拍照等标签属于该任务行的附属状态，应作为 `wrap-tags` 原数组传入，允许组件按宽度自然换行；右侧“待完成”等状态使用 `value`，下钻使用 `right-icon="arrow"` 和既有 `click`。不要将标题、标签、状态和箭头拆为手写 flex 行，也不要因标签换行改用三行样式。

“动作项 / 执行顺序 / 执行要求 / 检查内容”这类分组说明，每一个分组使用一个【单元格】的「多行备注」能力：分组名放入 `title`，每条原始说明分别放入 `multi-line-notes`，并开启 `show-multi-line-notes`。仅当原页面已有展开收起交互，才增加 `show-title-collapse-icon`、`default-multi-line-notes-collapsed` 和对应状态事件；静态展示不增加交互。位于同一卡片的一组单元格沿用组件分隔线，最后一个实际单元格设为 `border=false`。

## 交付格式

在“组件复用清单”后增加以下内容；同一变体可合并为一项，不必按每一行重复：

```md
## 组件变体选型
- [单元格](https://meri-mobile.netlify.app/#/zh-CN/cell)：模拟器示例「后置选择」；用于工单批量选择，使用 `right-select` 绑定原有选中状态。未采用「展示箭头」，因为该行不是跳转入口。
- [单元格](https://meri-mobile.netlify.app/#/zh-CN/cell)：模拟器示例「三行样式」；用于设备条目，使用 `three-line`、`title`、`label`、`description` 和 `right-icon="arrow"` 呈现名称、编号、位置与详情入口。
- <官网中文组件名>：模拟器示例「<README 中的准确示例标题>」；<页面意图>，使用 `<实际 Props/插槽/变量>`；<未选其他示例的关键原因>。
```

若 README/demo 没有能语义匹配的示例或公开能力，不创建相似自定义结构，也不得自行调整组件样式以强行匹配；在组件缺口记录中说明已评估的示例、不能满足的原因和建议新增的变体/API。仅当产品经理明确提出具体样式调整时，才可在其确认范围内使用 README 已文档化的公开样式变量。涉及动态面板时还必须附上 `dynamic-panel-policy.md` 的逐入口验收记录，不能只记录基础示例或页面覆盖率。