@qynpm/ui 1.0.26 → 1.0.28

package/README.md

@@ -39,8 +39,21 @@ import {
   QyFilePicker,
   QySwitch,
   QyTag,
+  QyBadge,
+  QyCascader,
   QyTooltip,
   QyPopover,
+  QySkeleton,
+  QySkeletonItem,
+  QyTabs,
+  QyTabPane,
+  QySteps,
+  QyStep,
+  QyLink,
+  QyDivider,
+  QyEmpty,
+  QyScrollbar,
+  QyProgress,
   QyImage,
   QyImagePreview,
   QyImageUpload,
@@ -90,8 +103,21 @@ import QyUpload from '@qynpm/ui/qy-upload'
 import QyFilePicker from '@qynpm/ui/qy-file-picker'
 import QySwitch from '@qynpm/ui/qy-switch'
 import QyTag from '@qynpm/ui/qy-tag'
+import QyBadge from '@qynpm/ui/qy-badge'
+import QyCascader from '@qynpm/ui/qy-cascader'
+import QyTree from '@qynpm/ui/qy-tree'
 import QyTooltip from '@qynpm/ui/qy-tooltip'
 import QyPopover from '@qynpm/ui/qy-popover'
+import QySkeleton from '@qynpm/ui/qy-skeleton'
+import QySkeletonItem from '@qynpm/ui/qy-skeleton-item'
+import QyTabs from '@qynpm/ui/qy-tabs'
+import QyTabPane from '@qynpm/ui/qy-tab-pane'
+import QySteps from '@qynpm/ui/qy-steps'
+import QyStep from '@qynpm/ui/qy-step'
+import QyLink from '@qynpm/ui/qy-link'
+import QyEmpty from '@qynpm/ui/qy-empty'
+import QyScrollbar from '@qynpm/ui/qy-scrollbar'
+import QyProgress from '@qynpm/ui/qy-progress'
 import QyImage from '@qynpm/ui/qy-image'
 import QyImagePreview from '@qynpm/ui/qy-image-preview'
 import QyImageUpload from '@qynpm/ui/qy-image-upload'
@@ -123,6 +149,80 @@ pnpm install --frozen-lockfile --ignore-scripts
 
 ## 组件说明
 
+### `QyEmpty`
+
+`QyEmpty` 使用 Element Plus `ElEmpty` 渲染只读空状态，支持 `image`、`imageSize` 和 `description` 属性，以及 `image`、`description`、默认三个原生插槽。组件不判断数据，不内置加载、错误、重试或按钮点击逻辑。
+
+```vue
+<QyEmpty description="暂无记录">
+  <template #image><img src="/empty.svg" alt="暂无记录" /></template>
+  <template #default>
+    <QyButton @click="createRecord">新建记录</QyButton>
+  </template>
+</QyEmpty>
+```
+
+`imageSize` 直接沿用 Element Plus 的数值语义；`image` / `description` 插槽遵循 Element Plus 的属性优先级。`class`、`style`、`id`、`title`、`role`、`data-*` 和 `aria-*` 安全透传到根节点，消费者传入的宽度、高度、margin、padding 均可覆盖，事件监听器和底层实例不对外暴露。
+
+### `QyScrollbar`
+
+`QyScrollbar` 以 Element Plus 2.14.3 的 `ElScrollbar` 作为唯一滚动实现。默认插槽直接承载滚动内容，支持固定高度、最大高度、纵向/横向滚动、原生/自定义滚动模式、`always`、滚动层样式与类名，以及 `tabindex`、`id`、`role`、`ariaLabel` 和 `ariaOrientation`。
+
+```vue
+<QyScrollbar height="240px" max-height="360px" always aria-label="消息列表">
+  <div v-for="message in messages" :key="message.id">{{ message.text }}</div>
+</QyScrollbar>
+
+<QyScrollbar
+  height="160px"
+  :distance="12"
+  @scroll="handleScroll"
+  @end-reached="loadMore"
+>
+  <div class="wide-content">横向内容由局部容器滚动</div>
+</QyScrollbar>
+```
+
+`scroll` 只返回只读快照 `{ scrollTop, scrollLeft }`；`end-reached` 返回 `top`、`bottom`、`left` 或 `right`，阈值由 Element Plus 的 `distance` 处理。实例只公开 `scrollTo(x, y)`、`scrollTo(options)`、`setScrollTop(value)`、`setScrollLeft(value)` 和 `update()`，挂载前或卸载后调用均为空操作。不显式暴露内部 `ElScrollbar` 实例、`wrapRef`、`handleScroll` 或 DOM ref；Vue 公共实例自带的 `$el` 不属于适配器承诺的稳定 API，消费者不得依赖。
+
+根节点仅安全透传 `class`、`style`、`title`、`data-*` 和不冲突的 `aria-*`；旧的 `width`、`vertical` 属性及未知 `on*` 监听器会被过滤。自定义模式只映射 `--el-scrollbar-bg-color` / `--el-scrollbar-hover-bg-color` 到 admin-theme 的 `--qy-scrollbar-thumb` / `--qy-scrollbar-thumb-hover`，不覆盖 Element Plus 滑块尺寸、定位、圆角、显隐或动画；原生模式继续使用 admin-theme 的全局原生滚动条规则。
+
+### `QyCascader`
+
+`QyCascader` 是 Element Plus Cascader 的受控适配器，保留单值、路径值和多选值的原始形状，不自动改写业务 options。支持 `expandTrigger`、`multiple`、`checkStrictly`、`emitPath`、`lazyLoad`、过滤、折叠标签、浮层定位、虚拟滚动及键盘操作。
+
+节点默认插槽、`suggestion-item`、过滤、懒加载以及 `disabled` / `leaf` 回调接收只读的 `QyCascaderNodeSnapshot`，不会泄漏 Element Plus Node 或组件实例。组件仅暴露 `focus()`、`blur()`、`open()`、`close()` 四个方法。
+
+```vue
+<QyCascader
+  v-model="value"
+  :options="options"
+  :props="{ emitPath: true, checkStrictly: true }"
+  filterable
+  placeholder="选择地区"
+/>
+```
+
+完整交互 playground 覆盖基础/路径、严格检查、多选折叠、过滤、懒加载、禁用、插槽、键盘、浮层和移动端 40px 触控目标。
+
+### `QyTree`
+
+`QyTree` 以 Element Plus `ElTree` 作为唯一的树结构、勾选/半选、键盘、懒加载和拖拽实现。`data` 始终是业务唯一数据权威；节点回调、事件、默认插槽和 `QyTreeRef.getNode()` 都返回当前只读 Qy 快照，不泄漏 Element Node、Store、组件实例或私有 DOM。
+
+```vue
+<QyTree
+  ref="treeRef"
+  :data="departments"
+  node-key="id"
+  show-checkbox
+  default-expand-all
+  :filter-node-method="(value, data, node) => node.label.includes(value)"
+  @check="(_, info) => console.log(info.checkedKeys, info.halfCheckedKeys)"
+/>
+```
+
+支持字段映射、展开/当前节点、联动和严格勾选、筛选、懒加载、拖拽、自定义节点插槽及本地键盘导航。公开引用仅包含筛选、当前节点、节点路径、勾选/半选读取与设置方法；不提供 `append`、`remove`、`insert` 或 `updateKeyChildren` 等内部数据修改方法。键值方法需要 `nodeKey`；未提供筛选函数时调用 `filter()` 会抛出 QyTree 自有错误。
+
 ### `QyFilePicker`
 
 单文件选择组件，支持点击选择、拖拽、替换、清空以及后缀和大小校验。
@@ -170,6 +270,23 @@ pnpm install --frozen-lockfile --ignore-scripts
 
 `disabled` 会设置 `aria-disabled="true"`、隐藏关闭按钮并抑制 `click` / `close`；非禁用状态下这两个事件各发出一次 `MouseEvent`。支持 `class`、`style`、`title`、`role`、`data-*`、`aria-*` 安全属性，不公开 `color`、`hit`、`disableTransitions` 或底层 Element Plus 实例。QyTag 不是按钮，不新增键盘按钮语义；需要动作语义时使用 `QyButton`。
 
+### `QyBadge`
+
+`QyBadge` 基于 Element Plus `ElBadge` 渲染只读徽标，不管理未读状态、通知或点击逻辑。支持数字与文字、数字上限、圆点、隐藏、零值策略、五种语义类型、自定义颜色、偏移以及徽标内部样式和类名。
+
+```vue
+<QyBadge :value="unreadCount" :max="99" type="danger">
+  <QyButton>消息</QyButton>
+</QyBadge>
+
+<QyBadge value="!" is-dot>
+  <span>待处理</span>
+  <template #content="{ value }">数量：{{ value }}</template>
+</QyBadge>
+```
+
+`value` 默认为空字符串，`max` 默认为 `99`，`type` 默认为 `danger`，`showZero` 默认为 `true`，`offset` 默认为 `[0, 0]`。上限只作用于数字，字符串原样显示；`content` 插槽收到经过圆点和上限规则处理后的只读 `{ value: string }`，组件公开的 `content` 也只有最终显示内容，不暴露 Element Plus 实例。根节点安全透传 `class`、`style`、`id`、`role`、`title`、`data-*` 和 `aria-*`，不声明事件、`v-model` 或尺寸参数。
+
 ### `QyTooltip`
 
 只读提示组件。默认插槽是唯一触发内容，不增加触发元素包装 DOM；`content` 插槽（content slot）优先于 `content` 属性。组件支持 hover / focus、完整 `placement`、`light` / `dark` effect、延迟、偏移和可收缩的 `maxWidth`。
@@ -205,6 +322,49 @@ pnpm install --frozen-lockfile --ignore-scripts
 
 默认值为 `trigger="click"`、`placement="bottom"`、`effect="light"`、`width=240`、`offset=12`、`showDelay=0`、`hideDelay=200`、`showArrow=true`、`disabled=false`。`open` 未传时组件内部管理状态，传入时通过 `v-model:open` 由父级回传决定状态；`update:open` 是状态意图，`open-change` / `open` / `close` 只在实际显隐转换时发出。唯一暴露的方法是 `close()`，不公开 Element Plus 实例、定位更新、`teleported`、`appendTo` 或 `popperOptions`。
 
+### `QySkeleton` 与 `QySkeletonItem`
+
+加载骨架组件基于 Element Plus 的 `ElSkeleton` / `ElSkeletonItem` 渲染。`loading` 由业务受控，加载期间使用 `template` 插槽，加载完成后使用默认插槽；支持 `animated`、`count`、`rows` 及数字或对象形式的 `throttle`。
+
+```vue
+<QySkeleton :loading="loading" animated :count="2">
+  <template #template>
+    <QySkeletonItem variant="rect" style="height: 120px" />
+  </template>
+  <div>真实内容</div>
+</QySkeleton>
+```
+
+`QySkeletonItem` 的 `variant` 支持 `p`、`text`、`h1`、`h3`、`caption`、`button`、`image`、`circle`、`rect`，默认值为 `text`。两者均支持 `class`、`style`、`role`、`title`、`data-*` 和 `aria-*`，不公开 Element Plus 实例。
+
+### `QyTabs` 与 `QyTabPane`
+
+`QyTabs` 使用 Element Plus 的 `ElTabs` / `ElTabPane` 处理渲染、焦点与键盘行为。`modelValue` 传入时保持受控；`defaultValue` 仅提供初始选择。`tab-change`、`tab-remove`、`tab-add` 与 `edit` 都是意图事件，不会改写业务页签数组、路由或 AdminShell 运行时。
+
+```vue
+<QyTabs v-model="current" editable @tab-add="addTab" @tab-remove="removeTab">
+  <QyTabPane label="概览" name="overview">概览内容</QyTabPane>
+  <QyTabPane label="详情" :name="2" lazy closable>详情内容</QyTabPane>
+</QyTabs>
+```
+
+支持 `type`（`'' | 'card' | 'border-card'）、`tabPosition`、`stretch`、`closable`、`addable`、`editable`、`beforeLeave` 和 `tabindex`。`QyTabPane` 支持 `label`、字符串或数字 `name`、`closable`、`disabled`、`lazy` 与 `label` 插槽。`tab-click` 的首个参数是冻结的 `QyTabPaneSnapshot`，只包含 `name`、`label`、`disabled`、`closable`、`lazy`、`active`、`index`，不会泄漏 Element Plus 页签上下文或实例。
+
+### `QyDescriptions` 与 `QyDescriptionsItem`
+
+`QyDescriptions` 使用 Element Plus 的 `ElDescriptions` / `ElDescriptionsItem` 处理描述列表的行列和单元格渲染。`QyDescriptionsItem` 是无 DOM 声明节点，父组件会递归处理直接子项、`v-if`、`v-for` 和 `template`/Fragment，再交给 Element Plus 完成 `span`、`rowspan`、宽度和对齐计算。
+
+```vue
+<QyDescriptions border :column="3" title="订单详情">
+  <template #extra><QyLink href="/orders">查看全部</QyLink></template>
+  <QyDescriptionsItem label="编号">SO-2026-001</QyDescriptionsItem>
+  <QyDescriptionsItem label="摘要" :span="2" :rowspan="2">复杂内容也可放入默认插槽。</QyDescriptionsItem>
+  <QyDescriptionsItem label="金额" align="right">¥12,800.00</QyDescriptionsItem>
+</QyDescriptions>
+```
+
+父级支持 `border`、`column`、`direction`、`size`（`'' | 'large' | 'default' | 'small'`）、`title`、`extra`、`labelWidth` 以及默认、`title`、`extra` 插槽；插槽优先于同名文本属性。描述项支持 `label`、`span`、`rowspan`、`width`、`minWidth`、`labelWidth`、`align`、`labelAlign`、`className`、`labelClassName` 以及默认和 `label` 插槽。组件只安全透传根节点的 `class`、`style`、`id`、`title`、`role`、`data-*`、`aria-*`，不公开事件、状态或 Element Plus 实例。
+
 ### `QyUpload`
 
 上传组件，支持：
@@ -677,18 +837,18 @@ options 模式物理复用 `QyCheckbox`；不提供 CheckboxButton、全选、in
 
 ### `QyTreeSelect`
 
-树选择组件，第一版定位为 `ElTreeSelect` 的轻量包装层，重点支持：
+树选择组件以 `ElTreeSelect` 作为唯一树、勾选、过滤、键盘和浮层实现，重点支持：
 
-- `options` 树数据直出
-- 兼容 `ElTreeSelect` 的 `data` 参数
-- `labelKey / valueKey / childrenKey / disabledKey` 字段映射
+- `data` 树数据直出，`options` 作为兼容入口；同时传入时 `data` 优先，节点与数组保持原始引用
+- `labelKey / valueKey / childrenKey / disabledKey` 快捷字段与 `props` 映射（显式 `props` 优先）
+- string、number、boolean、对象和多选数组的受控值；对象值必须配置稳定的 `nodeKey`
 - 单选 / 多选
 - `check-strictly`
 - `collapse-tags`
 - 默认弹层挂载策略
 - 保留原始节点字段，便于业务 slot 和后续透传使用
 
-`QyTreeSelect` 只处理树选择器的通用 UI 协议，不内置远程请求、权限过滤或业务接口格式化。业务接口返回字段不一致时，优先通过字段映射解决，避免每个页面先手写一遍 tree map。
+`QyTreeSelect` 只处理树选择器的通用 UI 协议，不内置远程请求、权限过滤或业务接口格式化。节点插槽、回调和事件只提供原始数据与安全快照；公开实例只有 `focus()` 和 `blur()`，不会暴露 Element Node、Store 或组件实例。
 
 为降低迁移成本，`QyTreeSelect` 的 `clearable`、`filterable`、`check-strictly`、`render-after-expand`、`fit-input-width` 等默认行为尽量跟随 `ElTreeSelect`。业务需要搜索、清空、父子不联动时应显式传参。
 
@@ -1222,6 +1382,114 @@ function handleSelect(item) {
 </template>
 ```
 
+### QyCollapse
+
+`QyCollapse` 与 `QyCollapseItem` 是 Element Plus 折叠面板的受控适配器。普通模式使用数组值，手风琴模式使用单个字符串或数字；`beforeCollapse` 同时拦截展开和收起。
+
+```vue
+<template>
+  <QyCollapse v-model="activeNames" :before-collapse="beforeCollapse">
+    <QyCollapseItem title="基本信息" name="base">内容</QyCollapseItem>
+    <QyCollapseItem title="数字名称" :name="2" />
+  </QyCollapse>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { QyCollapse, QyCollapseItem } from '@qynpm/ui'
+
+const activeNames = ref(['base'])
+function beforeCollapse(name) {
+  return name !== 'locked'
+}
+</script>
+```
+
+通过 `ref` 可读取只读的 `activeNames`，并调用 `setActiveNames(value)` 设置完整公共值；标题和图标插槽都接收 `{ isActive }`。
+
+### QyLink
+
+`QyLink` 基于 Element Plus `ElLink`，保留真实 `<a href>` 的浏览器焦点、Enter 激活和默认导航语义。支持六种语义类型、`always` / `never` / `hover` 下划线策略、禁用、原生链接地址和属性、图标属性及默认/图标插槽。
+
+```vue
+<QyLink
+  href="https://example.com"
+  target="_blank"
+  rel="noopener noreferrer"
+  type="primary"
+  underline="hover"
+>
+  打开外部文档
+  <template #icon>↗</template>
+</QyLink>
+```
+
+`disabled` 会移除有效 `href` 与 `target` 并抑制 `click`；非禁用点击只转发一次原生 `MouseEvent`。`type` 和 `underline` 未传时可继承 Element Plus ConfigProvider；布尔下划线仅作兼容，`true` 等同 `hover`、`false` 等同 `never`。不自动改写 `target` 或 `rel`，外部新窗口链接请显式提供 `rel="noopener noreferrer"`。无 href、只监听 `click` 的旧用法可以兼容，但新业务动作应使用 `QyButton`，路由导航应使用 RouterLink。
+
+### QyDivider
+
+`QyDivider` 基于 Element Plus `ElDivider`，支持水平/垂直方向、左中右标题位置和标准 CSS `border-style` 值。水平模式渲染默认插槽，垂直模式即使传入插槽也保持 Element Plus 行为而不渲染；消费者传入的 `width`、`height`、`margin` 等根样式会与 Element Plus 的边框 CSS 变量合并。
+
+```vue
+<QyDivider content-position="left" border-style="dashed">
+  分组标题
+</QyDivider>
+<QyDivider direction="vertical" :style="{ height: '130px', margin: '0 8px' }" />
+```
+
+根节点保留 `role="separator"`，只安全透传 `class`、`style`、`id`、`title`、`role`、`data-*` 和 `aria-*`；组件没有事件、尺寸参数、公开实例或额外布局规则。
+
+### QyProgress
+
+`QyProgress` 基于 Element Plus `ElProgress`，用于文件上传、批处理和任务进度的受控展示。支持 line / circle / dashboard 三种形态、percentage、四种 status、显示/隐藏/内部/自定义文字、固定/分段/函数颜色、线宽、端点、圆形画布宽度、不确定动画、条纹、流动条纹和默认插槽；不接管上传、轮询、暂停、恢复、重试或任务状态映射。
+
+```vue
+<QyProgress :percentage="progress" status="success" />
+<QyProgress type="circle" :percentage="progress" :color="colorStops" />
+<QyProgress :percentage="progress" :style="{ width: '720px', margin: '8px auto' }">
+  <template #default="{ percentage }">已完成 {{ percentage }}%</template>
+</QyProgress>
+```
+
+颜色、文字优先级、合法 percentage、图形和动画全部沿用 Element Plus；根级只安全透传 `class`、`style`、`id`、`role`、`title`、`data-*` 和 `aria-*`，未知属性、事件监听器、实例、DOM ref 和方法不对外暴露。文档演示位于 `src/docs/QyProgressDoc.vue`，API 表使用局部横向滚动，不产生页面级横向溢出。
+
+### QyAvatar
+
+`QyAvatar` 基于 Element Plus `ElAvatar`，用于用户头像及自定义头像内容展示。支持数字尺寸、`small` / `default` / `large` 命名尺寸、圆形和方形、图片 `src` / `srcSet` / `alt` / `fit`、图标、默认插槽和图片加载失败后的原生回退。
+
+```vue
+<QyAvatar :size="80" src="/avatar.png" alt="用户头像" />
+<QyAvatar size="large" shape="square" :icon="UserFilled" />
+<QyAvatar src="/missing.png" @error="handleAvatarError">
+  张三
+</QyAvatar>
+```
+
+图片加载、失败回退、图标与默认插槽优先级全部沿用 Element Plus；`error` 只转发标准图片 `Event`。根级只安全透传 `class`、`style`、`id`、`role`、`title`、`tabindex`、`data-*` 和 `aria-*`，未知属性、未声明事件、实例、DOM ref 和方法不对外暴露。QyAvatar 不接管上传、裁剪、预览、缓存、用户资料保存或头像组；文档演示位于 `src/docs/QyAvatarDoc.vue`，API 表使用局部横向滚动。
+
+### QyAlert
+
+`QyAlert` 基于 Element Plus `ElAlert`，用于页面模板中的常驻成功、警告、信息和错误提示。支持 `title`、`description`、五种 `type`、关闭入口、图标、居中和明暗效果，以及 `icon`、`title`、默认三个插槽；关闭时只触发无参数 `close` 事件，隐藏状态由 Element Plus 管理。
+
+```vue
+<QyAlert type="warning" title="请检查填写内容" description="修改后即可继续提交" @close="handleClose" />
+```
+
+根级只安全透传 `class`、`style`、`id`、`role`、`data-*` 和 `aria-*`；不透传原生 `title`、未知属性、原始鼠标事件或 Element Plus 实例。`QyAlert` 只负责常驻提示，不替代 `@qynpm/hooks` feedback runtime，也不改动 `QyFormSection` 的现有 tip 协议。
+
+### QyCard
+
+`QyCard` 基于 Element Plus `ElCard`，用于页面内部可独立识别的小型内容面板。支持 `header`、`footer`、`shadow`、`bodyStyle` 以及三个区域类名入口，原生转发 `header`、默认和 `footer` 插槽；插槽存在时由 Element Plus 优先于同名文本属性渲染。
+
+```vue
+<QyCard header="订单概览" shadow="hover" @click="handleCardClick">
+  <template #footer>更新于刚刚</template>
+  面板正文
+</QyCard>
+```
+
+根级只安全透传 `class`、`style`、`id`、`role`、`title`、`tabindex`、`data-*` 和 `aria-*`；`click` 只转发一次原生 `MouseEvent`，不把普通卡片自动改成按钮或链接。`QyCard` 不替代 `QyPage` 的页面语义根和页面节奏，也不替代 `QyFormSection` 的表单标题、说明、动作或折叠；标准列表页和完整页面不要再套一层卡片 workspace。
+
 ## 说明
 
 - 当前版本更适合体系内拆包复用
@@ -1269,3 +1537,21 @@ const ENABLE_LOCAL_QIYIN_DEBUG = true
 2. 清理消费项目的 `node_modules/.vite`
 3. 重新启动
 
+### QySteps 与 QyStep
+
+`QySteps` 和 `QyStep` 是 Element Plus `ElSteps` / `ElStep` 的安全公共入口。布局、父子注册、排序、状态计算和过渡全部由 Element Plus 负责；Qy 层只隔离公共属性、插槽、根级安全属性和 `change(newValue, oldValue)` 事件。
+
+```vue
+<QySteps :active="active" direction="horizontal" @change="handleChange">
+  <QyStep title="创建订单" description="填写订单信息" />
+  <QyStep title="确认信息">
+    <template #title><button type="button" @click="openOrder">查看订单</button></template>
+  </QyStep>
+  <QyStep title="完成" status="success" />
+</QySteps>
+```
+
+支持自动、像素和百分比 `space`，横向/纵向、居中、简洁模式、五种步骤状态以及受控 `active`。`QyStep` 支持 `title`、`description`、`icon`、显式 `status` 和 `icon` / `title` / `description` 插槽；插槽内容优先于同名属性。组件不提供 `update:active`、自动导航或步骤点击事件，业务跳转应在插槽中放置真实按钮或链接并自行处理。
+
+两个入口分别为 `@qynpm/ui/qy-steps` 与 `@qynpm/ui/qy-step`；根入口也导出 `QySteps`、`QyStep` 及其 Qy 自有类型。根级只安全透传 `class`、`style`、`id`、`role`、`title`、`data-*` 和 `aria-*`，未知属性、未声明事件、Element Plus 实例、内部注册对象和 DOM 方法不对外暴露。文档演示位于 `src/docs/QyStepsDoc.vue`，宽步骤条和 API 表使用局部横向滚动。
+