# 元素识别与组件匹配

界面优化的第一步不是写代码，而是完整识别页面元素，再为每个元素选择最贴近业务语义的 Persagy Vant 组件、模拟器示例和公开变量。目标是在不处理既有字段、数据和事件的前提下，用组件库原生能力替换页面结构。

## 四段式工作流

### 1. 整页元素扫描

先从上到下遍历页面；从 0 到 1 的需求则从需求中的页面区块开始。每个元素记录以下信息：

- **内容与字段**：标题、字段名称、回显值、标签、媒体、数量、时间、空值规则；保留字段名称、含义与数据来源。
- **层级与容器**：页面级、卡片外标题、卡片内标题、分组、列表项、字段行、固定底栏或动态面板。
- **交互与状态**：展示、跳转、打开选择、单选、多选、录入、上传、展开、删除、禁用、加载与提交。
- **呈现特征**：单/双/三行、左/右信息、前后图标、头像、标签组、媒体、是否需要换行或省略。

不得因为元素文案相似就直接选组件。例如“分类”可能是详情字段的标签型回显、工单卡片的状态标签，或可编辑的筛选条件，三者组件和变量不同。

### 2. 按语义快速匹配组件

以下表用于建立首轮候选，最终选择仍须阅读对应 README 与模拟器。

| 识别到的元素 | 首选组件 | 匹配边界 |
| --- | --- | --- |
| 白色卡片页面承载 | 【背景】`background` | 首页默认主题，其他层级灰色主题 |
| 页面一级大标题 | 【小蓝标】标题栏 `blue-mark-header` | 位于白色卡片外；不是普通卡片内分组标题 |
| 卡片内二级标题 | 【标题栏】`title-bar` 默认样式 | 备注、操作、箭头、必填或展开收起使用其公开 Props |
| 名称 + 回显值的详情字段 | 【字段展示】`label` | 依字段选择默认、加粗、链接、标签、媒体、换行、居右或 mini |
| 单一字段为录入或选择入口 | `field` 或 `cell` | 录入用 `field`；打开面板/下钻优先 `cell` 右图标样式 |
| 分组标题仅用于说明其下方的一块自由文本录入（如执行反馈、处理说明、备注） | 【输入框】`field` | 使用「换行文本域」：标题直接使用 `label`，不再额外拆出标题组件和自定义文本框 |
| 简单同构列表行 | 【单元格】`cell` / `cell-group` | 导航、选择、头像、标签组、双/三行等按模拟器变体匹配 |
| 单选对象/空间列表：左侧单选圆点，名称与一条位置/说明 | 【单元格】`cell` | 使用模拟器示例「单选单元格-双行样式」：前置单选 + `title` + `label`，不手写单选列表行 |
| 任务/检查项标题，标签可换行，右侧有状态和下钻箭头 | 【单元格】`cell` | 使用模拟器示例「换行标签栏」+ 右图标；不自绘任务行 |
| 分组标题下有多条同级说明、动作项、执行要求或检查内容 | 【单元格】`cell` / `cell-group` | 使用模拟器示例「多行备注」：一个分组对应一个单元格，标题和说明数组保持原样 |
| 工单的标题、标签、位置、展开信息与行内操作 | 【工单卡片】`work-order-card` | 不退化为自行拼接的 cell 列表 |
| 复杂多字段详情卡片 | 【信息卡片】`info-card` + `label` | 用字段类型与 `visible` 表达内容；不手写详情字段布局 |
| 任务/作业摘要卡：主标题、状态、设备/位置及多项标签属于同一对象 | 【信息卡片】`info-card` | 使用下方 `#default` 插槽组合【字段展示】与【单元格】换行标签栏，不拆成自定义白色卡片 |
| 独立状态、分类或关键词 | 【标签】`tag` | 先识别状态语义和是否可关闭/带数字/图标，再选 type、size 与示例 |
| 多个标签构成一个详情字段 | `label type="tag"` | 保留字段名与标签数组；不改为裸 `tag` 流 |
| 搜索 | 【搜索】`search variant="pure"` | 保留既有搜索绑定与事件 |
| 图片、视频、文件上传 | 【文件上传】`uploader` | 图片/视频选择模拟器示例「图片/视频表单」：以组件 `label` 呈现标题，`accept="image/*,video/*"`、`multiple`、`max-count="9"`、`preview-size="70"`；不自绘上传网格 |
| 阅读/详情/确认、表单、扁平单选/多选、树形选择动态面板 | `content-panel` / `form-panel` / `radio-panel` / `checkbox-panel` / `tree-select-panel` | 按任务类型强制匹配；不能承接的混合任务使用 `action-sheet` 已有变体；禁止轻量 `popup` 例外，见 `dynamic-panel-policy.md` |
| 当前上下文的复杂动态面板：标题/关闭、多类型选择条目、筛选或批量操作共同出现 | 【动作面板】`action-sheet` | 使用模拟器示例「自定义面板」：默认插槽在既有白色卡片内容结构中组合组件，不手写弹层骨架 |
| 页面级主次操作 | 【动作栏】`bottom-action-bar` | 固定操作栏，不自行实现 footer |

### 3. 变量与模拟器变体匹配

动态面板先执行 `dynamic-panel-policy.md` 的六类白名单与样式保护规则；树形单选/多选必须使用 `tree-select-panel`，不得因最终选中数量或面板复杂度改为扁平选择或手动拼装。

组件确定后，再根据元素盘点的字段、状态与视觉结构选择 README/demo 中的具体示例。优先使用已有 Props、事件和插槽；不得将 CSS 变量或页面样式作为第一选择。

- **标题**：一级标题固定选 `blue-mark-header`；二级标题固定选默认 `title-bar`。仅在存在真实必填、操作、备注、箭头或展开状态时开启相应 Props。
- **白色卡片内模块**：先按字段归属划分语义独立模块；出现两个及以上模块时，每个模块使用二次卡片承载。普通、中性模块使用 `--van-gradient-gray`，当前重点、选中或待处理模块使用 `--van-gradient-blue`；优先给支持该能力的组件传入公开 `background`，其他模块容器仅使用 `gradient-gray` / `gradient-blue` 工具类。单字段、同一模块的连续字段及已经由业务卡片承载的内容不再叠加二次卡片，不手写渐变或覆盖组件样式。
- **单元格**：跳转/打开面板选箭头变体；真实单选/多选选前置或后置选择变体；对象识别选头像；稳定三层信息选三行；多个分类/状态选标签组。单选对象/空间列表为左侧圆点、对象名称和一条位置/说明时，使用「单选单元格-双行样式」：原单选状态绑定 `v-model:left-select`，设置 `select-type="radio"`、`show-left-select`，名称传入 `title`，位置或说明传入 `label`；有位置图标时使用 `show-label-icon` 与 `label-icon="location-o"`。仅原标题已强调时才使用 `title-bold`，并保留原 `click`、可选数量与禁用逻辑，不通过原生 radio 或手写列表行替代。任务或检查项为单行标题、下方标签可因数量换行、右侧同时有状态与下钻入口时，使用「换行标签栏」示例的 `title`、`wrap-tags`、`show-wrap-tags`、`value`、`right-icon="arrow"` 与原有 `click`；只有任务标题在原页面需强调时才加 `title-bold`。分组标题下有多条同级说明（如动作项、执行顺序、执行要求、检查内容）时，使用「多行备注」示例：`title` 保持分组标题，`multi-line-notes` 保持原始说明数组，并开启 `show-multi-line-notes`；一个分组对应一个单元格，保留说明顺序，不合并成自定义段落或手写列表。只有原界面确实支持分组展开/收起时，才启用 `show-title-collapse-icon`、`default-multi-line-notes-collapsed` 及 `update:multi-line-notes-collapsed`；静态说明不要增加折叠或右图标。多个此类单元格位于同一白色卡片时沿用 `cell-group` 分割逻辑，卡片最后一个实际单元格隐藏分割线（`border=false`）。详见 `component-variant-selection.md`。
- **输入框**：分组标题只服务于一块自由文本录入时（如执行反馈、处理说明、备注），合并为【输入框】「换行文本域」而不是“标题 + 自定义文本框”：用原标题作为 `label`，`type="textarea"`、`label-position="top"`、`input-align="left"`，按既有内容高度使用 `rows` 与 `autosize`，并保留原 `v-model`、`name`、`rules`、`required`、禁用/只读状态和提交校验。文本最大 `200` 字时使用 `maxlength="200"` 与 `show-word-limit`；不为同一字段额外添加 `title-bar`。
- **文件上传**：图片/视频采集使用【文件上传】模拟器示例「图片/视频表单」；用组件 `label` 承接原标题、`required` 承接必填，`v-model` 保留原文件列表映射，`accept="image/*,video/*"`、`multiple`、`max-count="9"` 和 `preview-size="70"` 承接类型、数量和布局。保留既有 `after-read` 上传处理、上传状态、删除、回显和视频预览事件；不得拆成独立标题、手写“拍照/上传”按钮或自定义预览网格。
- **信息卡片**：任务/作业摘要中主标题、状态、设备/位置、字段和多个标签共同描述同一对象时，优先使用【信息卡片】而不是自定义白色卡片。主标题与可直接映射的详情使用 `title`、`fields` 或 `extra-fields`；需要组合字段展示和任务标签栏时，使用下方 `#default` 插槽：字段使用【字段展示】`label`，任务标题、多个标签可自然换行、右侧状态和下钻入口使用【单元格】「换行标签栏」的 `title`、`wrap-tags`、`show-wrap-tags`、`value`、`right-icon="arrow"` 与原有 `click`。插槽只组合已有组件，不手写文本、标签或卡片样式；没有实际下钻行为时不设置箭头。
- **动态面板**：面板只提供单选时直接使用【单选面板】`radio-panel`，只提供复选时直接使用【多选面板】`checkbox-panel`；不要因为它从底部弹出就改用动作面板。只有同时包含标题/关闭、多个复杂选择项、筛选信息、数量提示或批量操作，且专用面板无法完整承接时，选择【动作面板】模拟器示例「自定义面板」。使用 `v-model:show` 保留显示状态，按原行为配置 `title`、`closeable`、`close-on-click-overlay`、`lock-scroll` 与关闭事件；默认插槽只在该示例已有的白色卡片内容区组合【标题栏】、【单元格】、【字段展示】、单选/多选组件及已有操作组件。选项仍绑定原选中状态、数量上限、禁用原因和确认事件；不得改用 `popup`、手写遮罩/底部弹层、手写白色卡片或自行实现 fixed 底栏。
- **字段展示**：普通回显用 `label` 默认；需要强调用 `type="bold"`，真实可操作链接用 `type="link"`，标签数组用 `type="tag"`，图片/视频用 `type="media"`；内容结构而不是视觉偏好决定 `vertical`、`content-align`、`size`、`ellipsis` 等变量。
- **标签**：先判断字段语义。业务状态使用 README 中与状态语义相符的 `type`；中性分类优先默认灰色类型；需要轮廓、圆角、标记、关闭、数字前缀或右图标时，分别匹配 `plain`、`round`、`mark`、`closeable`、`show-number`/`number`、`right-icon` 的模拟器示例。没有明确产品语义时，不使用 `color` 或 `text-color` 自定义颜色。
- **列表/卡片**：先选择业务卡片或 `cell` 的对应示例，再以公开字段 Props/数组/插槽承载原始数据；不通过手写间距、字体或色彩伪造另一种列表样式。

### 4. 字段不变实现核验

落地前和交付前逐项检查：

1. 每个原有可见字段仍被展示，或仅因原规则的空值隐藏而未展示；字段名、值、格式、顺序和含义未被处理。
2. 原有 `v-model`、接口字段映射、条件显隐、事件、路由和权限判断仍连接到对应组件公开 API。
3. 每个状态值都映射到组件已有变量/示例；不能确认映射时保留原有状态并记录待确认，不能因展示方便而合并、删除或改写状态。
4. 先使用模拟器原始样式与变量组合；未有产品经理明确的具体调整，不使用 `color`、`text-color`、Less/CSS 变量或页面 CSS 修改组件视觉。

## 元素-组件匹配记录

优化、审查和从 0 到 1 实现均需在工作中建立此记录；交付时按页面复杂度展示主要项。组件中文名称与链接必须符合 `component-documentation.md`。

```md
## 元素-组件匹配
- 页面一级标题「工单详情」→ [小蓝标](<官网链接>)：卡片外标题，使用 `blue-mark-header` 默认标题栏。
- 分组标题「基础信息」→ [标题栏](<官网链接>)：卡片内二级标题，使用默认样式；无备注、操作或展开状态，不开启额外变量。
- 字段「分类」及标签数组 → [字段展示](<官网链接>)：`type="tag"` + 原有标签数组，保持字段名称与数据不变。
- 工单条目 → [工单卡片](<官网链接>)：保留标题、标签、位置、收起/展开字段和原事件；不改为通用单元格。
- 筛选入口「处理状态」→ [单元格](<官网链接>)：模拟器示例「右图标 + 备注」，使用 `right-icon="arrow"`、原有 `click` 和 `note` 回显选择结果。
- 任务项「确认冷却塔已停机」及 EHS/要求拍照标签 → [单元格](<官网链接>)：模拟器示例「换行标签栏」，使用原任务标题作为 `title`、原标签数组作为 `wrap-tags`、`show-wrap-tags`、原状态作为 `value` 及 `right-icon="arrow"`；保留原跳转事件。
- 执行依据「动作项」及多条说明 → [单元格](<官网链接>)：模拟器示例「多行备注」，使用原分组名作为 `title`、原说明数组作为 `multi-line-notes` 和 `show-multi-line-notes`；原界面无展开或跳转时，不配置展开图标和右图标。
- 作业准备摘要（任务标题、状态、设备/位置与 EHS/要求拍照标签）→ [信息卡片](<官网链接>)：使用 `title`、原字段数组，并在下方 `#default` 插槽组合 [字段展示](<官网链接>) 与 [单元格](<官网链接>)「换行标签栏」；保留原标签数组、状态和跳转事件，不自绘白色卡片。
- 选择无法执行对象（多条空间、选择数量、全选与下一步）→ [动作面板](<官网链接>)：模拟器示例「自定义面板」，用 `v-model:show`、原面板标题和关闭状态，在既有白色卡片内容区组合标题栏、原选择控件与【单元格】；保留原选中数组、最多可选数量、全选和下一步事件。
- 可反馈空间「2F 空调机房」及位置「B 栋 - F2」→ [单元格](<官网链接>)：模拟器示例「单选单元格-双行样式」，使用原选中值 `v-model:left-select`、`select-type="radio"`、`show-left-select`、`title`、`label` 及位置 `label-icon`；保留单选事件和禁用/数量判断。
- 执行反馈 → [输入框](<官网链接>)：模拟器示例「换行文本域」，使用原标题作为 `label`、原反馈字段作为 `v-model`，并使用 `type="textarea"`、`label-position="top"`、`maxlength="200"`、`show-word-limit`；保留原必填和校验规则。
- 照片/视频 → [文件上传](<官网链接>)：模拟器示例「图片/视频表单」，使用原标题作为 `label`、原文件列表作为 `v-model`，并使用 `required`、`accept="image/*,video/*"`、`multiple`、`max-count="9"` 和 `preview-size="70"`；保留原上传、删除、回显与预览事件。
```

当候选组件都不能同时满足元素语义、字段完整性和既有交互时，停止实现相似自定义结构，按组件缺口流程记录已评估的组件、示例和缺失能力。