基础组件使用约定

本节适用于直接使用 avue-input、avue-select 等输入组件。它们与 avue-form 的 column 共用部分配置，但不负责表单字段注册、整表校验和字典初始化。

独立组件与 Form 列配置

场景	独立组件	Form / CRUD 列配置
绑定数据	v-model="value" 绑定一个字段	v-model="form" 绑定对象，column.prop 指定字段
本地字典	:dic="options"	dicData: options
字典键映射	:props="{ label: 'name', value: 'code' }"	props: { label: 'name', value: 'code' }
尺寸	size="small"	option.size 或 column.size
校验	由外层表单负责	column.rules 配置规则数组
输入事件	@change="onChange"	column.change: onChange
初始选值	初始化 v-model	初始化 form[prop] 或 column.value

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

左侧独立选择器与右侧 Form 字段使用同一份本地字典。分别切换选项，比较字段绑定值和 change 事件对象；数字 0 同样可选。

正在加载示例…

<template>
  <el-row :gutter="20">
    <el-col :xs="24" :md="12">
      <p>独立 Select：dic + v-model</p>
      <avue-select v-model="value" :dic="options" :column="{ prop: 'status', label: '状态' }" aria-label="独立状态选择" @change="onStandaloneChange" />
    </el-col>
    <el-col :xs="24" :md="12">
      <p>Form：column.dicData + form.status</p>
      <avue-form v-model="form" :option="option" />
    </el-col>
  </el-row>
  <pre>{{ JSON.stringify({ value, formValue: form.status, event }, null, 2) }}</pre>
</template>

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

const options = [{ label: '停用', value: 0 }, { label: '启用', value: 1 }];
const value = ref(0);
const form = ref({ status: 1 });
const event = ref(null);
function record(source, { value, column, item }) {
  event.value = { source, value, valueType: typeof value, prop: column.prop, item };
}
function onStandaloneChange(payload) {
  record('独立组件', payload);
}
const option = {
  menuBtn: false,
  labelWidth: 0,
  column: [{ label: '状态', prop: 'status', type: 'select', span: 24, dicData: options,
    change: (payload) => record('Form 字段', payload) }],
};
</script>

<style scoped>
pre {
  margin-top: 16px;
  padding: 16px;
  border-radius: 8px;
  background: var(--el-fill-color-light);
  font-family: Consolas, monospace;
  font-size: 13px;
  line-height: 1.6;
  white-space: pre-wrap;
  overflow-wrap: anywhere;
}
</style>

dicData 是 Form/CRUD 的配置名；独立组件使用 dic。独立组件不会因为设置普通 dicUrl 就自动执行 Form 的初始化请求，应在业务中请求后赋给 dic。Select 的远程搜索有独立流程，见 Select。

通用属性

以下是输入组件公共包装层的配置；是否显示清空、只读、尺寸等效果，还取决于具体组件页面列出的支持范围。

属性	类型	默认值	说明
modelValue / v-model	取决于控件	—	建议明确初始化为字符串、数字或数组
size	string	空字符串	large / default / small；空值交给 Element Plus 上下文处理
disabled	boolean	false	禁用组件
readonly	boolean	false	只读，适用于有只读交互的输入组件
placeholder	string	空字符串	独立组件不会自动按 Form 的 label 生成占位文字
clearable	boolean	true	有清空功能的组件可使用；禁用时关闭清空
dic	array	[]	字典数组；无需字典的组件不使用此项
props	object	见下表	字典键映射
column	object	{}	事件上下文；独立 Select 远程请求也从这里读取字典配置
tableData	object	{}	追加到公共事件对象的上下文，例如 row/index
dataType	string	—	string / number / array / json 等，按具体控件和值结构使用
separator	string	,	字符串形式多值的分隔符；OTP、Cascader 等有各自的用途

值类型

单选一般绑定与字典 value 类型一致的字符串或数字；多选、复选框、路径选择和范围选择建议初始化为数组。多值组件如果初始值为字符串，公共处理会保留字符串形式并按 separator 拼接；dataType: 'json' 输出 JSON 字符串。需要数组时使用 ref([])，不要用 ref('') 代替。

不要将整个字典对象作为普通单选值。使用 props.value 指定稳定编码，并让初始值与编码类型一致；只有控件明确支持的对象模式才传对象。

字典映射

属性	默认键	用途
props.label	label	显示文字
props.value	value	绑定值
props.children	children	树形子节点
props.disabled	disabled	选项是否禁用
props.desc	desc	选项辅助说明
props.groups	groups	Select 分组选项
props.leaf	leaf	懒加载的末级标记

props.res 用于 Form/CRUD 的网络字典响应提取；已经传给独立组件的 dic 应当是数组，不能用 props.res 代替这一步。

事件参数

公共 change 事件传对象，update:modelValue 才传最终绑定值。支持焦点事件的控件还会在 focus / blur / click 参数中包含原生 event。

const onChange = ({ value, column, dic, item, row, index }) => {
  // value 为新的字段值；row/index 仅在传入对应 tableData 时存在
};
const onFocus = ({ value, event, column }) => {};

item 是按当前字典和值查找的节点；没有匹配项时不要假定它存在，也不要将它当成所有多选节点的列表。初始化与外部赋值也可能触发公共 change，持久化操作建议放在显式提交中。

回调属性 :change="onChange" 和组件事件 @change="onChange" 会分别被执行，不要同时绑定同一段业务逻辑。Select 的 removeTag、Upload 回调、Switch 的 beforeChange 和 OTP 的 finish 等专用参数见各组件页面。

Form 实例和字段实例

const formRef = ref(null);
// mounted 或 nextTick 后
const elementForm = formRef.value?.$refs.form;
const fieldWrapper = formRef.value?.getPropRef('otp');
const otp = fieldWrapper?.$refs.temp;
otp?.focus(0);

getPropRef 返回字段包装实例；使用完全自定义字段插槽或字段未渲染时不一定存在。只调用具体组件明确提供的方法，原生 Element Plus 的方法不会自动成为所有 Avue 组件的方法。