# 基础组件目录

本文件用于快速选型，不替代 API 文档。选中组件后的查阅顺序见 `component-documentation.md`；props、事件、插槽、样式变量和导入方式必须以 `packages/persagy-mobile/src/<component>/README.zh-CN.md`、类型定义和 demo 为准。

## 页面骨架与状态

- `background`：含白色卡片的页面优先使用此容器；一级页面使用 `theme="default"`，其他层级页面使用 `theme="gray"`。仅在没有白色卡片且无明确背景设计时使用 `--van-gray-1`。
- `nav-bar`、`tabbar`、`tab`、`tabs`、`sidebar`：页面与分区导航。标签较多时优先使用 `tabs` 的滚动或更多面板能力；筛选型分区选择 `type="filter"`。
- `cell`、`cell-group`、`row`、`col`、`space`、`divider`：信息布局与分组；动态面板的页面触发器优先使用 `cell` 的【单元格】右图标样式（`right-icon="arrow"` + `click`），当前结果使用 `value` 或 `note` 回显。白色卡片内有多个独立信息模块时，模块优先使用 `cell` 公开 `background` 能力承接 `--van-gradient-gray` 或 `--van-gradient-blue` 二次卡片背景；其他容器只使用 `gradient-gray` / `gradient-blue` 公共工具类。白色卡片内的最后一个可见 `cell` 或 `field` 设置 `border="false"`，不保留末尾分割线。
- `empty`、`loading`、`skeleton`、`overlay`、`pull-refresh`、`list`、`pagination`：加载、空态、刷新与列表分页；页面首次进入使用 `loading` 的 `type="illustration"`，并以纯色背景承载过渡。
- `collapse-toggle`：卡片内容区的展开/收起触发器；需要两侧分割线时使用其公开 `divider` 能力，不要自绘“查看更多/收起”控件。
- `bottom-action-bar`、`action-bar`、`submit-bar`：固定操作区；不要自行实现 fixed footer。

## 表单与通用选择

- `qr-scanner`：设备二维码采集，支持后置摄像头实时扫码、相册识别、函数调用和宿主扫码适配；用 `before-confirm` 异步查询设备并确认结果，`scan` 返回原始文本、码制与来源。设备详情跳转、位置定位及选中值由业务侧处理，不根据二维码内容自动跳转。对象选择、位置单选通过 `click-scan` 接入。
- `form-panel` + `form` + `field`：多字段编辑的表单面板、校验、输入与只读选择入口；需要录入文本时统一采用【输入框】换行文本域样式：`type="textarea"`、`label-position="top"`、`maxlength="200"`、`show-word-limit`，并按内容使用 `rows`、`autosize`。不要将同一编辑任务拆为零散弹层，也不要自绘文本域。
- `radio-panel`、`checkbox-panel`：动态面板内的单项和多项选择；单选使用 `radio-panel` 的 `v-model` 与 `select`，多选使用 `checkbox-panel` 的 `v-model` 与 `confirm`，不要自行拼接选择底部面板。
- `uploader`：图片、视频和文件上传统一采用【文件上传】表单示例的字段标签、白色卡片、上传与预览布局；图片/视频混合上传使用 `source-picker` 明确提供拍照、拍视频和从相册选择，使用 `accept` 区分文件类型，使用 `multiple`、`max-count="9"` 和 `preview-size="70"` 配置多文件上传。上传状态、删除、大小校验和超限提示只使用其公开 Props、事件和插槽。
- `checkbox`、`radio`、`switch`、`stepper`、`rate`、`slider`：布尔、单选、多选与数值录入。
- `picker`、`datetime-picker`、`calendar`、`area`、`cascader`、`tree-select`：普通选项、日期、地区、级联与树形数据选择；树节点需要按需请求子级时，使用 `tree-select` 的 `load-children` 异步加载能力。
- `search`、`filter-tag`、`dropdown-menu`、`dropdown-item`：搜索与轻量筛选；识别到搜索功能时，`search` 统一使用【搜索】纯净样式 `variant="pure"`，沿用 `v-model`、`search`、`cancel` 等公开能力连接既有筛选逻辑，不手写搜索区域。短选项的外露筛选优先使用 `filter-tag`，需要更大触达面积时选其大尺寸规格。

## 内容与反馈

- `label`：字段名称与回显值的首选组件，覆盖默认、加粗、链接、标签、图片视频及纵向布局；需要字段展示时优先使用，除录入、选择入口等应使用 `field` 或 `cell` 的场景外，不要为同类字段自行拼接样式。左侧标签文本尽量自带冒号，保证名称和值之间的统一阅读间距；按字段内容选择其公开展示类型。
- `info-card`：多种类型字段的白色信息卡片，可接收字段数组或插槽，并提供更多字段、固定分割线与展开收起能力；字段类型较多时优先使用，内部字段使用 `label` 呈现。任务/作业摘要中主标题、状态、设备/位置与标签属于同一对象时，可用 `title`、字段数组和下方 `#default` 插槽组合 `label` 与 `cell` 的「换行标签栏」；不手写同类卡片。固定分割线只用于字段分组，不作为卡片末尾分割线。
- `blue-mark`、`blue-mark-header`：一级标题和业务标识；页面一级标题统一使用放在白色卡片外层的 `blue-mark-header`，需要必填标识、右侧操作或展开收起时使用其公开能力，不手写同类标题栏。
- `title-bar`：白色卡片内的二级标题统一使用默认样式（不使用 `mini`）；用 `show-description`、`show-icon`、`show-arrow` 和 `expandable`/`v-model` 组合备注、图标、箭头和展开内容。视觉调整只使用其 `--van-title-bar-*` 公开变量。
- `card`、`tag`、`badge`、`notice-bar`、`image`、`icon`：内容展示与状态标识。
- `action-sheet`：上下文动作或专用面板不能承接的混合任务采用已有动作列表变体或模拟器「自定义面板」；插槽只组合已有组件，保持示例原有结构和视觉。动态面板禁止以 `popup`、`share-sheet`、`popover` 等替代，详见 `dynamic-panel-policy.md`；锚定气泡仍按其原用途使用。
- `content-panel`：承载阅读、详情与确认的分组内容，使用 `v-model:show`、`title`、`confirm-text`、`show-footer` 和 `confirm`/`close` 事件完成打开、确认与关闭；用 `footer` 插槽组合既有操作组件。内部优先组合 `cell`、`blue-mark-header`、`title-bar`、`material-display-bar`；保持既有面板样式，公开 CSS 变量不是自行调整视觉的授权。
- `tree-select-panel`：树形数据单选/多选的专用面板；从 README/demo 已有单/多选、搜索、级联、分级选择显隐与加载组合中选型，不以 `action-sheet` + `tree-select` 手动复刻。
- `dialog`、`toast`、`notify`：确认、短反馈与顶部通知；不得重复封装确认弹窗或全局提示。
- `friendly-tip`、`popover`：基于触发元素的引导说明和轻量操作菜单。一次性友好引导使用 `friendly-tip`，点击空白处关闭；不要手写定位气泡。
- `swipe`、`swipe-item`、`swipe-cell`、`collapse`、`grid`、`index-bar`：浏览、滑动操作、折叠和网格内容。

## 选型规则

- 动态面板必须按 `dynamic-panel-policy.md` 从六类面板及其已有变体中选型：阅读/详情/确认用 `content-panel`，表单用 `form-panel`，扁平单选/多选用 `radio-panel` / `checkbox-panel`，树形选择用 `tree-select-panel`，上下文动作或混合任务用 `action-sheet`。不允许轻量 `popup` 例外或擅改面板样式；纯二次确认用 `dialog`，短暂提示用 `toast` / `notify`，不得用反馈组件替代业务面板。
- 可分页的业务列表：组合 `list`、`pull-refresh`、`empty`、`loading`，不要手写重复加载状态。
- 页面首次进入：纯色页面背景叠加 `loading type="illustration"`，数据就绪后再展示内容；局部加载按实际范围使用 `loading` 或 `skeleton`。
- 需要展示字段名称与回显值时优先使用 `label`，并让左侧标签文本尽量自带冒号；字段成组或类型较多时选择 `info-card` + `label`。只有简单、不需要统一字段样式或展开逻辑的内容才组合 `cell-group` 或 `card`。
- 标题层级：白色卡片外的一级标题使用 `blue-mark-header`；白色卡片内的二级标题使用默认样式的 `title-bar`。不以普通文本或自绘标题替代。
- 上传内容：图片、视频、文件一律使用 `uploader` 的【文件上传】表单示例样式；已达 `9` 个时继续点击上传区域，提示“最多支持上传9个”。
- 文本录入：一律使用 `field` 的【输入框】换行文本域样式（`type="textarea"` + `label-position="top"`）；最大 `200` 字并显示字数统计。
- 搜索：一律使用 `search variant="pure"` 的【搜索】纯净样式；保留既有 `v-model`、`search` 和 `cancel` 事件语义。
- 白色卡片列表：最后一个实际可见控件的末尾分割线必须隐藏；`cell`/`field` 用 `border="false"`，`material-display-bar` 用 `divider="false"`，其他组件查 README 后使用其公开能力。
- 动态面板触发器优先使用 `cell` 的【单元格】右图标样式（`right-icon="arrow"` + `click`）；当前结果使用 `value` 或 `note` 回显。具体面板优先从 `business-component-catalog.md` 选择。
- 页面有主操作时优先使用 `bottom-action-bar`；在表单提交语义明确时使用 `submit-bar`。
- 非破坏性的局部快捷操作使用 `popover`；会影响全局数据或需要确认的操作不使用气泡菜单。