TypeScript 使用

Avue 3.9.5 在包内提供 types/index.d.ts，不需要额外安装 @types 包。声明覆盖安装配置、语言管理、公共插件和工具函数；Form/CRUD 的任意业务字段和组件实例方法仍需要项目自行定义。

安装与注册

pnpm add @smallwei/avue element-plus @element-plus/icons-vue axios

沿用快速上手的入口注册方式，在 main.ts 中可以直接导入配置类型：

import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import * as ElementPlusIconsVue from '@element-plus/icons-vue'
import Avue, { type AvueInstallOptions } from '@smallwei/avue'
import axios from 'axios'
import App from './App.vue'
import 'element-plus/dist/index.css'
import '@smallwei/avue/lib/index.css'

const options = {
  axios: axios.create({ baseURL: '/api' }),
  size: 'default',
  optionValidate: true,
  crudOption: { rowKey: 'id', border: true }
} satisfies AvueInstallOptions

const app = createApp(App)
for (const [name, component] of Object.entries(ElementPlusIconsVue)) {
  app.component(name, component)
}
app.use(ElementPlus)
app.use(Avue, options)
app.mount('#app')

保留项目已有的 Vue/Vite TypeScript 配置。不要重新声明一个只有 export default 的 declare module '@smallwei/avue' 来覆盖官方声明，否则会丢失下面的具名导出和全局属性类型。

可导入的公共类型

类别	类型
安装与组件导出	`AvueInstallOptions`、`AvuePlugin`、`AvueComponentExports`
上传与图片水印配置	`AvueCanvasOptions`、`AvueQiniuOptions`、`AvueAliOptions`
语言管理	`AvueLocale`、`AvueLocaleMessages`、`AvueLocaleInput`、`AvueLocalePrimitive`、`AvueTranslateHandler`
配置检查	`AvueOptionWarning`
弹窗、图片预览	`AvueDialogFormFactory`、`AvueDialogFormOpener`、`AvueImagePreviewFactory`、`AvueImagePreviewOpener`
复制、打印、截图	`AvueClipboardOptions`、`AvuePrintOptions`、`AvueScreenshotOptions`
页面水印	`AvueWatermarkOptions`、`AvueWatermarkInstance`
工具与插件集合	`AvueUtilityExports`、`AvuePluginExports`、`AvueExcelPlugin`

这些类型的配置中部分字段仍允许扩展；类型检查通过不代表所有拼写都被组件识别。Form/CRUD 配置可配合 validateOption 检查常见错误。

给业务数据和列定义类型

当前包没有导出完整的 AvueCrudOption<Row> 或 AvueFormInstance。下面的 UserColumn、UserOption 是项目本地类型，按自己的使用范围扩展即可：

import { ref } from 'vue'
import type { FormItemRule } from 'element-plus'

interface UserRow {
  id: number
  name: string
  status: 'enabled' | 'disabled'
}
interface UserColumn {
  label: string
  prop: keyof UserRow
  type?: 'input' | 'select'
  search?: boolean
  dicData?: Array<{ label: string; value: UserRow['status'] }>
  rules?: FormItemRule[]
}
interface UserOption {
  rowKey: keyof UserRow
  border?: boolean
  column: UserColumn[]
}

const rows = ref<UserRow[]>([
  { id: 1, name: '张三', status: 'enabled' }
])
const option = {
  rowKey: 'id',
  border: true,
  column: [
    { label: '姓名', prop: 'name', search: true },
    {
      label: '状态', prop: 'status', type: 'select',
      dicData: [
        { label: '启用', value: 'enabled' },
        { label: '停用', value: 'disabled' }
      ]
    }
  ]
} satisfies UserOption

使用 keyof UserRow 可以发现字段名拼错；字典值与业务字段使用相同的联合类型。可选字段、分组字段、动态子表按业务模型补充，避免用大范围 any 掩盖数据错误。

组件实例 ref

组件导出声明为 Vue 的 Component，当前不能据此获得完整的实例方法。为实际要调用的方法声明一个小接口，调用前等待组件挂载：

import { ref } from 'vue'

interface UserCrudHandle {
  rowAdd(): void
  rowEdit(row: UserRow, index: number): void
  rowView(row: UserRow, index: number): void
  toggleSelection(): void
}
const crudRef = ref<UserCrudHandle | null>(null)
const openCreate = () => crudRef.value?.rowAdd()

模板通过 <avue-crud ref="crudRef" ... /> 绑定。这里的 UserRow 沿用上一节定义；实际方法签名以 CRUD API 和 Form API 为准。带回调的方法不要仅为适应 await 而自行声明成 Promise。

插件的返回值与生命周期

import { onBeforeUnmount, ref } from 'vue'
import {
  $Clipboard, $Watermark, validateOption,
  type AvueClipboardOptions,
  type AvueWatermarkInstance,
  type AvueOptionWarning
} from '@smallwei/avue'

const panel = ref<HTMLElement | null>(null)
let watermark: AvueWatermarkInstance | undefined

const showWatermark = () => {
  if (!panel.value) return
  watermark?.remove()
  watermark = $Watermark({ id: panel.value, text: '内部预览' })
}
const copy = async () => {
  const options: AvueClipboardOptions = { text: 'A001', fallback: true }
  await $Clipboard(options)
}
const warnings: AvueOptionWarning[] = validateOption({
  column: [{ label: '姓名', prop: 'name' }]
}, 'form')
onBeforeUnmount(() => watermark?.remove())

$Clipboard 返回 Promise<void>，$Screenshot 返回 Promise<HTMLCanvasElement>，$Export.excel 和 $Export.xlsx 也有 Promise 结果类型。$DialogForm 的返回实例目前为宽类型；关闭方式和工厂绑定见全局 API。

Options API 的全局属性

声明文件已扩展 @vue/runtime-core 的 ComponentCustomProperties，包含 $AVUE、插件、工具函数、$axios、$uploadFun。在 defineComponent 内可以直接使用：

import { defineComponent } from 'vue'

export default defineComponent({
  methods: {
    async copyOrder() {
      await this.$Clipboard({ text: 'A001' })
    }
  }
})

$axios、$AVUE 和部分插件内部配置仍为宽类型。业务接口响应继续使用项目自己的请求类型，不应把它们当作端到端严格类型约束。

类型解析排查

先确认安装包里的 package.json 包含 types: "types/index.d.ts"，且实际安装的是预期版本；再检查项目的模块解析设置、工作区依赖位置和编辑器 TypeScript 服务。Vue 单文件组件交给项目已有的 Vue 类型检查工具处理。

手写完整模块声明会遮蔽官方导出；要增强业务提示，优先新增本地业务接口。文档中的安装命令不锁定版本，实际安装版本由项目锁文件决定。