persagy-vant 0.0.30 → 0.0.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "persagy-vant",
-  "version": "0.0.30",
+  "version": "0.0.32",
   "description": "Lightweight Mobile UI Components built on Vue",
   "main": "lib/vant.cjs.js",
   "module": "es/index.mjs",
@@ -11,8 +11,12 @@
   "files": [
     "es",
     "lib",
-    "skills"
+    "skills",
+    "bin"
   ],
+  "bin": {
+    "persagy-vant": "bin/persagy-vant.mjs"
+  },
   "npm": {
     "tag": "latest-v3"
   },

package/skills/use-persagy-vant/references/business-component-catalog.md

@@ -9,16 +9,20 @@
 | 选择空间或专业对象 | `object-select` | 空间/专业视角切换、树形对象多选 |
 | 选择楼座/楼层位置 | `location-select` | 楼座标签、位置树和位置单选 |
 | 按楼座和楼层选择空间 | `floor-select` | 全屏楼层导航、空间单元格和楼座更多面板 |
-| 添加物料、工具或备件 | `material-add` | 物料搜索、分类、数量和已选清单 |
+| 添加物料、工具或备件 | `material-add` | `v-model:show` 控制面板、`v-model` 同步与 `items` 顺序对应的数量数组；以 `categories` 配置物资/工具分组和分类，使用 `change`/`confirm` 取得数量 |
+| 操作单条物料数量 | `material-action-bar` | 通过 `v-model` 同步数量；`keyword` 高亮检索内容，`selected` 呈现已选样式，`enable-input-dialog` 控制数量输入，`detail` 事件打开详情 |
+| 查看物料的完整介绍 | `material-detail` | 通过 `v-model:show` 打开；传入 `item`、`categories`、`fields` 和 `images`，需要替换基础信息区时使用 `basic-info` 插槽 |
+| 展示物料名称、数量及仓库明细 | `material-display-bar` + `label` | `fields` 复用 Label Mini 字段回显；支持库存不足、左滑删除、标题跳转及 `title`/`quantity`/默认插槽。列表最后一项可设 `divider=false`；视觉调整只使用 `--van-material-detail-*` 公开变量 |
 | 批量勾选条目/录入数量 | `quantity-input` | 已选项展开、清空和批量确认 |
 | 工单列表的组合筛选 | `work-order-filter` | 项目、时间、排序、待办和工单类型筛选 |
 | 业务层级选项 | `tree-select` | 单选/多选树、父子联动和展开收起 |
 | 页面底部主次操作 | `bottom-action-bar` | 固定底栏、更多操作、按钮 loading/disabled |
 | 蓝色标识或业务标注 | `blue-mark` | 相同视觉的业务标签/标记 |
-| 展示多类型详情字段 | `info-card` + `label` | 文字、强调、链接、标签、图片/视频字段回显、接口字段可见性、更多信息与展开收起 |
+| 展示字段或多类型详情字段 | `label` / `info-card` + `label` | 单个字段回显优先 `label`，左侧标签文本尽量自带冒号；字段成组或类型较多时用 `info-card` 承载，并支持接口字段可见性、更多信息与展开收起 |
 | 视频预览 | `video-preview` | 视频预览容器与交互 |
 | AI 对话面板/移动端 bot | `bot-mobile` 系列（`BotMobile`/`BotMobilePrompts`/`BotMobileContextTags`/`BotMobileSheet`/`BotMobileView`/`BotFab`/`BotHistoryDrawer`/`BotVoiceBar`/`BotSessionList`） | 对话流、消息渲染、示例输入、上下文标签、呼出面板、纯展示消息渲染、悬浮入口、会话历史抽屉、按住说话和全部会话列表 |
 | 展示和处理工单 | `work-order-card` | 工单标题、标签、位置、展开详情和卡片内操作 |
+| 阅读并确认一组执行内容 | `content-panel` | 底部内容面板、标题关闭入口、确认区和可组合内容插槽；用 `confirm` 事件承接“我已知晓”等确认动作 |
 
 ## 业务组件组合
 
@@ -27,5 +31,6 @@
 - **工单列表（包含展开信息或行内操作）**：按页面层级选择 `background` 主题 + `work-order-filter` + `pull-refresh` + `list` + `work-order-card` + `empty`；不要在工单卡片页面省略背景容器。
 - **按楼层选择空间**：`floor-select`；不要自行组合楼座标签、楼层导航和空间选择列表。
 - **批量任务或物料确认**：`quantity-input` 或 `material-add` + `bottom-action-bar` + `dialog`。
+- **物料添加与回显**：`material-add` 通过 `change`/`confirm` 同步数量数组；选择完成后用 `material-display-bar` 回显，点击物料名称或 `material-action-bar` 的 `detail` 事件时使用 `material-detail` 展示完整信息。库存不足需使用 `stock-insufficient`，移除物料需使用 `swipe-delete` + `delete`，不要手写同类交互。
 - **巡检/维修详情**：`nav-bar` + `cell-group`/`card` + `tag` + `action-bar`/`bottom-action-bar`。
-- **字段型业务详情**：多类型字段优先使用 `info-card` + `label`，按字段内容选择 `label` 的默认、加粗、链接、标签、图片视频或纵向布局；图片或视频字段通过 `click-media` 事件连接 `image-preview` 或 `video-preview`，不要在页面内重复实现媒体字段布局。
+- **字段型业务详情**：单个字段回显优先使用 `label`，左侧标签文本尽量自带冒号；多类型字段优先使用 `info-card` + `label`，按字段内容选择 `label` 的默认、加粗、链接、标签、图片视频或纵向布局；图片或视频字段通过 `click-media` 事件连接 `image-preview` 或 `video-preview`，不要在页面内重复实现媒体字段布局。

package/skills/use-persagy-vant/references/component-catalog.md

@@ -7,7 +7,7 @@
 - `background`：含白色卡片的页面优先使用此容器；一级页面使用 `theme="default"`，其他层级页面使用 `theme="gray"`。仅在没有白色卡片且无明确背景设计时使用 `--van-gray-1`。
 - `nav-bar`、`tabbar`、`tab`、`tabs`、`sidebar`：页面与分区导航。标签较多时优先使用 `tabs` 的滚动或更多面板能力；筛选型分区选择 `type="filter"`。
 - `cell`、`cell-group`、`row`、`col`、`space`、`divider`：信息布局与分组。
-- `empty`、`loading`、`skeleton`、`overlay`、`pull-refresh`、`list`、`pagination`：加载、空态、刷新与列表分页。
+- `empty`、`loading`、`skeleton`、`overlay`、`pull-refresh`、`list`、`pagination`：加载、空态、刷新与列表分页；页面首次进入使用 `loading` 的 `type="illustration"`，并以纯色背景承载过渡。
 - `collapse-toggle`：卡片内容区的展开/收起触发器；需要两侧分割线时使用其公开 `divider` 能力，不要自绘“查看更多/收起”控件。
 - `bottom-action-bar`、`action-bar`、`submit-bar`：固定操作区；不要自行实现 fixed footer。
 
@@ -20,11 +20,13 @@
 
 ## 内容与反馈
 
-- `label`：详情字段的名称与回显值展示，覆盖默认、加粗、链接、标签、图片视频及纵向布局；不要为同类字段自行拼接样式。按字段内容选择其公开展示类型。
-- `info-card`：多种类型字段的白色信息卡片，可接收字段数组或插槽，并提供更多字段、固定分割线与展开收起能力；字段类型较多时优先使用。
+- `label`：字段名称与回显值的首选组件，覆盖默认、加粗、链接、标签、图片视频及纵向布局；需要字段展示时优先使用，除录入、选择入口等应使用 `field` 或 `cell` 的场景外，不要为同类字段自行拼接样式。左侧标签文本尽量自带冒号，保证名称和值之间的统一阅读间距；按字段内容选择其公开展示类型。
+- `info-card`：多种类型字段的白色信息卡片，可接收字段数组或插槽，并提供更多字段、固定分割线与展开收起能力；字段类型较多时优先使用，内部字段使用 `label` 呈现。
 - `blue-mark`、`blue-mark-header`：分组/卡片标题及标题栏操作；标题栏需要必填标识、右侧操作或展开收起时优先使用 `blue-mark-header`。
+- `title-bar`：卡片内的普通分组标题；用 `show-description`、`show-icon`、`show-arrow`、`size` 和 `expandable`/`v-model` 组合备注、图标、箭头和展开内容。视觉调整只使用其 `--van-title-bar-*` 公开变量。
 - `card`、`tag`、`badge`、`notice-bar`、`image`、`icon`：内容展示与状态标识。
 - `popup`、`action-sheet`、`share-sheet`、`popover`：动作选择与自定义容器。
+- `content-panel`：承载需阅读确认的分组内容，使用 `v-model:show`、`title`、`confirm-text`、`show-footer` 和 `confirm`/`close` 事件完成打开、确认与关闭；用 `footer` 插槽替换默认确认区。内部优先组合 `cell`、`blue-mark-header`、`title-bar`、`material-display-bar`；视觉调整只使用 `--van-content-panel-background`、`--van-content-panel-radius`、`--van-content-panel-footer-padding`。
 - `dialog`、`toast`、`notify`：确认、短反馈与顶部通知；不得重复封装确认弹窗或全局提示。
 - `friendly-tip`、`popover`：基于触发元素的引导说明和轻量操作菜单。一次性友好引导使用 `friendly-tip`，点击空白处关闭；不要手写定位气泡。
 - `swipe`、`swipe-item`、`swipe-cell`、`collapse`、`grid`、`index-bar`：浏览、滑动操作、折叠和网格内容。
@@ -33,7 +35,8 @@
 
 - 需要承载自定义表单/内容：使用 `popup`；仅确认操作：使用 `dialog`；短暂提示：使用 `toast` 或 `notify`。
 - 可分页的业务列表：组合 `list`、`pull-refresh`、`empty`、`loading`，不要手写重复加载状态。
-- 详情页的字段组优先选择 `info-card`；只有简单、不需要统一字段样式或展开逻辑的内容才组合 `cell-group` 或 `card`。
+- 页面首次进入：纯色页面背景叠加 `loading type="illustration"`，数据就绪后再展示内容；局部加载按实际范围使用 `loading` 或 `skeleton`。
+- 需要展示字段名称与回显值时优先使用 `label`，并让左侧标签文本尽量自带冒号；字段成组或类型较多时选择 `info-card` + `label`。只有简单、不需要统一字段样式或展开逻辑的内容才组合 `cell-group` 或 `card`。
 - 选择入口默认使用 `field` 或 `cell`，具体选择面板优先从 `business-component-catalog.md` 选择。
 - 页面有主操作时优先使用 `bottom-action-bar`；在表单提交语义明确时使用 `submit-bar`。
 - 非破坏性的局部快捷操作使用 `popover`；会影响全局数据或需要确认的操作不使用气泡菜单。

package/skills/use-persagy-vant/references/component-documentation.md

@@ -6,7 +6,7 @@
 
 1. 从 `business-component-catalog.md` 和 `component-catalog.md` 确定候选组件。
 2. 阅读所选组件的 `README.zh-CN.md`：先确认适用场景和演示，再确认实现所需的 Props、事件与插槽。
-3. 需要视觉适配时，读取该组件 `var.less` 中的公开变量；需要复杂数据或事件时，读取类型定义；需要组合方式时，读取 demo。
+3. 需要视觉适配时，读取该组件 `var.less` 中的公开变量；需要复杂数据、双向绑定或事件时，读取类型定义；需要组合方式时，读取 demo。新增的 `content-panel`、`title-bar`、`material-action-bar`、`material-detail`、`material-display-bar` 必须在使用前完整执行此步骤。
 4. 仅使用已文档化的公开能力。README 未列出的能力不得假定存在；无法满足时按 `component-gap-template.md` 输出缺口说明。
 
 ## 需求到资料的映射

package/skills/use-persagy-vant/references/design-interaction-baseline.md

@@ -14,7 +14,7 @@
 - 信息展示和录入控件以白色卡片承载；背景主题与页面层级不一致时，以明确的页面原型为准。
 - 卡片内容与页面左右边缘保持 `16px` 间距；卡片之间间距 `8px`。
 - 模块之间、控件之间使用 `8px` 或 `12px` 间距；仅左右排布的两组字段，纵向间距不得小于 `8px`。
-- 存在多种字段展示类型（文字、强调文字、链接、标签、图片/视频或纵向字段）时，优先使用 `info-card` + `label`；按字段内容选择 `label` 的公开展示类型和纵向布局。字段无数据时整项隐藏，使用 `info-card` 时通过字段的 `visible: false` 实现。
+- 需要展示字段名称与回显值时，优先使用 `label`，不要手写同类标签和值的排版；左侧标签文本尽量自带冒号，保证名称和值之间的统一阅读间距。录入或选择入口仍使用 `field`、`cell` 等对应组件。多字段成组或存在多种字段展示类型（文字、强调文字、链接、标签、图片/视频或纵向字段）时，优先使用 `info-card` + `label`；按字段内容选择 `label` 的公开展示类型和纵向布局。字段无数据时整项隐藏，使用 `info-card` 时通过字段的 `visible: false` 实现。
 - 触发器没有内置按压态时，叠加 `5%` 黑色透明遮罩作为按压反馈；有内置按压态的组件不重复添加。
 - 字体跟随设备系统字体。常规层级使用：一级标题 `16px` 加粗、二级标题与正文 `14px`、补充说明 `12px`、底部菜单最小 `10px`；有明确业务需要时可调整。
 - 信息层级最多使用四级：一级标题优先采用 `blue-mark`，二级使用灰底加粗文本，三级使用白底加粗文本，四级使用弱化的卡片内容；特殊业务可按组件文档调整。
@@ -41,11 +41,11 @@
 
 - 点击搜索入口后自动聚焦并唤起键盘；非业务必需时，在搜索态提供取消操作。键盘唤起后内容区不保留无关内容。
 - 列表使用 `pull-refresh` 处理下拉刷新，使用 `list` 处理滚动加载；无更多数据时展示明确的结束提示。
-- 请求超过 `500ms` 时展示加载反馈：局部请求使用 `loading` 或 `skeleton`，全局请求使用全局加载状态。
+- 整个页面首次进入时，先以纯色页面背景叠加 `loading` 的 `type="illustration"` 作为过渡；数据就绪后再展示正常页面内容。局部请求或后续请求超过 `500ms` 时，使用 `loading` 或 `skeleton` 等相应加载反馈，不以页面级插画加载替代局部反馈。
 
 ## 页面状态与信息反馈
 
-- 页面初始化展示加载状态；加载完成无数据时展示空状态页面。
+- 页面初始化展示插画加载状态；加载完成无数据时展示空状态页面。
 - 操作成功或失败均提供全局反馈；重要或高风险信息使用 `dialog`、`notice-bar` 等强提醒样式。
 - 所有不可用操作都必须可被点击或聚焦后说明具体不可用原因，提示文案为“`<具体原因>`”，不得只展示禁用态而无解释。
 - 友好提示仅展示一次，点击空白区域后消失。

package/skills/use-persagy-vant/references/page-recipes.md

@@ -2,11 +2,17 @@
 
 配方限定页面结构，不替代具体组件 API。开始编码前先选择最接近的一项。
 
+## 全页面进入过渡
+
+1. 页面首次进入时，使用纯色页面背景叠加 `loading type="illustration"`，作为页面内容加载完成前的过渡。
+2. 数据就绪后展示正常页面；无数据时切换为 `empty`，不保留插画加载状态。
+3. 页面内局部刷新、分页和提交中的加载按范围使用 `loading`、`skeleton` 或按钮 `loading`，不重复使用全页面插画加载。
+
 ## 创建/编辑业务单据
 
 1. `nav-bar` 放置标题和返回操作。
 2. 多字段编辑在表单面板内使用 `form` + `field` 组织输入与校验；选择字段仅作为触发器。
-3. 需要人员、位置、对象或物料时，接入对应 Persagy 业务组件。
+3. 需要人员、位置、对象或物料时，接入对应 Persagy 业务组件；物料选择使用 `material-add` 的数量数组双向绑定和 `change`/`confirm` 事件，已选物料用 `material-display-bar` 回显。
 4. 使用 `bottom-action-bar` 放置保存、提交或次操作；提交中禁用重复点击。
 5. 成功使用 `toast`，离开未保存页面使用 `dialog` 确认。
 
@@ -21,10 +27,11 @@
 ## 详情与处理页
 
 1. 页面含白色卡片时，用 `background` 承载页面内容：一级页面使用 `theme="default"`，其他层级页面使用 `theme="gray"`。
-2. 多类型字段详情优先用 `info-card` 承载；简单内容再用 `cell-group`、`card`、`divider` 组织分组。
-3. 字段回显使用 `label`，按字段内容选择默认、加粗、链接、标签、图片视频或纵向布局；媒体点击接入 `image-preview` 或 `video-preview`。
-4. `info-card` 的接口字段使用 `visible: false` 隐藏无数据项。需要更多字段时优先使用其固定分割线或展开收起能力；其他卡片内容的展开收起使用 `collapse-toggle` 或 `blue-mark-header`，不自行绘制触发器。
-5. 主要处理动作使用 `bottom-action-bar`；可能造成数据变更的操作先经 `dialog`。
+2. 需要展示字段名称与回显值时优先使用 `label`，左侧标签文本尽量自带冒号；录入或选择入口仍使用 `field`、`cell` 等对应组件。
+3. 多字段成组或字段类型较多时用 `info-card` 承载 `label`；简单内容再用 `cell-group`、`card`、`divider` 组织分组。
+4. 按字段内容选择 `label` 的默认、加粗、链接、标签、图片视频或纵向布局；媒体点击接入 `image-preview` 或 `video-preview`。
+5. `info-card` 的接口字段使用 `visible: false` 隐藏无数据项。需要更多字段时优先使用其固定分割线或展开收起能力；其他卡片内容的展开收起使用 `collapse-toggle` 或 `blue-mark-header`，不自行绘制触发器。
+6. 主要处理动作使用 `bottom-action-bar`；可能造成数据变更的操作先经 `dialog`。
 
 ## 编辑与全局操作
 
@@ -32,6 +39,12 @@
 2. 当前页面或当前数据集的全局操作统一放入 `bottom-action-bar`。
 3. 按操作数量选择 `bottom-action-bar` 文档提供的变量、布局或溢出方案；使用前必须查阅其 README 和 demo。
 
+## 阅读确认内容
+
+1. 对执行前须阅读并确认的人员、约束、影响或物料信息使用 `content-panel`，不要自行拼接底部确认弹层。
+2. 使用 `v-model:show` 控制显示，使用 `title`、`confirm-text` 和 `confirm` 事件表达确认语义；需要多按钮或特殊操作时使用 `footer` 插槽。
+3. 面板内的分组标题使用 `blue-mark-header` 或 `title-bar`，物料回显使用 `material-display-bar`；展开状态使用这些组件的公开 `v-model` 能力。
+
 ## 选择型流程
 
 1. 使用 `field` 或 `cell` 显示当前选择结果并触发面板。

package/skills/use-persagy-vant/references/reuse-policy.md

@@ -4,7 +4,7 @@
 
 - 必须从 Persagy Vant 选择现有基础组件和业务组件；先查业务组件目录，再查基础组件目录。
 - 必须阅读目标组件 README 和 demo 后再使用 API。
-- 必须处理 loading、empty、error、disabled 或 submitting 等与页面类型相关的状态。
+- 必须处理 loading、empty、error、disabled 或 submitting 等与页面类型相关的状态；整个页面首次进入时，使用纯色背景叠加 `loading type="illustration"` 进行过渡。
 - 必须在最终回复、PR 描述或交付说明中附上组件复用清单。
 
 ## 禁止事项

package/skills/use-persagy-vant/references/usage-patterns.md

@@ -1,5 +1,9 @@
 # 页面组合规则
 
+## 全页面进入
+
+首次进入页面时，以纯色背景叠加 `loading type="illustration"` 过渡；数据就绪后再展示页面内容，完成但无数据时切换为 `empty`。局部请求不使用页面级插画加载。
+
 ## 表单页
 
 以 `form` 作为校验与提交边界，用 `field` 承载输入或只读选择入口。选择型字段连接已有选择组件；提交中通过按钮的 loading/disabled 状态防止重复提交。底部主操作优先使用 `bottom-action-bar` 或 `submit-bar`。
@@ -10,7 +14,11 @@
 
 ## 详情页
 
-用 `cell-group`、`card`、`tag` 组织信息，页面级动作放在 `bottom-action-bar` 或 `action-bar`。危险或不可逆操作必须经 `dialog` 确认，并在完成后用 `toast` 或 `notify` 反馈。
+字段名称与回显值优先使用 `label`，左侧标签文本尽量自带冒号；多字段成组或字段类型较多时使用 `info-card` + `label`。其余信息可用 `cell-group`、`card`、`tag` 组织，页面级动作放在 `bottom-action-bar` 或 `action-bar`。危险或不可逆操作必须经 `dialog` 确认，并在完成后用 `toast` 或 `notify` 反馈。
+
+## 物料流程与阅读确认
+
+选择物料、工具或备件使用 `material-add`；单项数量操作使用 `material-action-bar`，详情使用 `material-detail`，提交前或详情页回显使用 `material-display-bar`。执行前阅读与确认使用 `content-panel`，面板内以 `title-bar` 或 `blue-mark-header` 分组；除非需求另有规定，确认动作由 `confirm` 事件承接。
 
 ## 样式扩展