YSchemaForm

适用范围：Legacy Admin Kit / Schema 与旧 admin-vue。新 admin-nuxtui 的开发入口见管理端 Nuxt UI 指南。

定位 / Owner

YSchemaForm 把稳定 Form IR field semantics 投影为 Admin Kit controls。标准 CRUD live field state 由 TanStack Form session 持有；SchemaForm 不是页面 DSL，也不拥有业务 workflow。

支持的默认 field kind

text、password、textarea、number、switch、select、multi-select、date、date-range。

remote-select、tree-select 或未知 kind 没有正式 field-<key> renderer slot 时 fail closed，不会静默降级成文本框。

基础用法

可运行示例

字段校验、只读与重置

清空方案名称后提交，再修正名称；切换只读或重置观察公开合同。

查看同源 Vue 代码

<script setup lang="ts">
import { ref } from 'vue'
import { YButton, YCheckbox, YSchemaForm } from '@yoyoboot/yoyo-admin-kit'

const initial = () => ({ code: 'DEMO-01', name: '示例方案', enabled: true })
const model = ref<Record<string, unknown>>(initial())
const readonly = ref(false)
const errors = ref<Record<string, string[]>>({})
const result = ref('尚未提交')
const schema = {
  id: 'docs-schema-form',
  fields: [
    { key: 'code', kind: 'text', label: '方案编号', lifecycle: { editableOn: 'never' } },
    { key: 'name', kind: 'text', label: '方案名称', required: true },
    { key: 'enabled', kind: 'switch', label: '启用方案' },
  ],
} as const
function submit() {
  errors.value = String(model.value.name ?? '').trim() ? {} : { name: ['请输入方案名称。'] }
  if (errors.value.name) return
  result.value = JSON.stringify(model.value)
}
function reset() {
  model.value = initial()
  errors.value = {}
  result.value = '尚未提交'
}
</script>

<template>
  <div class="grid gap-4">
    <YCheckbox v-model="readonly" label="只读预览" />
    <YSchemaForm v-model="model" :schema="schema" :errors="errors" :disabled="readonly" />
    <div class="flex gap-2">
      <YButton type="button" :disabled="readonly" @click="submit">提交演示表单</YButton>
      <YButton type="button" variant="outline" @click="reset">重置表单</YButton>
    </div>
    <p role="status">{{ result }}</p>
    <p>编号由 lifecycle 固定为只读；清空名称再提交可查看字段错误。此处只演示调用方提供 errors，不复制校验引擎或业务接口。</p>
  </div>
</template>

运行与源码展示来自同一文件，只消费公开 Kit。真实消费者是 Admin Vue 标准管理编辑器（src/shared/standard-management）；示例不调用业务 API。继续阅读 Authoring 与 外部消费，发布状态以版本说明为准。

<YSchemaForm
  v-model="form"
  :schema="{
    id: 'profile',
    fields: [
      { key: 'name', kind: 'text', label: '名称', required: true },
      { key: 'enabled', kind: 'switch', label: '启用' },
    ],
  }"
  :errors="fieldErrors"
/>

Public API

• v-model: Record<string, unknown>
• schema: { id, fields }
• errors: field-key → messages
• disabled
• mode: create | edit
• autofocusFirstError
• field-<key> slot：复杂或 feature-owned renderer extension

关键语义

• number: empty / valid numeric / invalid input 有明确 normalization/error contract。
• editableOn: create/edit/both/never 控制字段可编辑性。
• authoritative parent reset 会替换当前 baseline，不保留第二 record state。

不什么时候使用

• 不要把整个页面布局、业务步骤、网络请求、权限推断塞进 SchemaForm。
• 复杂 feature-specific editor 应通过正式 slot/extension 或独立 Application Composition。

Live Workbench

Admin Vue 稳定路径：

/frontend-module-demo/component-workbench/schema-form

该路径只标识 live scenario，不固化部署 Host；官方文档站与 Admin Vue 可以独立部署。

Verification / Source

• packages/yoyo-admin/admin-kit/src/ui/components/schema-form/YSchemaForm.vue
• tests/unit/ui/schema-form-semantic-kinds.spec.ts
• tests/unit/ui/schema-form-controlled-model.spec.ts
• Live Component Workbench