@qynpm/ui 1.0.32 → 1.0.34

package/README.md

@@ -43,16 +43,20 @@ import {
   QyCascader,
   QyTooltip,
   QyPopover,
-  QySkeleton,
-  QySkeletonItem,
-  QyLoading,
+  QyPopconfirm,
+  QySkeleton,
+  QySkeletonItem,
+  QyLoading,
   QyTabs,
   QyTabPane,
   QySteps,
   QyStep,
   QyIcon,
   QyIconPicker,
+  QyColorPicker,
+  QyWatermark,
   QyLink,
+  QyIframe,
   QyDivider,
   QyEmpty,
   QyScrollbar,
@@ -100,6 +104,7 @@ import QyActionBar from '@qynpm/ui/qy-action-bar'
 import QyButton from '@qynpm/ui/qy-button'
 import QyDropdown from '@qynpm/ui/qy-dropdown'
 import QyIconPicker from '@qynpm/ui/qy-icon-picker'
+import QyColorPicker from '@qynpm/ui/qy-color-picker'
 import QySearchInput from '@qynpm/ui/qy-search-input'
 import QyRecordQuoteSearch from '@qynpm/ui/qy-record-quote-search'
 import QyDialog from '@qynpm/ui/qy-dialog'
@@ -112,14 +117,17 @@ 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 QyLoading, { openQyLoading } from '@qynpm/ui/qy-loading'
+import QyPopconfirm from '@qynpm/ui/qy-popconfirm'
+import QyWatermark from '@qynpm/ui/qy-watermark'
+import QySkeleton from '@qynpm/ui/qy-skeleton'
+import QySkeletonItem from '@qynpm/ui/qy-skeleton-item'
+import QyLoading, { openQyLoading } from '@qynpm/ui/qy-loading'
 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 QyIframe from '@qynpm/ui/qy-iframe'
 import QyEmpty from '@qynpm/ui/qy-empty'
 import QyScrollbar from '@qynpm/ui/qy-scrollbar'
 import QyProgress from '@qynpm/ui/qy-progress'
@@ -327,7 +335,27 @@ 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`
+### `QyPopconfirm`
+
+二次确认浮层，提供 Qy-owned 的确认、取消、加载锁、关闭原因和焦点恢复语义。支持 `reference`、`title`、`icon` 插槽；`open` 可选受控，确认成功后的父级关闭会以 `close('external')` 记录，异步失败保持打开并允许重试。
+
+```vue
+<QyPopconfirm
+  title="确认删除？"
+  variant="danger"
+  confirm-type="danger"
+  :confirm-loading="saving"
+  :close-on-confirm="false"
+  @confirm="save"
+  @close="onClose"
+>
+  <template #reference><button type="button">删除</button></template>
+</QyPopconfirm>
+```
+
+事件为 `update:open`、`open-change`、`confirm`、`cancel` 和 `close(reason)`；关闭原因是 `confirm`、`cancel`、`outside`、`escape`、`trigger`、`external` 或 `disabled`。不公开 Element Plus 类型、实例、teleport 或 popper 参数。
+
+### `QySkeleton` 与 `QySkeletonItem`
 
 加载骨架组件基于 Element Plus 的 `ElSkeleton` / `ElSkeletonItem` 渲染。`loading` 由业务受控，加载期间使用 `template` 插槽，加载完成后使用默认插槽；支持 `animated`、`count`、`rows` 及数字或对象形式的 `throttle`。
 
@@ -340,78 +368,96 @@ pnpm install --frozen-lockfile --ignore-scripts
 </QySkeleton>
 ```
 
-`QySkeletonItem` 的 `variant` 支持 `p`、`text`、`h1`、`h3`、`caption`、`button`、`image`、`circle`、`rect`，默认值为 `text`。两者均支持 `class`、`style`、`role`、`title`、`data-*` 和 `aria-*`，不公开 Element Plus 实例。
-
-### `QyLoading`
-
-`QyLoading` 安装后注册 `v-qy-loading` 指令，并配置命令式 `openQyLoading` 服务。指令支持布尔值或 `{ active, text, maskColor, lockScroll }` 对象；服务未传 `target` 时覆盖 body，传入 HTMLElement 时只覆盖该容器。同一目标的多个句柄共享一个遮罩，最后一个句柄调用 `close()` 后才移除。
-
-```vue
-<script setup>
-import { ref } from 'vue'
-import { openQyLoading } from '@qynpm/ui/qy-loading'
-
-const loading = ref(false)
-const target = ref(null)
-
-function load() {
-  const handle = openQyLoading({ target: target.value, text: '加载中' })
-  // 请求完成后调用一次即可，重复 close 不会影响后续 loading。
-  handle.close()
-}
-</script>
-
-<template>
-  <div ref="target" v-qy-loading="{ active: loading, lockScroll: true }">
-    容器内容
-  </div>
-</template>
-```
-
-### `QyDrawer`
-
-`QyDrawer` 使用 Qy-owned props、事件和插槽封装抽屉容器，支持四方向、数字尺寸、遮罩/Escape 关闭原因、指定 `teleportTo` 容器、焦点恢复和重叠抽屉顶层响应。`header`、默认内容和 `footer` 插槽均接收 Qy-owned `close()`。
-
-```vue
-<script setup>
-import { ref } from 'vue'
-import QyDrawer from '@qynpm/ui/qy-drawer'
-
-const open = ref(false)
-</script>
-
-<template>
-  <button type="button" @click="open = true">查看订单</button>
-  <QyDrawer v-model="open" title="订单详情" placement="right" @close="open = false">
-    <p>抽屉内容</p>
-    <template #footer="{ close }">
-      <button type="button" @click="close">关闭</button>
-    </template>
-  </QyDrawer>
-</template>
-```
-
-### `QyResult`
-
-`QyResult` 统一展示成功、警告、信息、错误和 401/403/404/500 结果。它只负责结果视觉、标题、说明、图片和操作区，不负责路由、返回、刷新、重试、请求或状态管理；业务动作由消费者放入 `actions` 插槽。
-
-```vue
-<script setup>
-import QyResult from '@qynpm/ui/qy-result'
-</script>
-
-<template>
-  <QyResult status="404" title="页面不存在" description="请检查地址">
-    <template #actions>
-      <button type="button" @click="goHome">返回首页</button>
-    </template>
-  </QyResult>
-</template>
-```
-
-`visual` 插槽优先于 `image`，`image` 优先于状态内置视觉；`title` 同时作为结果标题和根节点原生 `title`，`description` 与 `actions` 也支持同名插槽覆盖属性内容。根入口与 `@qynpm/ui/qy-result` 均提供 Qy-owned 类型，不公开 Element Plus 类型、实例或事件。
-
-### `QyTabs` 与 `QyTabPane`
+`QySkeletonItem` 的 `variant` 支持 `p`、`text`、`h1`、`h3`、`caption`、`button`、`image`、`circle`、`rect`，默认值为 `text`。两者均支持 `class`、`style`、`role`、`title`、`data-*` 和 `aria-*`，不公开 Element Plus 实例。
+
+### `QyLoading`
+
+`QyLoading` 安装后注册 `v-qy-loading` 指令，并配置命令式 `openQyLoading` 服务。指令支持布尔值或 `{ active, text, maskColor, lockScroll }` 对象；服务未传 `target` 时覆盖 body，传入 HTMLElement 时只覆盖该容器。同一目标的多个句柄共享一个遮罩，最后一个句柄调用 `close()` 后才移除。
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { openQyLoading } from '@qynpm/ui/qy-loading'
+
+const loading = ref(false)
+const target = ref(null)
+
+function load() {
+  const handle = openQyLoading({ target: target.value, text: '加载中' })
+  // 请求完成后调用一次即可，重复 close 不会影响后续 loading。
+  handle.close()
+}
+</script>
+
+<template>
+  <div ref="target" v-qy-loading="{ active: loading, lockScroll: true }">
+    容器内容
+  </div>
+</template>
+```
+
+### `QyDrawer`
+
+`QyDrawer` 使用 Qy-owned props、事件和插槽封装抽屉容器，支持四方向、数字尺寸、遮罩/Escape 关闭原因、指定 `teleportTo` 容器、焦点恢复和重叠抽屉顶层响应。`header`、默认内容和 `footer` 插槽均接收 Qy-owned `close()`。
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import QyDrawer from '@qynpm/ui/qy-drawer'
+
+const open = ref(false)
+</script>
+
+<template>
+  <button type="button" @click="open = true">查看订单</button>
+  <QyDrawer v-model="open" title="订单详情" placement="right" @close="open = false">
+    <p>抽屉内容</p>
+    <template #footer="{ close }">
+      <button type="button" @click="close">关闭</button>
+    </template>
+  </QyDrawer>
+</template>
+```
+
+### `QyResult`
+
+`QyResult` 统一展示成功、警告、信息、错误和 401/403/404/500 结果。它只负责结果视觉、标题、说明、图片和操作区，不负责路由、返回、刷新、重试、请求或状态管理；业务动作由消费者放入 `actions` 插槽。
+
+```vue
+<script setup>
+import QyResult from '@qynpm/ui/qy-result'
+</script>
+
+<template>
+  <QyResult status="404" title="页面不存在" description="请检查地址">
+    <template #actions>
+      <button type="button" @click="goHome">返回首页</button>
+    </template>
+  </QyResult>
+</template>
+```
+
+`visual` 插槽优先于 `image`，`image` 优先于状态内置视觉；`title` 同时作为结果标题和根节点原生 `title`，`description` 与 `actions` 也支持同名插槽覆盖属性内容。根入口与 `@qynpm/ui/qy-result` 均提供 Qy-owned 类型，不公开 Element Plus 类型、实例或事件。
+
+### `QyWatermark`
+
+`QyWatermark` 在容器内提供 Qy-owned 的平铺文字或图片水印，图片优先且加载失败回退到 `content`；`content` 支持多行文字，`font`、`rotate`、`width`、`height`、`gap` 和 `offset` 控制水印单元。水印覆盖层不接收指针事件，默认插槽中的按钮、图片和选择操作仍由消费者处理。
+
+```vue
+<script setup>
+import QyWatermark from '@qynpm/ui/qy-watermark'
+</script>
+
+<template>
+  <QyWatermark :content="['客户名称', '订单编号']" :rotate="-18">
+    <div>订单内容</div>
+  </QyWatermark>
+</template>
+```
+
+公开 interface 只包含 `content`、`image`、`zIndex`、`rotate`、`width`、`height`、`gap`、`offset` 和 Qy-owned `font`，以及安全容器属性 `class`、`style`、`id`、`title`、`role`、`data-*`、`aria-*`；不公开 Element Plus props、实例、DOM、事件或 expose。完整演示位于 `src/docs/QyWatermarkDoc.vue`，入口为 `@qynpm/ui/qy-watermark`。
+
+### `QyTabs` 与 `QyTabPane`
 
 `QyTabs` 使用 Element Plus 的 `ElTabs` / `ElTabPane` 处理渲染、焦点与键盘行为。`modelValue` 传入时保持受控；`defaultValue` 仅提供初始选择。`tab-change`、`tab-remove`、`tab-add` 与 `edit` 都是意图事件，不会改写业务页签数组、路由或 AdminShell 运行时。
 
@@ -675,13 +721,28 @@ options 模式物理复用 `QyCheckbox`；不提供 CheckboxButton、全选、in
 
 ### `QyDialog`
 
-弹窗组件，支持：
+QyDialog 是受控弹窗组件，使用 Qy-owned 协议：
+
+- `open` / `update:open` / `open-change` 管理显隐
+- `confirm`、`cancel` 和 `close(reason)` 表达关闭意图；`reason` 为 `confirm | cancel | header | escape | overlay | external`
+- `confirm-loading` 在宿主异步业务期间锁定确认动作，业务成功后由宿主关闭
+- 默认 footer 由 `show-footer`、`show-confirm`、`show-cancel`、`confirm-text` 和 `cancel-text` 控制；自定义 `footer` 时不渲染默认按钮
+- 支持全屏切换、最小化、焦点恢复和顶层弹窗 Escape/遮罩仲裁
+
+```vue
+<QyDialog
+  :open="open"
+  title="订单确认"
+  :confirm-loading="saving"
+  :close-on-confirm="false"
+  @update:open="open = $event"
+  @confirm="save"
+>
+  内容区域
+</QyDialog>
+```
 
-- 默认头部/底部布局
-- 全屏切换
-- 最小化
-- 自定义 footer
-- 移动端自动全屏
+旧 `modelValue`、`layout`、`confirmProps`、`ok` 和 Element Plus attrs 不属于 QyDialog 公共面；过渡场景使用独立的 `@qynpm/qy-dialog-legacy` adapter，禁止新业务采用。
 
 ### `QyButton`
 
@@ -1275,7 +1336,7 @@ function handleSelect(item) {
 
 ```vue
 <template>
-<QyDialog title="标题" @confirm="handleConfirm">
+<QyDialog :open="open" title="标题" close-on-confirm @update:open="open = $event">
   内容区域
 </QyDialog>
 </template>
@@ -1500,6 +1561,26 @@ function beforeCollapse(name) {
 
 `disabled` 会移除有效 `href` 与 `target` 并抑制 `click`；非禁用点击只转发一次原生 `MouseEvent`。`type` 和 `underline` 未传时可继承 Element Plus ConfigProvider；布尔下划线仅作兼容，`true` 等同 `hover`、`false` 等同 `never`。不自动改写 `target` 或 `rel`，外部新窗口链接请显式提供 `rel="noopener noreferrer"`。无 href、只监听 `click` 的旧用法可以兼容，但新业务动作应使用 `QyButton`，路由导航应使用 RouterLink。
 
+### QyIframe
+
+`QyIframe` 用于在当前页面容器中嵌入受信任的独立页面。`src` 和无障碍 `title` 必填且去除首尾空白后必须非空；任一为空时不渲染 iframe。支持原生 `loading`、`sandbox`、`allow`、`referrerPolicy`、`allowFullscreen`，并发出无参数的 `load` 和 `error` 通知，不暴露原生 DOM Event。
+
+```vue
+<div style="height: 640px">
+  <QyIframe
+    src="/system/monitor"
+    title="系统监控"
+    :reload-key="reloadKey"
+    loading="lazy"
+    sandbox="allow-scripts allow-same-origin"
+    @load="handleLoad"
+    @error="handleError"
+  />
+</div>
+```
+
+`src` 变化时更新当前 iframe 地址；即使 `src` 相同，改变 `reloadKey`（`string | number`）也会重建 iframe 以触发受控 reload。组件默认填满父容器，不计算应用头部、标签栏或面包屑高度；宿主必须为容器提供明确高度。根节点只安全透传 `class`、`style`、`id`、`role`、`tabindex`、`data-*` 和 `aria-*`，未知属性及未声明监听器不对外透传。组件不模拟加载时长、不覆盖全局 resize 监听，也不负责登录会话、地址白名单或跨域通信。
+
 ### QyDivider
 
 `QyDivider` 基于 Element Plus `ElDivider`，支持水平/垂直方向、左中右标题位置和标准 CSS `border-style` 值。水平模式渲染默认插槽，垂直模式即使传入插槽也保持 Element Plus 行为而不渲染；消费者传入的 `width`、`height`、`margin` 等根样式会与 Element Plus 的边框 CSS 变量合并。
@@ -1700,6 +1781,23 @@ app.use(createQyIconPlugin(registry))
 
 公开事件为 `update:modelValue`、`change`、`clear`、`update:open` 和 `open-change`；实例只暴露 `focus()`、`blur()`、`open()`、`close()`。面板使用 listbox/option 语义，支持 Enter/Space 打开、方向键移动、Enter 选择和 Escape 回焦；触摸窄屏网格为两列且每个选项至少 40px。完整演示位于 `src/docs/QyIconPickerDoc.vue`，入口为 `@qynpm/ui/qy-icon-picker`。
 
+### QyColorPicker
+
+`QyColorPicker` 是受控颜色选择器。`format` 只接受 `hex` 或 `rgb`；未指定时，关闭透明度输出 hex，开启透明度输出 rgb/rgba。拖动和输入只触发 `active-change`，确认或清空才按 `update:modelValue`、`change`、`visible-change(false)` 顺序提交；Escape、点击外部和失焦会回滚到当前父级值且不发提交事件。
+
+```vue
+<QyColorPicker
+  v-model="brandColor"
+  format="rgb"
+  show-alpha
+  :predefine="['#409eff', '#67c23a']"
+  clearable
+  @active-change="previewColor = $event"
+/>
+```
+
+事件为 `update:modelValue`、`active-change`、`change` 和 `visible-change`，颜色 payload 为 `string | null`；组件不公开 Element Plus 类型、实例或 expose。完整演示位于 `src/docs/QyColorPickerDoc.vue`，入口为 `@qynpm/ui/qy-color-picker`。
+
 ### QyContainer、QyAside 与 QyMain
 
 三个组件是通用布局原语，入口分别为 `@qynpm/ui/qy-container`、`@qynpm/ui/qy-aside` 与 `@qynpm/ui/qy-main`；根入口也导出 `QyContainer`、`QyAside`、`QyMain` 及其 Qy 自有类型。V1 使用内部 Element Plus renderer，公共 wrapper 和声明文件不要求消费者感知 Element Plus。