Option 配置校验

validateOption 检查字段配置的结构，返回问题路径与说明。Form/CRUD 初始化时默认会打印这些警告，但不会自动修改配置，也不会阻止渲染。表单必填、格式和异步业务校验仍通过字段 rules 完成。

在线检查配置

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

点击“校验配置”查看问题，再点击“换成正确配置”对比结果。“应用到表单”仅在本示例没有警告时更新预览；这是示例的保护逻辑，不是 Avue 自动阻止渲染。

正在加载示例…

<template>
  <div class="option-check-demo">
    <div class="demo-actions">
      <el-button type="primary" @click="runValidate">校验配置</el-button>
      <el-button @click="useValid">换成正确配置</el-button>
      <el-button @click="useInvalid">恢复问题配置</el-button>
      <el-button @click="applyPreview">应用到表单</el-button>
    </div>
    <div class="validate-layout">
      <label class="option-editor">
        <span>待检查的 option（JSON）</span>
        <textarea v-model="optionText" spellcheck="false"></textarea>
      </label>
      <div>
        <p role="status">{{ message }}</p>
        <el-table :data="warnings" border size="small" empty-text="未发现配置警告">
          <el-table-column prop="path" label="路径" min-width="150" />
          <el-table-column prop="message" label="说明" min-width="170" />
        </el-table>
        <p>已应用的表单预览</p>
        <avue-form :key="previewKey" v-model="form" :option="previewOption" />
      </div>
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { validateOption } from '@smallwei/avue'

const invalidOption = {
  span: 30,
  column: [
    { label: '姓名', prop: 'name', rules: { required: true, message: '请输入姓名' } },
    { label: '重复姓名', prop: 'name' },
    { label: '部门', prop: 'dept', type: 'select', props: 'bad-props' },
    { prop: 'remark', span: 25 }
  ]
}
const validOption = {
  labelWidth: 80,
  menuBtn: false,
  column: [
    { label: '姓名', prop: 'name', span: 24, rules: [{ required: true, message: '请输入姓名', trigger: 'blur' }] },
    { label: '备注', prop: 'remark', type: 'textarea', span: 24 }
  ]
}
const optionText = ref(JSON.stringify(invalidOption, null, 2))
const warnings = ref([])
const message = ref('')
const form = ref({})
const previewKey = ref(0)
const previewOption = ref(validOption)
const runValidate = () => {
  try {
    const option = JSON.parse(optionText.value)
    warnings.value = validateOption(option, 'form')
    message.value = warnings.value.length ? '发现 ' + warnings.value.length + ' 项配置提示' : '配置检查通过'
    return option
  } catch (error) {
    warnings.value = [{ path: 'JSON', message: error.message }]
    message.value = 'JSON 解析失败，请先修正格式'
    return null
  }
}
const useValid = () => {
  optionText.value = JSON.stringify(validOption, null, 2)
  runValidate()
}
const useInvalid = () => {
  optionText.value = JSON.stringify(invalidOption, null, 2)
  runValidate()
}
const applyPreview = () => {
  const option = runValidate()
  if (!option || warnings.value.length) {
    message.value += '，预览保留上一次有效配置'
    return
  }
  previewOption.value = option
  form.value = {}
  previewKey.value += 1
  message.value = '配置检查通过，已应用到表单'
}
runValidate()
</script>

<style scoped>
.demo-actions { margin-bottom: 16px; display: flex; flex-wrap: wrap; gap: 8px; }
.demo-actions .el-button { margin-left: 0; }
.validate-layout { display: grid; grid-template-columns: minmax(0, 42%) minmax(0, 1fr); gap: 16px; }
.option-editor { min-width: 0; }
.option-editor span { display: block; margin-bottom: 8px; }
textarea { box-sizing: border-box; min-height: 360px; width: 100%; padding: 12px; border: 1px solid var(--el-border-color); border-radius: 6px; resize: vertical; font-family: Consolas, monospace; font-size: 13px; line-height: 1.55; }
textarea:focus { outline: 2px solid var(--el-color-primary); outline-offset: 2px; }
@media (max-width: 900px) { .validate-layout { grid-template-columns: 1fr; } }
</style>

自动检查开关

全局配置和页面配置都允许关闭；两个开关均未设为 false 时才自动检查。

// 全局关闭
app.use(Avue, { optionValidate: false })

// 仅关闭某页；optionValidate 放在 option 内
const option = {
  optionValidate: false,
  column: [{ label: '姓名', prop: 'name' }]
}

关闭的是自动警告。手动调用 validateOption 仍会返回结果。

手动检查

import { validateOption, warnOption } from '@smallwei/avue'

const option = {
  column: [
    { label: '姓名', prop: 'name' },
    { label: '重复姓名', prop: 'name' }
  ]
}
const warnings = validateOption(option, 'form')
// [{ path: 'form.column[1]', message: 'prop "name" 重复，已在 form.column[0] 出现' }]
warnOption(warnings, 'form')

方法	签名与行为
validateOption	(option = {}, component = 'component') => { path, message }[]
warnOption	(warnings = [], component = 'component') => void，按组件、路径、消息去重打印

第二个参数用于路径前缀与组件识别，通常传 'form'、'crud'、'search'；这三种名称还会检查是否缺少 column。

检查范围

配置	检查内容
option	必须是普通对象
column	数组或对象；对象写法会用键补充缺失的 prop
每个字段	必须是对象；prop 必填且不能重复
label	非 title 字段建议填写
span / searchSpan	全局及字段配置需在 1～24 之间
type	是否为源码已知字段类型；自定义组件可能出现提示
dicData、rules、cascader	存在时应为数组
props	存在时应为普通对象
group[].column	检查分组内字段
children.column	递归检查子表配置

配置检查不会请求字典接口、运行校验函数或验证权限。它也不覆盖所有组件参数的取值范围；“没有警告”不等于业务配置一定正确。

当前重复字段检查共享同一套 prop 记录，分组和子表里的同名字段也可能被提示。业务上确实需要重复名称或使用自定义组件时，先根据路径核实，再决定是否关闭该页面的自动警告。

源码位置

检查规则位于 src/core/option.ts，Form/CRUD 初始化开关位于 packages/core/common/init.ts。配置的公共类型 AvueOptionWarning 可直接从 @smallwei/avue 导入。