全局 API

以下接口来自 3.9.5 的 src/index.ts 公共导出。组件已通过 app.use(Avue) 注册时，Options API 可使用 this.$Clipboard 等全局方法；Composition API 可以直接导入。浏览器 DOM、文件、剪切板相关方法应在用户操作或 onMounted 后调用。

调用方式

$DialogForm 和 $ImagePreview 的具名导出是工厂函数：先传当前应用的 appContext，再传业务参数。安装后挂载到全局的版本已绑定上下文，直接传业务参数即可。其余插件无需这一步。

import { getCurrentInstance } from 'vue'
import { $DialogForm } from '@smallwei/avue'

// 在 setup 中获取，不能等点击事件发生时才调用 getCurrentInstance()
const { appContext } = getCurrentInstance()
const openDialog = $DialogForm(appContext)

// 点击按钮时：openDialog({ title: '编辑', data: {}, option: { column: [] } })

$DialogForm 弹窗表单

完整示例。支持 Dialog 和 Drawer；表单配置与 Form 相同。

参数 / 返回值	说明
option	Form 配置，包含 column、按钮文字、校验规则等
data	表单初始数据对象
title、width	弹窗标题和宽度；Drawer 同样通过 width 转换为尺寸
type	设置为 drawer 使用抽屉，其他值使用弹窗
appendTo	挂载容器的 CSS 选择器，默认 document.body
callback({ data, done, close })	表单校验通过后执行；done() 结束提交 loading，close() 走关闭流程
beforeClose(close)	自定义关闭流程，需要关闭时调用参数 close()
返回值的 close()	直接销毁这个弹窗实例，用于页面卸载等场景；不经过 beforeClose

<template>
  <el-button @click="open">打开表单</el-button>
  <p>{{ result }}</p>
</template>

<script setup>
import { getCurrentInstance, onBeforeUnmount, ref } from 'vue'
import { $DialogForm } from '@smallwei/avue'

const { appContext } = getCurrentInstance()
const openDialog = $DialogForm(appContext)
const result = ref('')
let dialog
const open = () => {
  dialog?.close()
  dialog = openDialog({
    title: '登记姓名',
    width: 'min(520px, 92vw)',
    data: { name: '' },
    option: {
      column: [{
        label: '姓名', prop: 'name', span: 24,
        rules: [{ required: true, message: '请输入姓名', trigger: 'blur' }]
      }]
    },
    callback: ({ data, done, close }) => {
      result.value = data.name
      done()
      close()
      dialog = null
    }
  })
}
onBeforeUnmount(() => dialog?.close())
</script>

保存异步数据时，在请求成功后调用 close()，失败时保留弹窗；通过 finally 调用 done()。主动关闭应保存并使用已打开的实例，重新调用工厂会新开一个弹窗。

$ImagePreview 图片预览

交互示例。

import { getCurrentInstance } from 'vue'
import { $ImagePreview } from '@smallwei/avue'

const { appContext } = getCurrentInstance()
const preview = $ImagePreview(appContext)
const showImage = () => preview([
  { thumbUrl: '/images/logo.png', url: '/images/logo.png' }
], 0, { closeOnClickModal: true })

第一个参数是图片数组，url 是大图，thumbUrl 是缩略图；第二个参数为从 0 开始的当前索引。第三个参数支持 appendTo、modal（默认 true）、closeOnClickModal（默认 false）、beforeClose 和 click，回调签名见示例页。它没有与 DialogForm 相同的公开 close() 方法。

$Clipboard 复制文本

返回 Promise<void>，失败时会拒绝；请在按钮点击等用户操作中调用。交互示例。

import { $Clipboard } from '@smallwei/avue'
import { ElMessage } from 'element-plus'

async function copy() {
  try {
    await $Clipboard({ text: '订单 A001', fallback: true })
    ElMessage.success('复制成功')
  } catch (error) {
    ElMessage.error(error.message)
  }
}

text 接受字符串、数字、null 或 undefined，后两者复制为空字符串。fallback 默认 true，现代剪切板 API 不可用或被拒绝时尝试兼容方式；设为 false 则不尝试兼容方式。

$Print 打印

$Print(dom, options) 接受 CSS 选择器、HTMLElement 或含 $el 的组件实例，创建打印 iframe。它不返回 Promise；通过回调观察进度。详见打印示例。

import { $Print } from '@smallwei/avue'

function printReceipt() {
  $Print('#receipt', {
    documentTitle: '收据',
    noPrint: '.no-print',
    timeout: 15000,
    onAfterPrint: () => console.log('打印对话框已结束'),
    onError: error => console.error(error.message)
  })
}

#receipt 需要已经存在。支持 onReady、onBeforePrint、onAfterPrint；onAfterPrint 表示打印流程结束，并不表示用户一定打印了纸张。noPrint 默认 .no-print，目标不存在时同步抛出异常。

$Export Excel 导入与导出

调用前需提供 window.XLSX；依赖准备见组件与依赖索引。当前导出代码使用 Blob 下载，无需额外提供 window.saveAs。完整示例。

import { $Export } from '@smallwei/avue'

async function exportRows() {
  const result = await $Export.excel({
    title: '人员名单',
    filename: '人员名单',
    sheetName: '人员',
    columns: [{ label: '姓名', prop: 'name' }],
    data: [{ name: '张三' }]
  })
  console.log(result) // { filename: '人员名单.xlsx', sheetName: '人员', rows: 1 }
}

columns 是复数，至少配置一列；children 可声明多级表头。按列的 prop 从记录取值，不会自动将字典值翻译成标签。导出文件名会自动附加 .xlsx，因此 filename 不需要再写扩展名。

async function importFile(file) {
  const { header, results, sheetName } = await $Export.xlsx(file, {
    sheetIndex: 0,
    headerRow: 0,
    raw: false,
    defval: ''
  })
  // results 的键来自 Excel 表头，业务字段映射需自行处理
  return { header, results, sheetName }
}

file 必须是 File。sheetName 优先于 sheetIndex；headerRow 为从 0 开始的表头行。两个方法均返回 Promise，接入时处理拒绝状态。

$Screenshot 截图

$Screenshot(element, options) 返回 Promise<HTMLCanvasElement>。支持 renderer 传入 html2canvas 函数，否则读取 window.html2canvas；未传 DOM 或缺少渲染器会失败。截图示例。

import { $Screenshot } from '@smallwei/avue'
import html2canvas from 'html2canvas'

async function capture(element) {
  return $Screenshot(element, {
    renderer: html2canvas,
    download: true,
    filename: '截图.png',
    type: 'image/png',
    backgroundColor: '#fff'
  })
}

download 默认不启用；filename 默认带时间戳。type、quality 控制下载图片；onSuccess(canvas)、onError(error) 为回调，其他字段传给渲染器。

$Watermark 页面水印

$Watermark(options) 返回实例，可通过 Repaint(options) 更新、remove() 移除。局部水印需要传入实际元素，或不带 # 的元素 id。

效果预览可直接操作下方示例

在当前示例区域添加、更新、移除水印；离开页面时会清理实例。

正在加载示例…

<template>
  <section class="watermark-demo">
    <div class="watermark-demo__actions">
      <el-button type="primary" @click="add">添加水印</el-button>
      <el-button :disabled="!enabled" @click="repaint">更新水印</el-button>
      <el-button :disabled="!enabled" @click="remove">移除水印</el-button>
    </div>
    <div ref="target" class="watermark-demo__paper">
      <strong>订单预览</strong>
      <p>订单编号：A001</p>
      <p>水印只覆盖当前预览区域，可以继续选择和阅读文字。</p>
    </div>
    <p aria-live="polite">{{ message }}</p>
  </section>
</template>

<script setup>
import { onBeforeUnmount, ref } from 'vue'
import { $Watermark } from '@smallwei/avue'

const target = ref(null)
const enabled = ref(false)
const message = ref('尚未添加水印')
let watermark
const add = () => {
  watermark?.remove()
  watermark = $Watermark({
    id: target.value,
    text: '内部预览',
    fontSize: '20px',
    width: 220,
    height: 120,
    zIndex: 1
  })
  enabled.value = true
  message.value = '已添加：内部预览'
}
const repaint = () => {
  watermark?.Repaint({ text: '已审核', color: 'rgba(64,158,255,0.28)' })
  message.value = '已更新：已审核'
}
const remove = () => {
  watermark?.remove()
  watermark = undefined
  enabled.value = false
  message.value = '已移除水印'
}
onBeforeUnmount(() => watermark?.remove())
</script>

<style scoped>
.watermark-demo__actions { display: flex; flex-wrap: wrap; gap: 8px; margin-bottom: 16px; }
.watermark-demo__actions .el-button { margin-left: 0; }
.watermark-demo__paper { position: relative; overflow: hidden; min-height: 180px; padding: 20px; border: 1px solid var(--el-border-color); border-radius: 8px; }
.watermark-demo__paper p { line-height: 1.8; }
</style>

参数	默认值	说明
id	空字符串	HTMLElement 或元素 id；未传入时覆盖页面
text	avueJS	水印文字
width / height	400 / 200	单块水印尺寸，单位 px
fontSize	30px	字体大小，建议传带单位的字符串
fontStyle	Microsoft YaHei, sans-serif	字体
color	rgba(100,100,100,0.15)	文字颜色
degree	-20	旋转角度
zIndex	9999	水印覆盖层层级

Repaint 的 R 为大写。组件卸载时调用 remove()，会同时清理观察器。上传图片水印使用字段 canvasOption，见全局配置。

$Log 日志

import { $Log } from '@smallwei/avue'

$Log.capsule('订单', '保存成功', 'success')
$Log.primary('普通提示')
$Log.colorful([
  { text: '状态：', type: 'default' },
  { text: '成功', type: 'success' }
])

内置 default、primary、success、warning、danger 五种样式。日志输出到浏览器控制台。

查找、克隆与空值工具

效果预览可直接操作下方示例

对同一组数据执行查找，观察对象、下标、空值的实际返回结果。

正在加载示例…

<template>
  <div class="utility-demo">
    <p>源数据：[{ prop: 'name' }, { prop: 'status' }]</p>
    <div class="utility-demo__actions">
      <el-button type="primary" @click="run">重新计算</el-button>
      <el-switch v-model="returnIndex" active-text="返回下标" inactive-text="返回对象" @change="run" />
    </div>
    <pre aria-live="polite">{{ result }}</pre>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { findArray, findNode, validData, validatenull, isJson } from '@smallwei/avue'

const returnIndex = ref(false)
const result = ref('')
const run = () => {
  const list = [{ prop: 'name' }, { prop: 'status' }]
  const tree = [{ id: 1, nodes: [{ id: 2, label: '研发' }] }]
  result.value = JSON.stringify({
    findArray: findArray(list, 'status', 'prop', returnIndex.value),
    findNode: findNode(tree, { value: 'id', children: 'nodes' }, 2),
    falseWithFallback: validData(false, true),
    emptyArray: validatenull([]),
    zeroIsEmpty: validatenull(0),
    jsonStringIsObject: isJson('{"name":"张三"}')
  }, null, 2)
}
run()
</script>

<style scoped>
.utility-demo__actions { display: flex; flex-wrap: wrap; gap: 16px; align-items: center; }
.utility-demo pre { margin-top: 16px; padding: 16px; overflow: auto; background: var(--el-fill-color-light); border-radius: 8px; line-height: 1.6; }
</style>

方法	返回值与规则
deepClone(data)	深拷贝，基于 lodash cloneDeep；修改副本不会修改原对象
findArray(list, value, valueKey = 'value', index = false)	默认返回匹配的对象，未找到为 undefined；第四参为 true 才返回下标，未找到为 -1；使用宽松比较
findNode(list, props, value)	递归查找树节点；props.value 默认 value、props.children 默认 children；严格比较字段值
findObject(list, value, prop = 'prop')	按字段标识查找配置，也检查分组的 column 及 dynamic/table 子配置；返回找到的配置引用
validatenull(value)	判断空字符串、null、undefined、空数组、无可枚举属性对象以及字符串 'null' / 'undefined'；数字、布尔值和 Date 不算空
validData(value, fallback)	空值取 fallback，保留 false、0 等有效值
isJson(value)	判断对象或首项为对象的数组；不解析 JSON 字符串
randomId()	返回 16 位大小写字母串，可作临时 UI 标识；不要在每次分页刷新时重新生成记录的 rowKey

import { findArray, findNode, findObject, validData, isJson } from '@smallwei/avue'

const list = [{ prop: 'name' }, { prop: 'status' }]
findArray(list, 'status', 'prop')       // { prop: 'status' }
findArray(list, 'status', 'prop', true) // 1
findArray(list, 'missing', 'prop', true) // -1

const tree = [{ id: 1, nodes: [{ id: 2, label: '研发' }] }]
findNode(tree, { value: 'id', children: 'nodes' }, 2) // { id: 2, label: '研发' }
findNode(tree, { value: 'id', children: 'nodes' }, '2') // undefined
findObject(list, 'name') // 返回 list[0]，可直接修改其配置
validData(false, true) // false
isJson('{"name":"张三"}') // false

文件、资源与尺寸工具

方法	用法和边界
dataURLtoFile(dataURL, filename)	将含 Base64 数据的 Data URL 转为 File，浏览器环境使用
downFile(urlOrBlob, saveName)	点击下载链接；不返回 Promise，也不负责请求远程文件或检查下载完成
loadScript(type, url, dom = 'body')	type 为 js / css，dom 为 head / body；加载成功后 resolve
setPx(value, fallback = '')	数值或数字字符串追加 px，含 % 的字符串保留，空值先取 fallback

import { downFile, loadScript, setPx } from '@smallwei/avue'

downFile(new Blob(['订单 A001'], { type: 'text/plain;charset=utf-8' }), '订单.txt')
await loadScript('js', '/vendor/Sortable.min.js')
setPx(24)     // '24px'
setPx('100%') // '100%'
setPx(null, 16) // '16px'

当前 setPx 只识别百分比；传 '24px' 会得到 '24pxpx'，传 '2rem' 同样会继续拼接 px。因此已有单位的 CSS 字符串应直接使用。loadScript 当前未实现网络失败的 reject，需处理错误的业务资源加载建议自行封装加载器。

配置校验工具

validateOption(option, component) 返回 { path, message }[]，warnOption(warnings, component) 向控制台打印并去重。完整规则、开关和交互示例见Option 配置校验。