快速上手

本页从安装到运行一个表单、一个表格，演示 Avue 最基本的配置方式。示例使用 Vue 3、Element Plus 和 Avue 3.9.5，适合已有的 Vue 3 项目。

1. 安装依赖

在项目根目录执行下面的命令。已有 Vue 3 项目无需重新创建项目。

npm install @smallwei/avue element-plus @element-plus/icons-vue axios

使用 pnpm 的项目可执行对应命令：

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

版本选择

这里是 Vue 3 版本的文档。Vue 2 项目请使用 2.x 文档。升级已有项目时，先阅读更新日志，并保留项目使用的包管理器和锁文件。

2. 在入口文件注册

在 src/main.js 中引入组件库和样式，最后挂载应用。项目已创建 app 时，将注册代码加到现有的 app.mount() 之前。

import { createApp } from 'vue'
import App from './App.vue'
import ElementPlus from 'element-plus'
import zhCn from 'element-plus/es/locale/lang/zh-cn'
import * as ElementPlusIconsVue from '@element-plus/icons-vue'
import Avue from '@smallwei/avue'
import axios from 'axios'
import 'element-plus/dist/index.css'
import '@smallwei/avue/lib/index.css'

const app = createApp(App)

for (const [name, component] of Object.entries(ElementPlusIconsVue)) {
  app.component(name, component)
}

app.use(ElementPlus, { locale: zhCn })
app.use(Avue, { axios })
app.mount('#app')

axios 用于远程字典、上传等功能。如果项目已有请求实例，可把它传入 app.use(Avue, { axios: request })；该实例应保留 Axios 的 response.data 包装。字典内部先取 response.data，再调用字段的 dicFormatter；已经解包响应的业务实例应另做适配或使用独立实例，参见全局配置和数据字典。

3. 创建第一个表单

把下面示例的源码复制到 src/App.vue，按项目原有脚本启动开发服务。输入姓名、选择岗位后点击“提交”，下方会显示提交结果；姓名为空时会显示校验提示。

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

v-model 保存字段值；option.column 定义字段；每列的 prop 与数据对象的键对应。示例只处理本地数据，可以直接运行。

正在加载示例…

<template>
  <avue-form v-model="form" :option="option" @submit="handleSubmit" />
  <div class="installation-result" role="status" aria-live="polite">
    <strong>最近一次提交</strong>
    <pre>{{ submitted ? JSON.stringify(submitted, null, 2) : '填写姓名后点击提交，查看实际提交的数据。' }}</pre>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const form = ref({ name: '', role: 'developer' })
const submitted = ref(null)
const option = {
  labelWidth: 80,
  span: 24,
  column: [
    {
      label: '姓名',
      prop: 'name',
      rules: [{ required: true, message: '请输入姓名', trigger: 'blur' }]
    },
    {
      label: '岗位',
      prop: 'role',
      type: 'select',
      dicData: [
        { label: '开发', value: 'developer' },
        { label: '设计', value: 'designer' }
      ]
    }
  ]
}

const handleSubmit = (values, done) => {
  submitted.value = { ...values }
  done()
}
</script>

<style scoped>
.installation-result {
  padding: 14px 16px;
  border: 1px solid var(--el-border-color-lighter);
  border-radius: 8px;
  background: var(--el-fill-color-light);
}
.installation-result pre {
  margin: 8px 0 0;
  white-space: pre-wrap;
  overflow-wrap: anywhere;
  font-size: 13px;
}
</style>

配置	示例	作用
prop	name	绑定 form.name，同时作为字段标识
label	姓名	显示给用户的字段标题
type	select	指定控件类型，不填时使用输入框
dicData	岗位列表	下拉选项的标签和值
rules	必填规则	提交时校验输入

提交完成后结束 loading

submit 回调的第二个参数是 done。接入真实接口后，在请求完成的 finally 中调用它，确保成功和失败时都结束按钮 loading。示例同步保存本地结果，所以直接调用 done()。

4. 展示第一张表格

表格复用相同的 column 配置思路，使用 data 接收记录数组。本例展示静态数据和字典翻译；新增、编辑、删除的接入方式见 CRUD 方法。

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

rowKey 指向记录的唯一标识，字段的 prop 对应每条记录的属性。岗位值保存为字符串，因此字典的 value 也使用字符串。

正在加载示例…

<template>
  <avue-crud :data="data" :option="option" />
</template>

<script setup>
const data = [
  { id: 'member-01', name: '张三', role: 'developer' },
  { id: 'member-02', name: '李四', role: 'designer' }
]

const option = {
  rowKey: 'id',
  border: true,
  addBtn: false,
  menu: false,
  refreshBtn: false,
  columnBtn: false,
  column: [
    { label: '姓名', prop: 'name', minWidth: 120 },
    {
      label: '岗位',
      prop: 'role',
      type: 'select',
      minWidth: 120,
      dicData: [
        { label: '开发', value: 'developer' },
        { label: '设计', value: 'designer' }
      ]
    }
  ]
}
</script>

下一步

• 组件与依赖索引：按源码整理的组件标签、具名导出和功能依赖。
• 基础组件通用用法：独立组件与表单字段的属性、字典和事件差异。
• 表单配置：字段、布局和交互的完整入口。
• 表单联动：根据上级字段加载下级选项。
• 表格配置：分页、搜索、操作列和事件。
• 表格数据字典：静态字典、逐行字典和级联参数。

常见问题

组件未渲染或提示无法解析组件：检查 app.use(ElementPlus)、app.use(Avue) 是否在同一个应用的 app.mount() 之前执行。

控件没有样式：检查 Element Plus 和 Avue 的两个 CSS 文件是否都已引入。

下拉框显示原始值而不是标签：检查字段值与字典 value 的类型。字符串 '1' 与数字 1 不相等；通过字段的 dataType 或统一接口数据类型处理。

修改配置后数据未对应变化：检查 prop 是否与数据键一致，使用 Vue 的 ref / reactive 保存会更新的状态。字段配置负责界面，业务接口的调用和结果处理仍需在事件中实现。