@qynpm/ui 1.0.23 → 1.0.25

package/README.md

@@ -36,6 +36,11 @@ app.use(QyUI)
 ```ts
 import {
   QyUpload,
+  QyFilePicker,
+  QySwitch,
+  QyTag,
+  QyTooltip,
+  QyPopover,
   QyImage,
   QyImagePreview,
   QyImageUpload,
@@ -48,6 +53,7 @@ import {
   QyMoneyInput,
   QyDatePicker,
   QyCheckbox,
+  QyRadio,
   QyAutocomplete,
   QyMenuActions,
   QyTableColumnSettings,
@@ -81,6 +87,11 @@ 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 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'
@@ -88,14 +99,15 @@ 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 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'
-```
-
-后台公共包必须通过 `@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` 执行：
+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
@@ -111,6 +123,88 @@ pnpm install --frozen-lockfile --ignore-scripts
 
 ## 组件说明
 
+### `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`
 
 上传组件，支持：
@@ -244,9 +338,53 @@ type QyImageProps = {
 
 ### `QyCheckbox`
 
-复选框基础组件，基于 `ElCheckbox` 做薄封装，统一 `v-model`、`change`、`focus`、`blur` 事件和单组件入口。
+受控复选框基础组件，基于 `ElCheckbox` 做隔离适配，`modelValue`、`trueValue`、`falseValue` 和事件 payload 均保持 `boolean | string | number` 原始类型，不做隐式布尔转换。
 
-主要用于普通表单复选框，以及 `@qynpm/table-schema` 的 `edit-checkbox` 渲染器底座。
+支持 `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`
 
@@ -441,7 +579,11 @@ type QyImageProps = {
 - `trimMode`
 - `enter`
 - `textarea`
-- 兼容常见 slots 与 expose 方法
+- `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`
 
@@ -464,6 +606,10 @@ type QyImageProps = {
 - `step-strictly`
 - `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` 做金额格式化。
@@ -478,11 +624,13 @@ type QyImageProps = {
 - `default-time`
 - `shortcuts`
 - `disabled-date`
-- 默认弹层挂载到 `body`
-- `normalize-range-end-time` 查询场景结束时间归一化
-- 兼容 `focus / blur / handleOpen / handleClose` expose 方法
+- `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` 归一为 `23:59:59` 时再显式开启，避免影响普通日期选择。
+`normalize-range-end-time` 默认关闭。开启后只处理范围第二项：精确 `00:00:00.000` 的 `Date` 克隆为 `23:59:59.000`，带明确午夜时间的普通/ISO 字符串只替换时间并保留格式及 zone suffix；date-only 字符串、number、非午夜和非范围值保持原引用，不修改父数组或父 `Date`。
 
 ### `QyRadioGroup`
 
@@ -502,16 +650,30 @@ type QyImageProps = {
 - `value`：映射后的选项值
 - `disabled`：是否禁用
 
+普通 `options` 模式物理复用 `QyRadio`；`type="button"` 继续使用内部 Element Plus button adapter。已发布的 `getRadioGroupInstance()` 仅为兼容保留并标记为 deprecated，不新增实例能力。
+
 ### `QySelect`
 
-选择器组件，第一版定位为 `ElSelect` 的轻量包装层，重点支持：
+受控选择器组件。string、number、boolean、对象值和多选数组会原样通过 `update:modelValue` / `change` 返回；组件不会排序、克隆或隐式转换，父级 `modelValue` 始终是最终状态权威。
 
-- `options` 直出
-- `labelKey / valueKey / disabledKey` 映射
-- 单选 / 多选
-- `collapse-tags`
-- 默认弹层挂载策略
-- 保留原生 slot 扩展
+- `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`
 
@@ -942,6 +1104,18 @@ function handleSelect(item) {
 </template>
 ```
 
+### QyRadio
+
+```vue
+<template>
+  <QyRadio
+    v-model="ticketType"
+    value="invoice"
+    label="开票"
+  />
+</template>
+```
+
 ### QyRadioGroup
 
 ```vue