# 组件说明查阅与维护

组件 README 是组件能力、API、事件、插槽、类型和样式变量的唯一事实来源。组件目录只用于选型，页面配方只用于组合；不得在它们中复制完整 API 或变量表。

## 页面实现时的查阅流程

1. 从 `business-component-catalog.md` 和 `component-catalog.md` 确定候选组件。
2. 阅读所选组件的 `README.zh-CN.md`：先确认适用场景和全部代码演示标题，再确认实现所需的 Props、事件与插槽；模拟器中的每个示例都视为可选变体，而不是只看“基础用法”。
3. 按 `component-variant-selection.md` 从示例中选择最贴近当前页面语义和视觉结构的一种变体，并记录示例标题与实际使用的公开能力。默认保持该变体的原始样式，不读取或修改 `var.less` 以进行视觉适配；只有产品经理明确提出具体样式调整后，才读取该组件 `var.less` 中与该调整直接相关的公开变量。不得通过页面 CSS 覆盖组件内部样式。需要复杂数据、双向绑定或事件时，读取类型定义；需要组合方式时，读取 demo。新增的 `content-panel`、`title-bar`、`material-action-bar`、`material-detail`、`material-display-bar` 必须在使用前完整执行此步骤。
4. 仅使用已文档化的公开能力。README 未列出的能力不得假定存在；无法满足时按 `component-gap-template.md` 输出缺口说明。

## 需求到资料的映射

| 产品需求 | 必读资料 |
| --- | --- |
| 选择合适组件 | 组件目录、业务组件目录、对应 README 的介绍和 demo |
| 配置交互、按钮、校验或回调 | README 的 Props、Events、Slots、类型定义 |
| 产品经理明确提出组件样式调整 | README 的样式变量和 `var.less`；仅查阅和修改与该明确要求直接相关的公开变量 |
| 组合多个组件完成页面 | 页面配方、各组件 demo |
| 评估是否需要新组件 | 组件目录、README、组件缺口模板 |

## 给产品经理的请求方式

在需求中写明业务目标和涉及组件，并要求先读组件说明。例如：

```md
使用 $use-persagy-vant 实现工单详情页。先读取 `info-card`、`label`、`bottom-action-bar` 的组件说明和 demo；按其已有公开 Props、事件、插槽与模拟器示例实现需求，不新增同类组件，也不调整组件样式。
```

无需指定组件时，也可以要求 AI 先完成选型：

```md
使用 $use-persagy-vant 实现可编辑的工单详情。先从组件目录选择组件，再阅读所选组件说明后实现；交付时列出组件复用清单和实际使用的扩展能力。
```

## 交付中的组件复用清单

组件复用清单面向产品经理，组件名不得使用代码名（如 `label`、`bottom-action-bar`）或自行翻译。交付前执行以下规则：

1. 从 `packages/persagy-mobile/vant.config.mjs` 的 `site.locales['zh-CN'].nav` 读取组件官网导航名称和 `path`；在已安装包项目中，从同包的 `vant.config.mjs` 或已发布文档导航读取。
2. 使用官网导航名称中的中文名称作为链接文字，并链接到 `https://meri-mobile.netlify.app/#/zh-CN/<path>`。例如：`[字段展示](https://meri-mobile.netlify.app/#/zh-CN/label)`、`[动作栏](https://meri-mobile.netlify.app/#/zh-CN/bottom-action-bar)`。
3. 若官网导航本身展示“中文名称 + 英文名称”，可保留其完整名称，确保与网站完全一致；不得使用组件目录名替代名称。
4. 若组件尚未出现在官网中文导航或未发布，禁止编造跳转地址；以官网中文名称（如可取得）标注“待官网发布”，并在交付中说明。

清单格式如下：

```md
## 组件复用清单

- [字段展示](https://meri-mobile.netlify.app/#/zh-CN/label)：展示字段名称与回显值；左侧标签使用冒号。
- [信息卡片](https://meri-mobile.netlify.app/#/zh-CN/info-card)：承载成组详情字段。
- [动作栏](https://meri-mobile.netlify.app/#/zh-CN/bottom-action-bar)：承载页面级提交操作。
```

## 组件 README 的维护标准

每个组件 README 至少维护以下内容：

1. **适用场景**：解决什么问题；易误用时说明不适用场景。
2. **代码演示**：基础用法及有代表性的扩展能力。
3. **公开能力**：Props、Events、Slots、类型定义和样式变量。
4. **常用组合**：仅在组件有明确搭配对象时说明，避免重复页面配方。

新增或修改 API、事件、插槽、样式变量和推荐组合时，必须在同一改动中更新双语 README、demo 和组件目录的简短选型描述。