更新记录

0.1.0（2026-10-20） 下载此版本

• 初版 nax-form-render 动态表单渲染器：由 schema（JSON 字符串 / 字段数组 / 含 fields 的对象）渲染表单项，required 自动生成校验规则
• 内部组合 nax-form + nax-form-item，标签、错误展示、字段注册与校验链路与手写表单完全一致；字段增删由 nax-form-item 的 prop watch 自动注册/注销
• 支持 16 类控件：text / password / number-input / digit / tel / textarea / search / select / switch / radio / checkbox / checkbox-group / number / slider / rate / date / datetime / time / year-month / calendar / date-strip
• 控件类型为封闭枚举：受蒸汽模式渲染机制约束（模板编译期静态分析，h() / resolveComponent() 在 App 的 Vapor 模式不支持），渲染分支在源码内以 v-if / v-else-if 穷举；schema 出现枚举外的 type 时渲染可诊断提示而非静默空白
• 值回写统一走 :model-value + @update:model-value（v-for 内无法把 v-model 绑定到动态 key）。不用 @change 取值：各控件载荷不统一（nax-select / nax-datetime-picker 的 change 回传结构化数组/对象，nax-input / nax-textarea / nax-search 的 change 是「失焦且与聚焦时不同」语义）
• 端差异处理（#ifdef APP-ANDROID || APP-IOS || APP-HARMONY）：schema 解析读字段在 App 端走 UTSJSONObject API，Web / 小程序走字段访问
• 按控件类型分派初值：开关 false、多选 []、数字类取 min、其余空串，避免控件拿到类型不符的值
• nax-calendar 无 modelValue，值取 change 载荷的 result，初值走 default-date
• 弹层类控件（datetime-picker / calendar）清除时同步复位展示文案
• Methods：validate / validateField / resetFields / clearValidate / setSchema（运行时替换 schema 并保留同名字段已有值）/ getModel
• Events：update:modelValue / change（带 prop）/ confirm / open / close
• demo：pages/components/form-render

平台兼容性

uni-app x(4.25)

其他

nax-form-render

uni-app x 动态表单渲染器：由 schema（JSON 字符串 / 数组 / 对象）渲染出不同的表单项，校验规则同步生成。

依赖

基础用法

<nax-form-render
  ref="formRef"
  v-model="formValue"
  :schema="schema"
  @change="onChange"
></nax-form-render>

const schema = `[
  { "prop": "account", "label": "账号", "type": "text", "placeholder": "4-12 位", "required": true },
  { "prop": "role", "label": "角色", "type": "select", "required": true,
    "options": [ { "value": "dev", "label": "开发" }, { "value": "ops", "label": "运维" } ] },
  { "prop": "notify", "label": "接收通知", "type": "switch" }
]`

const formValue = ref({} as UTSJSONObject)
const formRef = ref(null as ComponentPublicInstance | null)

function onSubmit() {
  const p = formRef.value!.validate() as Promise<boolean>
  p.then((_ok : boolean) => {
    // 通过校验，读取值：formRef.value!.getModel()
  }).catch((_err : any | null) => {
    // 校验失败，字段错误已由 nax-form-item 展示
  })
}

schema 也可以传数组（[{...}]）或含 fields 数组的对象，三者在解析层等价。

控件类型

控件类型是封闭枚举——受 uni-app x 蒸汽模式渲染机制约束：模板在编译期静态分析，不支持运行期构造组件（h() / resolveComponent() 在 App 的 Vapor 模式均不支持），因此渲染分支在组件源码内以 v-if / v-else-if 穷举。新增类型需要修改组件源码，不能由 schema 引入任意组件。

schema 里出现枚举外的 type 时，该字段会渲染为可诊断的提示文案（而非静默空白），便于排查。

字段配置（schema）

date-strip 的 minDate / maxDate 只接受日期字符串（组件内只识别 Date 与字符串），传时间戳数字会静默失效。

Props

Events

Methods（ref）

setSchema 之后会自动 clearValidate，避免已移除字段的错误残留。

值回写与校验

• 控件统一用 :model-value + @update:model-value 回写，不使用 v-model：v-for 内无法把 v-model 绑定到动态 key。
• 之所以不用 @change 取值：各控件载荷不统一（例如 nax-select 的 change 回传的是选中项数组 [{value,label,index}]，nax-input 的 change 仅在失焦且内容变化时触发）。update:modelValue 才是统一的「值已变化」信号。
• 字段级校验无需手动触发：控件在值变化 / 失焦时回调 nax-form-item，规则里的 trigger 自动生效。

平台说明

• select / datetime-picker 在微信小程序端可映射模式会走微信系统弹层（v-model:show 不生效，点击内置触发条弹出）；datetime / month-day / time + 秒无法映射，保持自建弹层。详见各控件 readme。
• date-strip 的 minDate / maxDate 需传日期字符串（见上）。
• calendar 无内置触发条，组件自渲染触发条以驱动弹层显隐；其 @change 载荷为对象，组件取 result 字段作为值。

主题

通过 CSS 变量覆盖（沿用 nax-ui 主题体系）：