@qynpm/ui 1.0.21 → 1.0.23

package/README.md

@@ -1,10 +1,10 @@
 # @qynpm/ui
 
-起印体系内抽离出来的 Vue 3 UI 组件包，当前主要包含基础输入组件、选择器组件、区块容器、底部操作栏，以及上传、弹窗、备注图文等通用能力。
-
-录单拆包的 transform 实际代码盘点见 [录单拆包迁移总览](../record-order-migration.md)。其中记录了 `QyImagePreview`、凭证上传模式、设计文件管理等后续 UI 缺口。`QyRichTextEditor` 属于录单追加信息的独立业务组件，不进入当前全局 UI 基础包。
-
-## 安装
+起印体系内抽离出来的 Vue 3 UI 组件包，当前主要包含基础输入组件、选择器组件、区块容器、底部操作栏，以及上传、弹窗、备注图文等通用能力。
+
+录单拆包的 transform 实际代码盘点见 [录单拆包迁移总览](../record-order-migration.md)。其中记录了 `QyImagePreview`、凭证上传模式、设计文件管理等后续 UI 缺口。`QyRichTextEditor` 属于录单追加信息的独立业务组件，不进入当前全局 UI 基础包。
+
+## 安装
 
 ```bash
 pnpm add @qynpm/ui
@@ -34,25 +34,27 @@ app.use(QyUI)
 也可以按需引入：
 
 ```ts
-import {
-  QyUpload,
-  QyImage,
-  QyImagePreview,
-  QyImageUpload,
+import {
+  QyUpload,
+  QyImage,
+  QyImagePreview,
+  QyImageUpload,
   QyDialog,
+  QyButton,
+  QyDropdown,
   QyRemarkImage,
   QyInput,
   QyInputNumber,
-  QyMoneyInput,
-  QyDatePicker,
-  QyCheckbox,
-  QyAutocomplete,
-  QyMenuActions,
-  QyTableColumnSettings,
-  QyRadioGroup,
-  QySelect,
-  QyTreeSelect,
-  QyRemoteSelect,
+  QyMoneyInput,
+  QyDatePicker,
+  QyCheckbox,
+  QyAutocomplete,
+  QyMenuActions,
+  QyTableColumnSettings,
+  QyRadioGroup,
+  QySelect,
+  QyTreeSelect,
+  QyRemoteSelect,
   QySelectionDialog,
   QyFormSection,
   QyActionBar,
@@ -66,30 +68,48 @@ import {
 ```ts
 import QyInput from '@qynpm/ui/qy-input'
 import QyMoneyInput from '@qynpm/ui/qy-money-input'
-import QyRadioGroup from '@qynpm/ui/qy-radio-group'
-import QySelect from '@qynpm/ui/qy-select'
-import QyTreeSelect from '@qynpm/ui/qy-tree-select'
-import QyRemoteSelect from '@qynpm/ui/qy-remote-select'
+import QyRadioGroup from '@qynpm/ui/qy-radio-group'
+import QySelect from '@qynpm/ui/qy-select'
+import QyTreeSelect from '@qynpm/ui/qy-tree-select'
+import QyRemoteSelect from '@qynpm/ui/qy-remote-select'
 import QySelectionDialog from '@qynpm/ui/qy-selection-dialog'
 import QyFormSection from '@qynpm/ui/qy-form-section'
 import QyActionBar from '@qynpm/ui/qy-action-bar'
+import QyButton from '@qynpm/ui/qy-button'
+import QyDropdown from '@qynpm/ui/qy-dropdown'
 import QySearchInput from '@qynpm/ui/qy-search-input'
 import QyRecordQuoteSearch from '@qynpm/ui/qy-record-quote-search'
-import QyDialog from '@qynpm/ui/qy-dialog'
-import QyUpload from '@qynpm/ui/qy-upload'
-import QyImage from '@qynpm/ui/qy-image'
-import QyImagePreview from '@qynpm/ui/qy-image-preview'
-import QyImageUpload from '@qynpm/ui/qy-image-upload'
+import QyDialog from '@qynpm/ui/qy-dialog'
+import QyUpload from '@qynpm/ui/qy-upload'
+import QyImage from '@qynpm/ui/qy-image'
+import QyImagePreview from '@qynpm/ui/qy-image-preview'
+import QyImageUpload from '@qynpm/ui/qy-image-upload'
 import QyRemarkImage from '@qynpm/ui/qy-remark-image'
-import QyInputNumber from '@qynpm/ui/qy-input-number'
-import QyDatePicker from '@qynpm/ui/qy-date-picker'
-import QyCheckbox from '@qynpm/ui/qy-checkbox'
-import QyAutocomplete from '@qynpm/ui/qy-autocomplete'
-import QyMenuActions from '@qynpm/ui/qy-menu-actions'
+import QyInputNumber from '@qynpm/ui/qy-input-number'
+import QyDatePicker from '@qynpm/ui/qy-date-picker'
+import QyCheckbox from '@qynpm/ui/qy-checkbox'
+import QyAutocomplete from '@qynpm/ui/qy-autocomplete'
+import QyMenuActions from '@qynpm/ui/qy-menu-actions'
 import QyTableColumnSettings from '@qynpm/ui/qy-table-column-settings'
 ```
 
-## 组件说明
+后台公共包必须通过 `@qynpm/ui/<子组件>` 使用 UI 能力。每个被后台公共包消费的子入口必须是自包含入口，直接组装对应组件并保留该子入口的命名导出，禁止再转发到 `../index.js` 加载 UI 根入口。这样可以保证发布包按需加载，也能让本地源码联调稳定解析到唯一物理模块。
+
+本地 file 依赖联调说明：单组件入口的 `package.json exports` 指向 `dist/qy-*/index.mjs` 和 `dist/qy-*/index.cjs`，而 `dist` 不提交到仓库。消费项目如果通过 `file:../qy-components/packages/ui` 引用本包，必须先在 `qy-components` 执行：
+
+```bash
+pnpm --filter @qynpm/ui build
+```
+
+然后在消费项目刷新 file 依赖安装视图，例如：
+
+```bash
+pnpm install --frozen-lockfile --ignore-scripts
+```
+
+不要依赖本机残留的 `packages/ui/dist`。如果后续希望免 build 联调，应在消费项目显式配置源码 alias，而不是把包 export 指向未发布源码。
+
+## 组件说明
 
 ### `QyUpload`
 
@@ -127,7 +147,7 @@ import QyTableColumnSettings from '@qynpm/ui/qy-table-column-settings'
 - `showText=false` 可隐藏文字备注区；如仍需粘贴入口，可开启 `showPasteInput`
 - `defaultValue` 仍保留给老页面做非受控初始化；新页面建议优先使用 `v-model`
 
-### `QyImageUpload`
+### `QyImageUpload`
 
 图片/文件字段上传组件，基于 `QyUpload` 的薄封装，适合商品图、设计图、成本附图、凭证图片集合、单视频字段等场景。
 
@@ -139,149 +159,149 @@ import QyTableColumnSettings from '@qynpm/ui/qy-table-column-settings'
 - 默认 `name="files"`
 - 默认 `showText=false`
 - 默认开启纯粘贴输入条
-- 默认 `size="128px"`
-- 支持 `supportVideo`、`fileType`、`fileSize`
-- 支持透传 `uploadRequest`，用于接入宿主项目上传请求
-
-凭证上传模式：
-
-- `mode="voucher"` 或 `voucher` 可启用凭证图片场景。
-- 默认允许 `jpg / jpeg / png / gif / bmp / webp`。
-- 默认 `limit=30`，保留纯粘贴入口，适合收款凭证、成本附图等旧 `CopyImgUpload` 使用点。
-- 暴露 `getFullPathList()` 和 `fullPathList`，兼容旧页面 `ref.fullPathList.join(',')` 的读值方式。
-- 上传成功时额外触发 `updateImg(url)`，兼容旧 `CopyImgUpload` 的成功通知语义。
-
-`QyImageUpload` 不保留旧 `imageUpload` 的 `successUpload(fileList)` 回调。旧页面迁移时优先改为 `v-model`；确实依赖旧 `CopyImgUpload` 读值方式的页面，可先用凭证模式的 `fullPathList / getFullPathList()` 过渡。
-
-### `QyImage`
-
-图片展示组件，计划承接旧 `packages/qiyin/components/Image`，并作为 `@qynpm/table-schema` 的 `image` 列渲染底座。
-
-这是后续替代旧 `useCol` 的前置组件。旧 `useCol/render/imageRender.vue` 的表格列渲染不应该在 `@qynpm/table-schema` 内重复维护一套通用图片组件，而应组合 `QyImage`。
-
-必须完整覆盖旧能力：
-
-- `src` 图片地址。
-- `width / height / size` 缩略图尺寸。
-- `fit` 图片填充方式，透传 `ElImage`。
-- 加载中状态。
-- 加载失败状态。
-- `error` 事件。
-- `placeholder` 空图占位。
-- `compressor` 压缩缩略图参数。
-- 旧域名兼容：`ys.diansan.com` 地址迁移为 `https://admin.qiyinbz.com`。
-- 旧缩略图参数：点三域名使用 `?small=true&style=image/resize,h_{h},w_{w}`，其他域名使用 `?w={w}`。
-- 失败兜底：缩略图请求失败后请求原图 blob，并用浏览器 canvas 压缩成 dataURL 展示。
-- `preview / previewList / initialIndex` 图片预览。
-
-失败兜底属于旧公共图片组件能力，不是录单业务逻辑。当前实现不新增 `compressorjs`，使用浏览器原生 `fetch + blob + canvas` 完成压缩；如果后续发现必须完全等价旧 `compressorjs` 的压缩细节，再单独评估是否新增依赖。
-
-建议新组件 API：
-
-```ts
-type QyImageProps = {
-  src?: string
-  width?: number | string
-  height?: number | string
-  size?: number
-  fit?: 'fill' | 'contain' | 'cover' | 'none' | 'scale-down'
-  placeholder?: boolean
-  compressor?: boolean | {
-    w?: number
-    h?: number
-    q?: number
-  }
-  preview?: boolean
-  previewList?: string[]
-  initialIndex?: number
-}
-```
-
-表格 image 列后续直接组合 `QyImage` 和 `QyImagePreview`，不要在 `@qynpm/table-schema` 里复制一份通用图片组件。
-
-已完成：
-
-- 创建 `@qiyin/UI/qy-image` 入口。
-- 创建 `src/docs/QyImageDoc.vue` playground 文档。
-- 补 `index.js / index.d.ts / package.json exports / files`。
-- 补构建入口，确保 `@qynpm/ui/qy-image` 可按需引入。
-- 补失败压缩兜底，不新增 `compressorjs`。
-- 补 `preview` 接入，可点击打开 `QyImagePreview`。
-
-### `QyImagePreview`
-
-图片预览组件，承接旧 `useCol/render/imageRender.vue` 中动态创建 `ElImageViewer` 的逻辑。
-
-需要支持：
-
-- `urlList` 图片列表。
-- `initialIndex` 初始预览索引。
-- 打开时控制 `body.style.overflow = 'hidden'`。
-- 关闭时恢复 body 滚动并销毁实例。
-- 支持直接作为组件使用，也支持函数式调用，例如 `openQyImagePreview({ urlList, initialIndex })`。
-
-该能力是 `@qynpm/table-schema` 完整迁移 image 列的前置能力。table-schema 不应该长期维护一份独立图片预览逻辑。
-
-### `QyCheckbox`
-
-复选框基础组件，基于 `ElCheckbox` 做薄封装，统一 `v-model`、`change`、`focus`、`blur` 事件和单组件入口。
-
-主要用于普通表单复选框，以及 `@qynpm/table-schema` 的 `edit-checkbox` 渲染器底座。
-
-### `QyAutocomplete`
-
-自动完成输入基础组件，基于 `ElAutocomplete` 做薄封装，支持本地 `options` 过滤和 Element Plus 原生 `fetchSuggestions` 透传。
-
-默认协议：
-
-- `v-model` 绑定输入值。
-- `options` 支持 `{ value }` 列表，也支持通过 `valueKey` 映射其它字段。
-- 默认按 `option.value.includes(query)` 过滤。
-- 支持 `select / change / input / clear / focus / blur` 事件。
-
-该组件作为 `@qynpm/table-schema` 的 `edit-autocomplete` 渲染器底座，表格 row 写回逻辑仍留在 table-schema。
-
-### `QyMenuActions`
-
-表格行操作 UI 底座，承接旧 `useCol/render/menu.vue` 的通用展示能力。
-
-支持：
-
-- `inline` 横向操作模式。
-- `popover` 更多操作模式。
-- `actions` 列表。
-- `hidden / disabled / loading` 支持布尔值或按行上下文计算。
-- `type` 控制默认、主色、成功、警告、危险操作色。
-- `confirmMethod(action, context)` 由宿主注入确认逻辑。
-- `action(action, context)` 只在可执行且确认通过后触发。
-
-`QyMenuActions` 不内置权限、路由、缓存、弹窗实例、消息提示，也不直接执行业务方法。权限过滤和业务执行应留在 `@qynpm/table-schema` adapter 或宿主页面。
-
-### `QyTableColumnSettings`
-
-表格列设置 UI 底座，承接旧 `useCol/render/setup.vue` 的通用 UI 能力。
-
-支持：
-
-- 列列表展示。
-- 当前选中列。
-- 置顶、置底、上移、下移。
-- 固定左侧、固定右侧、取消固定。
-- 列宽编辑。
-- 显隐开关。
-- 恢复默认。
-- 删除缓存。
-
-业务缓存读写仍由 `@qynpm/table-schema` 的 settings adapter 或宿主 adapter 负责，UI 组件只负责展示和编辑 settings。
-
-### 编辑类基础组件（待评估）
-
-旧 `useCol` 的 `edit-input / edit-autocomplete` 有一套“展示态 -> 点击编辑 -> blur/enter 写回”的通用交互。后续有两种选择：
-
-- 如果表格外也需要该交互，补 `QyInlineEditInput` 和 `QyAutocompleteInput`。
-- 如果只服务表格列，先放在 `@qynpm/table-schema` renderer 内部，避免 UI 包过早扩大。
-
-### `QyDialog`
+- 默认 `size="128px"`
+- 支持 `supportVideo`、`fileType`、`fileSize`
+- 支持透传 `uploadRequest`，用于接入宿主项目上传请求
+
+凭证上传模式：
+
+- `mode="voucher"` 或 `voucher` 可启用凭证图片场景。
+- 默认允许 `jpg / jpeg / png / gif / bmp / webp`。
+- 默认 `limit=30`，保留纯粘贴入口，适合收款凭证、成本附图等旧 `CopyImgUpload` 使用点。
+- 暴露 `getFullPathList()` 和 `fullPathList`，兼容旧页面 `ref.fullPathList.join(',')` 的读值方式。
+- 上传成功时额外触发 `updateImg(url)`，兼容旧 `CopyImgUpload` 的成功通知语义。
+
+`QyImageUpload` 不保留旧 `imageUpload` 的 `successUpload(fileList)` 回调。旧页面迁移时优先改为 `v-model`；确实依赖旧 `CopyImgUpload` 读值方式的页面，可先用凭证模式的 `fullPathList / getFullPathList()` 过渡。
+
+### `QyImage`
+
+图片展示组件，计划承接旧 `packages/qiyin/components/Image`，并作为 `@qynpm/table-schema` 的 `image` 列渲染底座。
+
+这是后续替代旧 `useCol` 的前置组件。旧 `useCol/render/imageRender.vue` 的表格列渲染不应该在 `@qynpm/table-schema` 内重复维护一套通用图片组件，而应组合 `QyImage`。
+
+必须完整覆盖旧能力：
+
+- `src` 图片地址。
+- `width / height / size` 缩略图尺寸。
+- `fit` 图片填充方式，透传 `ElImage`。
+- 加载中状态。
+- 加载失败状态。
+- `error` 事件。
+- `placeholder` 空图占位。
+- `compressor` 压缩缩略图参数。
+- 旧域名兼容：`ys.diansan.com` 地址迁移为 `https://admin.qiyinbz.com`。
+- 旧缩略图参数：点三域名使用 `?small=true&style=image/resize,h_{h},w_{w}`，其他域名使用 `?w={w}`。
+- 失败兜底：缩略图请求失败后请求原图 blob，并用浏览器 canvas 压缩成 dataURL 展示。
+- `preview / previewList / initialIndex` 图片预览。
+
+失败兜底属于旧公共图片组件能力，不是录单业务逻辑。当前实现不新增 `compressorjs`，使用浏览器原生 `fetch + blob + canvas` 完成压缩；如果后续发现必须完全等价旧 `compressorjs` 的压缩细节，再单独评估是否新增依赖。
+
+建议新组件 API：
+
+```ts
+type QyImageProps = {
+  src?: string
+  width?: number | string
+  height?: number | string
+  size?: number
+  fit?: 'fill' | 'contain' | 'cover' | 'none' | 'scale-down'
+  placeholder?: boolean
+  compressor?: boolean | {
+    w?: number
+    h?: number
+    q?: number
+  }
+  preview?: boolean
+  previewList?: string[]
+  initialIndex?: number
+}
+```
+
+表格 image 列后续直接组合 `QyImage` 和 `QyImagePreview`，不要在 `@qynpm/table-schema` 里复制一份通用图片组件。
+
+已完成：
+
+- 创建 `@qiyin/UI/qy-image` 入口。
+- 创建 `src/docs/QyImageDoc.vue` playground 文档。
+- 补 `index.js / index.d.ts / package.json exports / files`。
+- 补构建入口，确保 `@qynpm/ui/qy-image` 可按需引入。
+- 补失败压缩兜底，不新增 `compressorjs`。
+- 补 `preview` 接入，可点击打开 `QyImagePreview`。
+
+### `QyImagePreview`
+
+图片预览组件，承接旧 `useCol/render/imageRender.vue` 中动态创建 `ElImageViewer` 的逻辑。
+
+需要支持：
+
+- `urlList` 图片列表。
+- `initialIndex` 初始预览索引。
+- 打开时控制 `body.style.overflow = 'hidden'`。
+- 关闭时恢复 body 滚动并销毁实例。
+- 支持直接作为组件使用，也支持函数式调用，例如 `openQyImagePreview({ urlList, initialIndex })`。
+
+该能力是 `@qynpm/table-schema` 完整迁移 image 列的前置能力。table-schema 不应该长期维护一份独立图片预览逻辑。
+
+### `QyCheckbox`
+
+复选框基础组件，基于 `ElCheckbox` 做薄封装，统一 `v-model`、`change`、`focus`、`blur` 事件和单组件入口。
+
+主要用于普通表单复选框，以及 `@qynpm/table-schema` 的 `edit-checkbox` 渲染器底座。
+
+### `QyAutocomplete`
+
+自动完成输入基础组件，基于 `ElAutocomplete` 做薄封装，支持本地 `options` 过滤和 Element Plus 原生 `fetchSuggestions` 透传。
+
+默认协议：
+
+- `v-model` 绑定输入值。
+- `options` 支持 `{ value }` 列表，也支持通过 `valueKey` 映射其它字段。
+- 默认按 `option.value.includes(query)` 过滤。
+- 支持 `select / change / input / clear / focus / blur` 事件。
+
+该组件作为 `@qynpm/table-schema` 的 `edit-autocomplete` 渲染器底座，表格 row 写回逻辑仍留在 table-schema。
+
+### `QyMenuActions`
+
+表格行操作 UI 底座，承接旧 `useCol/render/menu.vue` 的通用展示能力。
+
+支持：
+
+- `inline` 横向操作模式。
+- `popover` 更多操作模式。
+- `actions` 列表。
+- `hidden / disabled / loading` 支持布尔值或按行上下文计算。
+- `type` 控制默认、主色、成功、警告、危险操作色。
+- `confirmMethod(action, context)` 由宿主注入确认逻辑。
+- `action(action, context)` 只在可执行且确认通过后触发。
+
+`QyMenuActions` 不内置权限、路由、缓存、弹窗实例、消息提示，也不直接执行业务方法。权限过滤和业务执行应留在 `@qynpm/table-schema` adapter 或宿主页面。
+
+### `QyTableColumnSettings`
+
+表格列设置 UI 底座，承接旧 `useCol/render/setup.vue` 的通用 UI 能力。
+
+支持：
+
+- 列列表展示。
+- 当前选中列。
+- 置顶、置底、上移、下移。
+- 固定左侧、固定右侧、取消固定。
+- 列宽编辑。
+- 显隐开关。
+- 恢复默认。
+- 删除缓存。
+
+业务缓存读写仍由 `@qynpm/table-schema` 的 settings adapter 或宿主 adapter 负责，UI 组件只负责展示和编辑 settings。
+
+### 编辑类基础组件（待评估）
+
+旧 `useCol` 的 `edit-input / edit-autocomplete` 有一套“展示态 -> 点击编辑 -> blur/enter 写回”的通用交互。后续有两种选择：
+
+- 如果表格外也需要该交互，补 `QyInlineEditInput` 和 `QyAutocompleteInput`。
+- 如果只服务表格列，先放在 `@qynpm/table-schema` renderer 内部，避免 UI 包过早扩大。
+
+### `QyDialog`
 
 弹窗组件，支持：
 
@@ -291,7 +311,42 @@ type QyImageProps = {
 - 自定义 footer
 - 移动端自动全屏
 
-### `QySelectionDialog`
+### `QyButton`
+
+后台按钮统一入口，后续 AdminShell 和业务页按钮迁移时优先使用该组件，而不是直接写原生 `button` 或分散使用 `ElButton`。
+
+核心能力：
+
+- `type="default | primary | success | warning | danger | text | ghost | link"` 控制视觉类型。
+- `size="sm | md | lg"` 控制高度、padding、gap、字号和图标尺寸，默认 `md`。
+- `disabled` 和 `loading` 都会阻止 `click` 事件；`loading` 会展示内置 loading 状态。
+- `active` 用于顶部当前系统、tabs 当前操作等选中态。
+- `block` 撑满父容器，`round` 显式开启胶囊圆角；默认后台圆角保持紧凑。
+- `native-type="button | submit | reset"` 控制原生按钮类型，默认 `button`。
+- `prefix-icon / suffix-icon` 只支持 Vue 组件图标；也可以通过 `prefix / suffix` 插槽传入前后图标；`icon-only` 必须提供 `aria-label` 或 `title`。
+
+样式 token：
+
+- 尺寸类：`--qy-button-sm-height`、`--qy-button-md-height`、`--qy-button-lg-height`、`--qy-button-*-padding-x`、`--qy-button-*-gap`、`--qy-button-*-font-size`、`--qy-button-*-icon-size`。
+- 状态类：`--qy-button-default-*`、`--qy-button-primary-*`、`--qy-button-success-*`、`--qy-button-warning-*`、`--qy-button-danger-*`、`--qy-button-disabled-*`、`--qy-button-focus-ring`。
+- token 默认从 Element Plus 的 `--el-*` 设计变量取值，宿主可覆盖 `--qy-button-*` 做主题适配。
+
+### `QyDropdown`
+
+后台下拉菜单统一入口，后续 AdminShell、工具栏和更多操作菜单迁移时优先使用该组件，而不是在业务页面散落手写原生 dropdown DOM。
+
+核心能力：
+
+- `items` 支持 `{ key, label, icon, disabled, danger, hidden, divided, active, title }`。
+- `hidden` 项不渲染，`disabled` 项不触发 `select`。
+- `danger` 和 `active` 项会输出稳定的 `is-danger` / `is-active` class，以及 `data-danger` / `data-active` 标记。
+- `trigger="click"` 为默认触发方式，预留 `contextmenu`。
+- `v-model` / `model-value` 支持受控打开状态；受控模式下只触发 `update:modelValue` 和 `open-change`，不私自决定最终打开状态。
+- `close-on-select=false` 可在选择后保持面板打开。
+- `panel-width` / `width` 和 `max-height` 控制面板尺寸。
+- `trigger`、`item`、`header`、`footer`、`empty` 插槽用于业务定制展示；`trigger` 插槽应把 `attrs` 绑定到实际触发按钮上。
+
+### `QySelectionDialog`
 
 数据选择弹窗底座，参考老 `@qiyin/components/Dialog` 的核心能力迁移，但不内置任何 ERP 接口或权限逻辑。
 
@@ -316,11 +371,11 @@ type QyImageProps = {
 - `side`、`search`、`toolbar` 插槽扩展业务区域
 - Element Plus 原生分页
 
-`QySelectionDialog` 只解决“怎么选”，不解决“选什么”。业务接口、字段映射、权限判断应放在宿主项目 wrapper 中。
-
-迁移业务选择器前，建议先阅读：
-
-- [选择弹窗迁移规范](./选择弹窗迁移规范.md)
+`QySelectionDialog` 只解决“怎么选”，不解决“选什么”。业务接口、字段映射、权限判断应放在宿主项目 wrapper 中。
+
+迁移业务选择器前，建议先阅读：
+
+- [选择弹窗迁移规范](./选择弹窗迁移规范.md)
 
 选择状态采用“弹窗草稿 + 确认提交”协议：
 
@@ -346,11 +401,11 @@ type QyImageProps = {
 - `defaultValue` 解析 `[url:图片地址]备注文本`
 - `defaultImage` 独立图片默认值
 - `change(value, imageUrl)` 输出完整备注值和图片地址
-- 粘贴图片上传
-- 悬浮预览和删除图片
-- `uploadRequest` 自定义上传请求
-- `layout="select-prefix"` 可把一个基础下拉值合并成输入前缀，用于“下拉值 + 图文备注”这类旧协议字段
-- `deleteImage()` / `clearContent()` / `getValue()` 暴露方法，兼容旧表单重置和读取协议值
+- 粘贴图片上传
+- 悬浮预览和删除图片
+- `uploadRequest` 自定义上传请求
+- `layout="select-prefix"` 可把一个基础下拉值合并成输入前缀，用于“下拉值 + 图文备注”这类旧协议字段
+- `deleteImage()` / `clearContent()` / `getValue()` 暴露方法，兼容旧表单重置和读取协议值
 
 默认上传会使用：
 
@@ -358,24 +413,24 @@ type QyImageProps = {
 - `tokenKey`，默认 `Admin-Token`
 - `uploadName`，默认 `files`
 
-如果宿主项目有统一 request、baseURL、鉴权、错误处理或登录失效处理，应优先传入 `uploadRequest`，不要在组件内部写死项目请求实现。
-
-组合下拉输入：
-
-```vue
-<QyRemarkImage
-  layout="select-prefix"
-  :select-value="postageValue"
-  :select-options="[
-    { label: '包邮', value: '包邮' },
-    { label: '不包邮', value: '不包邮' }
-  ]"
-  placeholder="备注 / 粘贴图片"
-  type="text"
-  @update:select-value="postageValue = $event"
-  @change="handleRemarkChange"
-/>
-```
+如果宿主项目有统一 request、baseURL、鉴权、错误处理或登录失效处理，应优先传入 `uploadRequest`，不要在组件内部写死项目请求实现。
+
+组合下拉输入：
+
+```vue
+<QyRemarkImage
+  layout="select-prefix"
+  :select-value="postageValue"
+  :select-options="[
+    { label: '包邮', value: '包邮' },
+    { label: '不包邮', value: '不包邮' }
+  ]"
+  placeholder="备注 / 粘贴图片"
+  type="text"
+  @update:select-value="postageValue = $event"
+  @change="handleRemarkChange"
+/>
+```
 
 ### `QyInput`
 
@@ -447,35 +502,35 @@ type QyImageProps = {
 - `value`：映射后的选项值
 - `disabled`：是否禁用
 
-### `QySelect`
-
-选择器组件，第一版定位为 `ElSelect` 的轻量包装层，重点支持：
+### `QySelect`
+
+选择器组件，第一版定位为 `ElSelect` 的轻量包装层，重点支持：
 
 - `options` 直出
 - `labelKey / valueKey / disabledKey` 映射
 - 单选 / 多选
 - `collapse-tags`
-- 默认弹层挂载策略
-- 保留原生 slot 扩展
-
-### `QyTreeSelect`
-
-树选择组件，第一版定位为 `ElTreeSelect` 的轻量包装层，重点支持：
-
-- `options` 树数据直出
-- 兼容 `ElTreeSelect` 的 `data` 参数
-- `labelKey / valueKey / childrenKey / disabledKey` 字段映射
-- 单选 / 多选
-- `check-strictly`
-- `collapse-tags`
-- 默认弹层挂载策略
-- 保留原始节点字段，便于业务 slot 和后续透传使用
-
-`QyTreeSelect` 只处理树选择器的通用 UI 协议，不内置远程请求、权限过滤或业务接口格式化。业务接口返回字段不一致时，优先通过字段映射解决，避免每个页面先手写一遍 tree map。
-
-为降低迁移成本，`QyTreeSelect` 的 `clearable`、`filterable`、`check-strictly`、`render-after-expand`、`fit-input-width` 等默认行为尽量跟随 `ElTreeSelect`。业务需要搜索、清空、父子不联动时应显式传参。
-
-### `QyRemoteSelect`
+- 默认弹层挂载策略
+- 保留原生 slot 扩展
+
+### `QyTreeSelect`
+
+树选择组件，第一版定位为 `ElTreeSelect` 的轻量包装层，重点支持：
+
+- `options` 树数据直出
+- 兼容 `ElTreeSelect` 的 `data` 参数
+- `labelKey / valueKey / childrenKey / disabledKey` 字段映射
+- 单选 / 多选
+- `check-strictly`
+- `collapse-tags`
+- 默认弹层挂载策略
+- 保留原始节点字段，便于业务 slot 和后续透传使用
+
+`QyTreeSelect` 只处理树选择器的通用 UI 协议，不内置远程请求、权限过滤或业务接口格式化。业务接口返回字段不一致时，优先通过字段映射解决，避免每个页面先手写一遍 tree map。
+
+为降低迁移成本，`QyTreeSelect` 的 `clearable`、`filterable`、`check-strictly`、`render-after-expand`、`fit-input-width` 等默认行为尽量跟随 `ElTreeSelect`。业务需要搜索、清空、父子不联动时应显式传参。
+
+### `QyRemoteSelect`
 
 远程选择器组件，基于 `QySelect` 组合实现，重点支持：
 
@@ -576,7 +631,7 @@ type QyImageProps = {
 </template>
 ```
 
-### QyImageUpload
+### QyImageUpload
 
 单图字段：
 
@@ -587,37 +642,37 @@ type QyImageProps = {
     api="/permission-api/common/uploads"
     :file-size="5"
   />
-</template>
-```
-
-### QyImage
-
-```vue
-<template>
-  <QyImage
-    src="https://img.example.com/a.jpg"
-    :size="48"
-    fit="cover"
-    preview
-    :compressor="{ w: 200, h: 200, q: 50 }"
-  />
-</template>
-```
-
-函数式预览：
-
-```ts
-import { openQyImagePreview } from '@qynpm/ui'
-
-openQyImagePreview({
-  urlList: ['https://img.example.com/a.jpg'],
-  initialIndex: 0
-})
-```
+</template>
+```
 
-多图字段：
-
-```vue
+### QyImage
+
+```vue
+<template>
+  <QyImage
+    src="https://img.example.com/a.jpg"
+    :size="48"
+    fit="cover"
+    preview
+    :compressor="{ w: 200, h: 200, q: 50 }"
+  />
+</template>
+```
+
+函数式预览：
+
+```ts
+import { openQyImagePreview } from '@qynpm/ui'
+
+openQyImagePreview({
+  urlList: ['https://img.example.com/a.jpg'],
+  initialIndex: 0
+})
+```
+
+多图字段：
+
+```vue
 <template>
   <QyImageUpload
     v-model="payImages"
@@ -625,38 +680,38 @@ openQyImagePreview({
     multiple
     :limit="9"
   />
-</template>
-```
-
-凭证上传模式，迁移旧 `CopyImgUpload`：
-
-```vue
-<template>
-  <QyImageUpload
-    ref="payImgRef"
-    v-model="payImages"
-    mode="voucher"
-    api="/permission-api/common/uploads"
-    :multiple="false"
-    size="100px"
-  />
-</template>
-
-<script setup>
-import { ref } from 'vue'
-
-const payImages = ref('')
-const payImgRef = ref(null)
-
-function getForms() {
-  return {
-    erpOrderPayImg: payImgRef.value.getFullPathList().join(',')
-  }
-}
-</script>
-```
-
-接入宿主项目上传请求：
+</template>
+```
+
+凭证上传模式，迁移旧 `CopyImgUpload`：
+
+```vue
+<template>
+  <QyImageUpload
+    ref="payImgRef"
+    v-model="payImages"
+    mode="voucher"
+    api="/permission-api/common/uploads"
+    :multiple="false"
+    size="100px"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const payImages = ref('')
+const payImgRef = ref(null)
+
+function getForms() {
+  return {
+    erpOrderPayImg: payImgRef.value.getFullPathList().join(',')
+  }
+}
+</script>
+```
+
+接入宿主项目上传请求：
 
 ```vue
 <template>
@@ -681,9 +736,9 @@ async function uploadFile({ formData }) {
 </script>
 ```
 
-### QyRemarkImage
-
-默认上传：
+### QyRemarkImage
+
+默认上传：
 
 ```vue
 <template>
@@ -729,56 +784,100 @@ function handleRemarkChange(value: string, imageUrl?: string) {
   remark.value = value
   remarkImage.value = imageUrl || ''
 }
-</script>
-```
-
-### QyMenuActions
-
-```vue
-<template>
-  <QyMenuActions
-    :row="row"
-    :row-index="0"
-    :actions="actions"
-    :confirm-method="confirmAction"
-    @action="handleAction"
-  />
-</template>
-
-<script setup lang="ts">
-const row = { id: 1, status: 'draft' }
-const actions = [
-  { key: 'edit', label: '编辑' },
-  { key: 'delete', label: '删除', type: 'danger', confirm: true }
-]
-
-function confirmAction(action, context) {
-  return window.confirm(`确认${action.label}？`)
-}
-
-function handleAction(action, context) {
-  // 业务执行、消息提示和权限判断留在宿主或 table-schema adapter。
-}
-</script>
-```
-
-### QyTableColumnSettings
-
-```vue
-<template>
-  <QyTableColumnSettings
-    v-model="visible"
-    :settings="settings"
-    :default-settings="defaultSettings"
-    @confirm="saveSettings"
-    @delete-cache="removeSettingsCache"
-  />
-</template>
-```
-
-### QyDialog
-
-```vue
+</script>
+```
+
+### QyMenuActions
+
+```vue
+<template>
+  <QyMenuActions
+    :row="row"
+    :row-index="0"
+    :actions="actions"
+    :confirm-method="confirmAction"
+    @action="handleAction"
+  />
+</template>
+
+<script setup lang="ts">
+const row = { id: 1, status: 'draft' }
+const actions = [
+  { key: 'edit', label: '编辑' },
+  { key: 'delete', label: '删除', type: 'danger', confirm: true }
+]
+
+function confirmAction(action, context) {
+  return window.confirm(`确认${action.label}？`)
+}
+
+function handleAction(action, context) {
+  // 业务执行、消息提示和权限判断留在宿主或 table-schema adapter。
+}
+</script>
+```
+
+### QyTableColumnSettings
+
+```vue
+<template>
+  <QyTableColumnSettings
+    v-model="visible"
+    :settings="settings"
+    :default-settings="defaultSettings"
+    @confirm="saveSettings"
+    @delete-cache="removeSettingsCache"
+  />
+</template>
+```
+
+### QyButton
+
+```vue
+<template>
+  <QyButton type="primary" :prefix-icon="Search" @click="handleSearch">
+    查询
+  </QyButton>
+  <QyButton loading>保存中</QyButton>
+  <QyButton icon-only :prefix-icon="Refresh" aria-label="刷新当前页" />
+</template>
+```
+
+### QyDropdown
+
+```vue
+<template>
+  <QyDropdown
+    :items="items"
+    panel-width="168px"
+    @select="handleSelect"
+  >
+    <template #trigger="{ attrs }">
+      <QyButton v-bind="attrs">
+        更多
+      </QyButton>
+    </template>
+  </QyDropdown>
+</template>
+
+<script setup lang="ts">
+import QyButton from '@qynpm/ui/qy-button'
+import QyDropdown from '@qynpm/ui/qy-dropdown'
+
+const items = [
+  { key: 'profile', label: '个人信息' },
+  { key: 'logout', label: '退出登录', danger: true, divided: true }
+]
+
+function handleSelect(item) {
+  // 业务执行、路由跳转和权限判断留在宿主项目。
+}
+</script>
+```
+
+### QyDialog
+
+```vue
 <template>
 <QyDialog title="标题" @confirm="handleConfirm">
   内容区域
@@ -960,10 +1059,10 @@ function handleAction(action, context) {
 - `QyDatePicker` 第一版优先兼容 `ElDatePicker`，查询结束时间归一化需要显式开启
 - `QyRemoteSelect` 负责远程请求状态和回显保留，不承接具体业务接口协议转换
 - `QyFormSection` 只负责区块壳，不替代 `@qiyin/form` 的 schema / 校验能力
-- `QyActionBar` 只负责底部布局壳，不负责编排按钮业务逻辑
-- `QySearchInput` 第一版已经覆盖建议搜索场景，可通过 `show-button=false` 关闭默认搜索按钮，但仍然不承接页面级副作用
-- `QyRecordQuoteSearch` 只承接报价单搜索入口逻辑，不直接改整页录单状态
-- `QyImage` 负责通用图片显示，不负责表格列取值、formatter、水印和列设置；这些由 `@qynpm/table-schema` 组合
+- `QyActionBar` 只负责底部布局壳，不负责编排按钮业务逻辑
+- `QySearchInput` 第一版已经覆盖建议搜索场景，可通过 `show-button=false` 关闭默认搜索按钮，但仍然不承接页面级副作用
+- `QyRecordQuoteSearch` 只承接报价单搜索入口逻辑，不直接改整页录单状态
+- `QyImage` 负责通用图片显示，不负责表格列取值、formatter、水印和列设置；这些由 `@qynpm/table-schema` 组合
 
 ## 当前联调说明