@qynpm/ui 1.0.22 → 1.0.24

package/README.md

@@ -35,8 +35,13 @@ app.use(QyUI)
 
 ```ts
 import {
-  QyUpload,
-  QyImage,
+  QyUpload,
+  QyFilePicker,
+  QySwitch,
+  QyTag,
+  QyTooltip,
+  QyPopover,
+  QyImage,
   QyImagePreview,
   QyImageUpload,
   QyDialog,
@@ -46,9 +51,10 @@ import {
   QyInput,
   QyInputNumber,
   QyMoneyInput,
-  QyDatePicker,
-  QyCheckbox,
-  QyAutocomplete,
+  QyDatePicker,
+  QyCheckbox,
+  QyRadio,
+  QyAutocomplete,
   QyMenuActions,
   QyTableColumnSettings,
   QyRadioGroup,
@@ -80,20 +86,28 @@ 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 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 QyTooltip from '@qynpm/ui/qy-tooltip'
+import QyPopover from '@qynpm/ui/qy-popover'
 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 QyDatePicker from '@qynpm/ui/qy-date-picker'
+import QyCheckbox from '@qynpm/ui/qy-checkbox'
+import QyRadio from '@qynpm/ui/qy-radio'
 import QyAutocomplete from '@qynpm/ui/qy-autocomplete'
 import QyMenuActions from '@qynpm/ui/qy-menu-actions'
-import QyTableColumnSettings from '@qynpm/ui/qy-table-column-settings'
-```
-
-本地 file 依赖联调说明：单组件入口的 `package.json exports` 指向 `dist/qy-*/index.mjs` 和 `dist/qy-*/index.cjs`，而 `dist` 不提交到仓库。消费项目如果通过 `file:../qy-components/packages/ui` 引用本包，必须先在 `qy-components` 执行：
+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
@@ -107,9 +121,91 @@ pnpm install --frozen-lockfile --ignore-scripts
 
 不要依赖本机残留的 `packages/ui/dist`。如果后续希望免 build 联调，应在消费项目显式配置源码 alias，而不是把包 export 指向未发布源码。
 
-## 组件说明
-
-### `QyUpload`
+## 组件说明
+
+### `QyFilePicker`
+
+单文件选择组件，支持点击选择、拖拽、替换、清空以及后缀和大小校验。
+
+- `v-model` 只输出浏览器原始 `File | null`。
+- `extensions` 忽略大小写，可传 `xls` 或 `.xlsx`。
+- `maxSizeMb` 的边界值允许，默认 20MB。
+- 校验失败触发 `invalid`，并保留原有 `modelValue`。
+- 组件只选择本地文件，不发送请求、不读取 token、不生成或保存 URL，也不复用 `QyUpload` 的业务上传协议。
+
+```vue
+<QyFilePicker
+  v-model="file"
+  :extensions="['xls', 'xlsx']"
+  :max-size-mb="20"
+  placeholder="选择或拖拽 Excel 文件"
+  @invalid="handleInvalid"
+/>
+```
+
+### `QySwitch`
+
+受控开关组件，`modelValue`、`activeValue`、`inactiveValue` 和 `update:modelValue` / `change` payload 均为 `boolean | string | number`，不进行隐式布尔化。
+
+```vue
+<QySwitch
+  v-model="enabled"
+  active-text="启用"
+  inactive-text="停用"
+  @change="handleChange"
+/>
+```
+
+支持 `disabled`、`loading`、`size`、`inlinePrompt`、`name`、`id`、`tabindex` 和 `ariaLabel`，以及 `class`、`style`、`role`、`title`、`data-*`、其它 `aria-*` 安全属性。只发出 `update:modelValue`、`change`、`focus`、`blur`；不提供 `beforeChange`、`input`、图标/slot 或底层实例、focus/blur 等命令式方法。
+
+### `QyTag`
+
+通用紧凑标签，内部使用 `ElTag`，公开 `tone`、`size`、`effect`、`closable`、`round`、`disabled` 和默认 slot。`tone` 支持 `neutral`、`primary`、`success`、`warning`、`danger`、`info`；`size` 为 `sm`、`md`、`lg`，默认分别映射为 Element Plus 的 `small`、`default`、`large`。
+
+```vue
+<QyTag tone="success" size="sm" closable @close="removeTag">
+  已完成
+</QyTag>
+```
+
+`disabled` 会设置 `aria-disabled="true"`、隐藏关闭按钮并抑制 `click` / `close`；非禁用状态下这两个事件各发出一次 `MouseEvent`。支持 `class`、`style`、`title`、`role`、`data-*`、`aria-*` 安全属性，不公开 `color`、`hit`、`disableTransitions` 或底层 Element Plus 实例。QyTag 不是按钮，不新增键盘按钮语义；需要动作语义时使用 `QyButton`。
+
+### `QyTooltip`
+
+只读提示组件。默认插槽是唯一触发内容，不增加触发元素包装 DOM；`content` 插槽（content slot）优先于 `content` 属性。组件支持 hover / focus、完整 `placement`、`light` / `dark` effect、延迟、偏移和可收缩的 `maxWidth`。
+
+```vue
+<QyTooltip content="说明文字" placement="top-start">
+  <button type="button">查看提示</button>
+</QyTooltip>
+
+<QyTooltip content="属性内容">
+  <button type="button">插槽内容</button>
+  <template #content>只读插槽内容</template>
+</QyTooltip>
+```
+
+默认值为 `placement="top"`、`effect="dark"`、`disabled=false`、`showDelay=0`、`hideDelay=200`、`offset=12`、`maxWidth=320`。事件只有 `open` / `close`，且只在实际可见状态转换时各发一次；不公开 `trigger`、受控 `open`、raw HTML、交互内容、Element Plus attrs/listeners 或实例方法。
+
+### `QyPopover`
+
+交互浮层组件。`reference` 插槽是触发元素，默认插槽是可交互面板内容，不增加触发元素包装 DOM；支持 `click`、`hover`、`focus`、`contextmenu`、完整 `placement`、`light` / `dark` effect、数字或 CSS 字符串 `width`、延迟、偏移、箭头和窄视口收缩。
+
+```vue
+<QyPopover placement="bottom-start" :width="280" @open-change="onOpenChange">
+  <template #reference><button type="button">打开操作</button></template>
+  <button type="button" @click="submit">确认</button>
+</QyPopover>
+
+<QyPopover v-model:open="open" trigger="contextmenu">
+  <template #reference><div>右键区域</div></template>
+  <div>受控交互内容</div>
+</QyPopover>
+```
+
+默认值为 `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`。
+
+### `QyUpload`
 
 上传组件，支持：
 
@@ -187,7 +283,7 @@ pnpm install --frozen-lockfile --ignore-scripts
 - `error` 事件。
 - `placeholder` 空图占位。
 - `compressor` 压缩缩略图参数。
-- 旧域名兼容：`http` 转 `https`，`ys.diansan.com` 转 `admin.qiyinbz.com`。
+- 旧域名兼容：`ys.diansan.com` 地址迁移为 `https://admin.qiyinbz.com`。
 - 旧缩略图参数：点三域名使用 `?small=true&style=image/resize,h_{h},w_{w}`，其他域名使用 `?w={w}`。
 - 失败兜底：缩略图请求失败后请求原图 blob，并用浏览器 canvas 压缩成 dataURL 展示。
 - `preview / previewList / initialIndex` 图片预览。
@@ -240,11 +336,55 @@ type QyImageProps = {
 
 该能力是 `@qynpm/table-schema` 完整迁移 image 列的前置能力。table-schema 不应该长期维护一份独立图片预览逻辑。
 
-### `QyCheckbox`
-
-复选框基础组件，基于 `ElCheckbox` 做薄封装，统一 `v-model`、`change`、`focus`、`blur` 事件和单组件入口。
-
-主要用于普通表单复选框，以及 `@qynpm/table-schema` 的 `edit-checkbox` 渲染器底座。
+### `QyCheckbox`
+
+受控复选框基础组件，基于 `ElCheckbox` 做隔离适配，`modelValue`、`trueValue`、`falseValue` 和事件 payload 均保持 `boolean | string | number` 原始类型，不做隐式布尔转换。
+
+支持 `value`（为后续 `QyCheckboxGroup` 保留的选项值）、只读展示状态 `indeterminate`、`disabled`、`size` 和默认 slot。事件只有 `update:modelValue`、`change`、`focus`、`blur`；禁用状态不产生值变更意图，也不公开 Element Plus 实例或命令式方法。
+
+```vue
+<QyCheckbox
+  v-model="ticketValue"
+  true-value="Y"
+  false-value="N"
+  aria-label="开票"
+  @change="handleChange"
+>
+  开票
+</QyCheckbox>
+```
+
+`class`、`style`、`id`、`name`、`role`、`title`、`data-*` 和 `aria-*` 会安全透传；桌面交互区域保持紧凑，窄屏下提升到至少 40px。`QyCheckboxGroup`、全选/级联和 `CheckboxButton` 不属于 V1。
+
+### `QyRadio`
+
+受控单选框基础组件，基于 `ElRadio` 做隔离适配。`value` 表示选中值，`label` 只负责展示；默认 slot 优先。`modelValue` 与事件 payload 保持 `boolean | string | number` 原始类型，父级不回写时组件不会自行改变状态，也不会通过再次点击取消选中。
+
+支持 `disabled`、`size`、`name`、`border` 以及 `update:modelValue`、`change`、`focus`、`blur` 事件；安全透传 `class`、`style`、`role`、`title`、`data-*` 和 `aria-*`，不公开 Element Plus 实例或命令式方法。
+
+```vue
+<QyRadio
+  v-model="ticketType"
+  value="invoice"
+  label="开票"
+  name="ticket-type"
+  border
+  @change="handleChange"
+/>
+```
+
+### `QyCheckboxGroup`
+
+受控复选框组，统一管理 `QyCheckboxValue[]`。支持默认 slot 或 `options`（两者同时存在时 slot 优先），并透传 `disabled`、`min`、`max`、`size`。事件只有 `update:modelValue` 和 `change`，每次更新都返回新数组。
+
+```vue
+<QyCheckboxGroup v-model="selected" :options="[
+  { label: '阅读', value: 'read' },
+  { label: '写作', value: 'write', disabled: true }
+]" />
+```
+
+options 模式物理复用 `QyCheckbox`；不提供 CheckboxButton、全选、indeterminate 推导、树形/层级选择、布局 props 或 Element Plus 实例。
 
 ### `QyAutocomplete`
 
@@ -436,10 +576,14 @@ type QyImageProps = {
 
 - 保持和 `ElInput` 接近的使用方式
 - `removeSpace`
-- `trimMode`
-- `enter`
-- `textarea`
-- 兼容常见 slots 与 expose 方法
+- `trimMode`
+- `enter`
+- `textarea`
+- `modelValue` 支持 `string | number | null | undefined`，用户编辑事件统一输出 `string`
+- 兼容 `text`、`textarea`、`password`、`search` 和 Element Plus 常用属性
+- 兼容 `prefix`、`suffix`、`prepend`、`append` slots
+- 类型出口包含 `QyInputValue`、`QyInputModelValue`、`QyInputProps`、`QyInputEmits` 和 `QyInputExposed`
+- 只公开 `focus`、`blur`、`select`、`clear`、`resizeTextarea` 方法
 
 ### `QyMoneyInput`
 
@@ -460,9 +604,13 @@ type QyImageProps = {
 - `min / max`
 - `step`
 - `step-strictly`
-- `precision`
-- `controls / controls-position`
-- 兼容 `focus / blur` expose 方法
+- `precision`
+- `controls / controls-position`
+- `valueOnClear`（默认 `null`，也支持 `min / max / number`）
+- `readonly / disabled / formatter / parser / inputmode / align`
+- `prefix / suffix / increase-icon / decrease-icon` slots
+- `update:modelValue / input / change / focus / blur` 显式事件
+- 兼容 `focus / blur` expose 方法
 
 金额、费用、税费等财务录入场景请优先使用 `QyMoneyInput`，不要用 `QyInputNumber` 做金额格式化。
 
@@ -473,14 +621,16 @@ type QyImageProps = {
 - 保持和 `ElDatePicker` 接近的使用方式
 - `date / datetime / daterange / datetimerange` 等常见类型
 - `format / value-format`
-- `default-time`
-- `shortcuts`
-- `disabled-date`
-- 默认弹层挂载到 `body`
-- `normalize-range-end-time` 查询场景结束时间归一化
-- 兼容 `focus / blur / handleOpen / handleClose` expose 方法
-
-`normalize-range-end-time` 默认关闭。只有查询表单需要把范围结束值从当天 `00:00:00` 归一为 `23:59:59` 时再显式开启，避免影响普通日期选择。
+- `default-time`
+- `shortcuts`
+- `disabled-date`
+- `year / month / date / dates / datetime / week / daterange / datetimerange / monthrange`
+- `clearable / disabled / readonly / teleported / append-to / popper-class`
+- `update:modelValue / change / clear / calendar-change / panel-change / visible-change / focus / blur`
+- `default / range-separator / prev-month / next-month / prev-year / next-year` slots
+- 仅公开 `focus() / blur() / open() / close()` expose 方法
+
+`normalize-range-end-time` 默认关闭。开启后只处理范围第二项：精确 `00:00:00.000` 的 `Date` 克隆为 `23:59:59.000`，带明确午夜时间的普通/ISO 字符串只替换时间并保留格式及 zone suffix；date-only 字符串、number、非午夜和非范围值保持原引用，不修改父数组或父 `Date`。
 
 ### `QyRadioGroup`
 
@@ -493,23 +643,37 @@ type QyImageProps = {
 - `option` 插槽自定义选项文案
 - 事件保持 `update:modelValue`、`change`
 
-`option` 插槽由外部传入，组件会透出当前选项的：
+`option` 插槽由外部传入，组件会透出当前选项的：
 
 - `option`：原始选项对象
 - `label`：映射后的展示文案
 - `value`：映射后的选项值
-- `disabled`：是否禁用
-
-### `QySelect`
-
-选择器组件，第一版定位为 `ElSelect` 的轻量包装层，重点支持：
-
-- `options` 直出
-- `labelKey / valueKey / disabledKey` 映射
-- 单选 / 多选
-- `collapse-tags`
-- 默认弹层挂载策略
-- 保留原生 slot 扩展
+- `disabled`：是否禁用
+
+普通 `options` 模式物理复用 `QyRadio`；`type="button"` 继续使用内部 Element Plus button adapter。已发布的 `getRadioGroupInstance()` 仅为兼容保留并标记为 deprecated，不新增实例能力。
+
+### `QySelect`
+
+受控选择器组件。string、number、boolean、对象值和多选数组会原样通过 `update:modelValue` / `change` 返回；组件不会排序、克隆或隐式转换，父级 `modelValue` 始终是最终状态权威。
+
+- `options` 支持 `labelKey / valueKey / disabledKey` 字段映射；默认 slot 有实际内容时优先。
+- `valueKey` 只决定 option 的值字段；对象值需要稳定回显时，使用 `objectIdentityKey` 指定对象身份字段。
+- 支持单选、多选、disabled、clearable、filterable、loading、collapse tags、弹层挂载和 popper class。
+- `autoSelectSingle` 只在 options 模式、当前值为空且唯一 option 未禁用时触发一次 `update:modelValue` 后再触发一次 `change`；父值变为非空后再次清空可重新触发。
+- 保留 prefix、empty、loading、tag 和 default slots，以及 clear、visible-change、focus、blur 事件。
+- 只公开 `focus()` / `blur()`，不公开 Element Plus 实例或 DOM 引用。
+
+```vue
+<QySelect
+  v-model="selectedUser"
+  :options="userOptions"
+  label-key="name"
+  value-key="user"
+  object-identity-key="id"
+/>
+```
+
+远程请求、防抖和已选项缓存仍由 `QyRemoteSelect` 负责；`QySelect` 不承接业务字典或请求状态编排。
 
 ### `QyTreeSelect`
 
@@ -940,11 +1104,23 @@ function handleSelect(item) {
 </template>
 ```
 
-### QyRadioGroup
-
-```vue
-<template>
-  <QyRadioGroup
+### QyRadio
+
+```vue
+<template>
+  <QyRadio
+    v-model="ticketType"
+    value="invoice"
+    label="开票"
+  />
+</template>
+```
+
+### QyRadioGroup
+
+```vue
+<template>
+  <QyRadioGroup
     v-model="openTicket"
     :options="ticketOptions"
   />