---
name: use-persagy-vant
description: 使用 Persagy Vant 为 Vue 3 移动端业务页面规划、实现、改造或验收 UI 时使用。适用于产品经理或 Vibe Coding 用户需要复用本组件库的基础组件与 Persagy 业务组件，并要求统一页面交互、视觉与 API 使用方式的任务。
---

# 使用 Persagy Vant

将 Persagy Vant 视为此项目唯一的 UI 与业务组件来源。页面可以组合组件、组织业务数据和编写接口逻辑，但不得重写组件库已经提供的基础控件、交互模式或业务组件。

## 动态面板硬约束

所有触发的动态面板（包括二级面板、已选展开、筛选、详情和编辑面板）必须由 `ContentPanel`、`FormPanel`、`RadioPanel`、`CheckboxPanel`、`TreeSelectPanel` 或 `ActionSheet` 承载，并按语义选用其 README/demo 已有的样式变体与变量组合。不得以 `Popup`、手写弹层或其他通用容器替代，即使内容少或页面组件覆盖率已达 `90%` 也不例外。不得擅自修改面板组件样式；选用预置变体不等于获得修改 CSS/Less 变量的授权。

涉及动态面板时，在选型和编码前必须阅读 [动态面板规范](references/dynamic-panel-policy.md)，交付前逐个触发入口核查面板组件、示例/变量和样式未改动情况。此规范优先于其他资料中的通用容器、页面布局和轻量样式扩展建议；组件缺口必须反馈，不得自行绕过。

## 强制工作流

1. 阅读 `references/reuse-policy.md`，确认复用边界与禁止项。
2. 阅读 `references/design-interaction-baseline.md` 与 `references/public-style-system.md`，将其中适用的设计、状态和反馈规则落实到页面；如与产品需求冲突，以明确的产品需求为准并说明差异。
3. 阅读 `references/element-component-matching.md`，先完整盘点当前页面或需求中的可见元素、字段、状态、交互和层级，再建立元素到组件的匹配；不得先编码或只凭单个关键词选组件。
4. 阅读 `references/business-component-catalog.md`，按元素盘点结果先确定业务组件；再从 `references/component-catalog.md` 补齐基础组件。
5. 按 `references/component-documentation.md` 的查阅流程读取每个被选中组件的 README 和 demo：在组件库仓库中使用 `packages/persagy-mobile/src/<component>/README.zh-CN.md`，在业务项目中使用 `node_modules/persagy-vant/es/<component>/README.zh-CN.md`。涉及视觉、插槽或类型扩展时，同时查阅 `var.less`、类型定义和 demo；API、事件、插槽和导入方式均以这些资料为准。
6. 阅读 `references/component-variant-selection.md`，针对每个可见或可交互 UI 单元，从该组件模拟器/README 的示例中选定最贴近当前页面的具体样式与变量组合；不得仅按组件名称套用基础示例。
7. 按 `references/page-recipes.md` 组合页面，补齐加载、空数据、错误、禁用和提交中状态。用户要求“审查并优化当前页面”或语义等同的 UI 优化时，默认按 `references/reuse-policy.md` 的非侵入式优化规则执行：不得改变已有接口、请求/响应数据、字段映射、数据内容或业务事件。
8. 无论是单个页面审查/优化，还是从 0 到 1 的页面规划与实现，页面组件覆盖率均必须不低于 `90%`。将组件复用清单中的组件职责视为页面覆盖基线：默认保持模拟器示例与组件原样，只使用其既有 Props、事件、插槽和样式变体完成搭建；未经产品经理明确提出具体样式调整，不得改动 Less/CSS 变量、覆盖组件视觉或自行定制组件样式。
9. 输出或提交前，按 `references/reuse-policy.md`、`references/design-interaction-baseline.md`、`references/element-component-matching.md` 和 `references/component-variant-selection.md` 完成自查，并附上“元素-组件匹配”“组件复用清单”“组件变体选型”“规范落实项”“业务与数据兼容核查”和“组件覆盖率”。组件复用清单必须按 `references/component-documentation.md` 使用官网中文名称和可点击的组件展示链接；未达到 `90%` 时，必须记录覆盖率缺口并反馈给产品经理，说明需要优化的组件变量或建议新增的组件，供其反馈组件库维护方；未经产品经理明确确认例外，不得作为合规页面交付。

## 组件缺口

找不到合适能力时，停止新建通用控件或业务组件。改为读取并按 `references/component-gap-template.md` 输出组件缺口说明，等待组件库维护者处理。

只允许为单一页面补充不具备复用价值的业务数据转换、接口调用和页面级状态；这些代码不得包装或替代现有组件。

## 资料边界

- 组件库仓库中的 `packages/persagy-mobile/src/<component>/README.zh-CN.md`，或已安装包中的 `node_modules/persagy-vant/es/<component>/README.zh-CN.md`，连同类型定义和 demo，是组件 API 的唯一事实来源。
- `references/` 用于选型、组件文档查阅、复用规则、页面组合与设计交互基线，不能据此编造不存在的 props 或事件。
- 当前目录是对外分发版本；随 `persagy-vant` 发布版本一起更新。组件库维护、扩展或新增组件不属于本 Skill 的授权范围。
