@qynpm/ui

起印体系内抽离出来的 Vue 3 UI 组件包，当前主要包含基础输入组件、选择器组件、区块容器、底部操作栏，以及上传、弹窗、备注图文等通用能力。

安装

pnpm add @qynpm/ui

Peer Dependencies：

• vue >= 3.4
• element-plus >= 2.0
• @element-plus/icons-vue >= 2.0
• @vueuse/core >= 10.0
• clsx >= 2.0

注册

import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import QyUI from '@qynpm/ui'

const app = createApp(App)

app.use(ElementPlus)
app.use(QyUI)

也可以按需引入：

import {
  QyUpload,
  QyVoucherUpload,
  QyDialog,
  QyRemarkImage,
  QyInput,
  QyMoneyInput,
  QyRadioGroup,
  QySelect,
  QyRemoteSelect,
  QyFormSection,
  QyActionBar,
  QySearchInput,
  QyRecordQuoteSearch
} from '@qynpm/ui'

也可以按需引入单个组件入口：

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 QyRemoteSelect from '@qynpm/ui/qy-remote-select'
import QyFormSection from '@qynpm/ui/qy-form-section'
import QyActionBar from '@qynpm/ui/qy-action-bar'
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 QyVoucherUpload from '@qynpm/ui/qy-voucher-upload'
import QyRemarkImage from '@qynpm/ui/qy-remark-image'

组件说明

QyUpload

上传组件，支持：

• 图片上传
• 视频上传
• 粘贴上传
• 拖拽上传
• 文本备注
• 预览
• v-model
• valueFormat
• 纯图片模式

当前可配置项里，和宿主耦合最强的是上传配置：

• api
• tokenKey
• name

其中：

• api 为必填
• tokenKey 不传时默认使用 Admin-Token
• name 不传时默认使用 file

值协议：

• 默认 valueFormat="object"，v-model 输出 { files: string[], text: string }
• valueFormat="array"，v-model 输出 string[]
• valueFormat="string"，v-model 输出逗号分隔 URL
• showText=false 可隐藏文字备注区；如仍需粘贴入口，可开启 showPasteInput
• defaultValue 仍保留给老页面做非受控初始化；新页面建议优先使用 v-model

QyVoucherUpload

凭证上传组件，基于 QyUpload 的薄封装，适合财审凭证、收款凭证、返现凭证等纯图片凭证场景。

固定协议：

• v-model 为 string[]
• 默认 name="files"
• 默认 showText=false
• 默认开启纯粘贴输入条，用于恢复“粘贴图片上传”的凭证交互
• 默认 pastePlaceholder="粘贴图片上传"
• 默认 size="90px"

如果需要图片加文字备注，请直接使用 QyUpload。

QyDialog

弹窗组件，支持：

• 默认头部/底部布局
• 全屏切换
• 最小化
• 自定义 footer
• 移动端自动全屏

QyInput

输入组件，第一版定位为 ElInput 的轻量包装层，重点支持：

• 保持和 ElInput 接近的使用方式
• removeSpace
• trimMode
• enter
• textarea
• 兼容常见 slots 与 expose 方法

QyMoneyInput

金额输入组件，第一版定位为 ElInput 的金额录入包装层，重点支持：

• 输入过程清洗非法字符
• 默认失焦格式化为固定小数位
• precision
• min / max
• allowNegative
• 兼容常见 slots 与 expose 方法

QyRadioGroup

单选组组件，第一版定位为 ElRadioGroup 的轻量包装层，重点支持：

• options 直出
• labelKey / valueKey / disabledKey 映射
• 普通单选 / 按钮式单选
• 选项禁用
• option 插槽自定义选项文案
• 事件保持 update:modelValue、change

option 插槽由外部传入，组件会透出当前选项的：

• option：原始选项对象
• label：映射后的展示文案
• value：映射后的选项值
• disabled：是否禁用

QySelect

选择器组件，第一版定位为 ElSelect 的轻量包装层，重点支持：

• options 直出
• labelKey / valueKey / disabledKey 映射
• 单选 / 多选
• collapse-tags
• 默认弹层挂载策略
• 保留原生 slot 扩展

QyRemoteSelect

远程选择器组件，基于 QySelect 组合实现，重点支持：

• fetchMethod(keyword) 远程请求
• debounce
• minLength
• defaultOptions
• remoteOnFocus
• 内部请求 loading
• error
• options-change
• 已选项缓存，避免远程 options 清空后回显丢 label
• 继承 QySelect 的字段映射、多选、折叠标签、唯一选项自动选中能力

如果只是本地 options 下拉，应优先使用 QySelect；只有需要远程请求、搜索和回显保留时再使用 QyRemoteSelect。

QyFormSection

区块容器组件，适合录单页面的表单区块外壳，重点支持：

• 标题
• 描述
• 操作区 slot
• 提示区
• 简单折叠
• 统一边框、背景和间距

QyActionBar

底部操作栏组件，适合录单页面底部按钮区，重点支持：

• sticky 吸底
• 左右分区
• 窄屏换行
• 边框 / 阴影
• 底部安全区适配

QySearchInput

搜索输入组件，支持：

• 基于 ElAutocomplete 的等价封装
• 搜索按钮
• 回车搜索
• 本地建议项
• 远程建议项
• 兼容 fetch-suggestions(queryString, cb) 回调风格
• 高亮匹配词
• 默认使用 Element Plus 弹层挂载策略，避免被父级裁剪
• 平铺项和分组项两种建议结构

QyRecordQuoteSearch

录单报价单号搜索组件，支持：

• 报价单号输入
• 报价单号提取与规范化
• 搜索触发
• 建议项选择
• 局部状态提示
• loading-change / success / error 事件

样式说明

• 包内样式会跟随构建产物一起注入
• 宿主仍然需要自行引入 element-plus/dist/index.css
• 当前组件内部仍然依赖宿主提供的 Tailwind / Iconify 体系能力

使用示例

QyUpload

<template>
  <QyUpload
    v-model="uploadValue"
    api="/permission-api/common/uploads"
    token-key="Admin-Token"
    @change="handleChange"
  />
</template>

纯图片上传：

<template>
  <QyUpload
    v-model="payImgs"
    api="/permission-api/common/uploads"
    name="files"
    value-format="array"
    :show-text="false"
    :show-paste-input="true"
    paste-placeholder="粘贴图片上传"
    size="90px"
  />
</template>

QyVoucherUpload

<template>
  <QyVoucherUpload
    v-model="payImgs"
    api="/permission-api/common/uploads"
    :limit="9"
    :file-size="10"
  />
</template>

QyDialog

<template>
<QyDialog title="标题" @confirm="handleConfirm">
  内容区域
</QyDialog>
</template>

QyInput

<template>
  <QyInput
    v-model="quoteOrderCode"
    remove-space
    trim-mode="blur"
    placeholder="填写报价单,回车搜索"
    @enter="handleSearch"
  />
</template>

QyMoneyInput

<template>
  <QyMoneyInput
    v-model="totalPay"
    :precision="2"
    :min="0"
    placeholder="请输入总金额"
  />
</template>

QyRadioGroup

<template>
  <QyRadioGroup
    v-model="openTicket"
    :options="ticketOptions"
  />
</template>

自定义选项展示：

<template>
  <QyRadioGroup v-model="openTicket" :options="ticketOptions">
    <template #option="{ option, label }">
      <span>{{ label }}</span>
      <span v-if="option.fee" style="margin-left: 6px; color: #f56c6c">
        {{ option.fee }}
      </span>
    </template>
  </QyRadioGroup>
</template>

QySelect

<template>
  <QySelect
    v-model="shopCode"
    :options="shopOptions"
    placeholder="请选择店铺"
  />
</template>

QyRemoteSelect

<template>
  <QyRemoteSelect
    v-model="recvAccount"
    :fetch-method="fetchFinanceAccounts"
    :default-options="accountDefaultOptions"
    label-key="accountName"
    value-key="accountId"
    placeholder="请选择收款账户"
    remote-on-focus
    @error="handleAccountError"
  />
</template>

QyFormSection

<template>
  <QyFormSection title="订单信息" description="这里放订单表单区块">
    <el-form>...</el-form>
  </QyFormSection>
</template>

QyActionBar

<template>
  <QyActionBar>
    <template #left>
      <el-button plain>开票</el-button>
    </template>
    <template #right>
      <el-button>保存</el-button>
      <el-button type="primary">提交</el-button>
    </template>
  </QyActionBar>
</template>

QySearchInput

<template>
  <QySearchInput
    v-model="keyword"
    :fetch-suggestions-method="querySearch"
    @search="handleSearch"
  />
</template>

QyRecordQuoteSearch

<template>
  <QyRecordQuoteSearch
    v-model="quoteOrderCode"
    :fetch-suggestions="fetchQuoteSuggestions"
    :search-method="handleQuoteSearch"
    @search="handleSearch"
  />
</template>

说明

• 当前版本更适合体系内拆包复用
• 上传默认值仍然保留了现有项目约定，后续如果完全独立对外，可以再继续抽离
• QyInput 第一版优先兼容 ElInput，后续再逐步补统一输入规则
• QyRadioGroup 第一版优先兼容 ElRadioGroup，不内置字典请求或复杂表单联动
• QySelect 第一版优先兼容 ElSelect，不内置远程字典或复杂请求能力
• QyRemoteSelect 负责远程请求状态和回显保留，不承接具体业务接口协议转换
• QyFormSection 只负责区块壳，不替代 @qiyin/form 的 schema / 校验能力
• QyActionBar 只负责底部布局壳，不负责编排按钮业务逻辑
• QySearchInput 第一版已经覆盖建议搜索场景，但仍然不承接页面级副作用
• QyRecordQuoteSearch 只承接报价单搜索入口逻辑，不直接改整页录单状态

当前联调说明

当前 workspace 联调由顶层 Vite 开关统一控制，不再要求在 UI 或 form 内手动切换 import。

开关位置：

• vite.config.ts

当前配置：

const ENABLE_LOCAL_QIYIN_DEBUG = true

规则如下：

1. 当值为 true 时

• @qynpm/ui 映射到本地 @qiyin/UI/lib/index.js
• @qynpm/form / @qiyin/form 映射到本地 @qiyin/form/index.ts
• 消费项目开发时可以直接联调 UI 与 form

2. 当值为 false 时

• 走各自包的正常入口
• 行为更接近线上

如果切换开关后页面报 Outdated Optimize Dep：

1. 停掉当前 dev 服务
2. 清理消费项目的 node_modules/.vite
3. 重新启动