更新记录

0.2.1（2026-09-28） 下载此版本

• 修复规则 trigger 不生效（用户反馈：设置 trigger: ['blur', 'change'] 后值已改动，错误提示仍不消失）：此前 nax-form 已提供字段校验入口但库内无消费方，nax-form-item 的控件插槽也无法挂载事件，字段级校验只能由业务侧手动调 validateField(prop, event) 触发
• nax-form-item 新增向插槽内表单控件提供字段级校验入口 naxFormItemValidate(event, value)；NaxFormState 新增 validateOneWithValue(prop, event, value)
• 控件驱动的校验使用控件传入的当前值而非读 model：业务侧 model 多在 @change / @blur 时才同步，读 model 会取到旧值，错误提示依然不消失
• 公共 validate() / validateField() 仍从 model 取值，快照与重置逻辑不变
• 全端一致（无条件编译差异）：Android / iOS / 鸿蒙 / Web / 小程序行为相同

0.2.0（2026-08-27） 下载此版本

• 新增 labelSize 标签字号属性：nax-form 表单级统一（空串跟随组件默认 15px），nax-form-item 可单项覆盖（空跟随 form）

0.1.8（2026-08-21） 下载此版本

• 修复 TypeError: root.getAny is not a function（Web 端用户反馈）：对象 props（model / rules / 规则项）在部分场景下不是真实 UTSJSONObject 实例（Web 普通/响应式对象、App 渲染层桥接等），getAny/set 方法丢失导致校验与快照全部失效。

平台兼容性

uni-app x(4.25)

其他

nax-form

uni-app x 表单 / 表单项，功能覆盖常用场景。

依赖

• nax-icon（表单项左右图标）
• nax-ui-theme（CSS 变量 --nax-*，安装时依赖 / 运行时弱依赖）

基础用法

<template>
  <nax-form ref="formRef" :model="form" :rules="rules" label-width="80" error-type="message">
    <nax-form-item label="姓名" prop="name" required>
      <nax-input v-model="form.name" border placeholder="请输入姓名"></nax-input>
    </nax-form-item>
    <nax-form-item label="简介" prop="intro">
      <nax-input v-model="form.intro" border placeholder="请输入简介"></nax-input>
    </nax-form-item>
  </nax-form>
  <nax-button type="primary" label="提交" @click="onSubmit"></nax-button>
</template>

<script setup lang="uts">
const formRef = ref(null)
const form = reactive({
  name: '',
  intro: ''
} as UTSJSONObject)

const rules = {
  name: [
    { required: true, message: '请输入姓名', trigger: ['blur', 'change'] }
  ],
  intro: [
    { min: 3, max: 50, message: '简介 3-50 字' }
  ]
} as UTSJSONObject

function onSubmit() {
  const comp = formRef.value
  if (comp == null) {
    return
  }
  // 通过 defineExpose 暴露的 validate
  comp.validate().then((_ok: boolean) => {
    uni.showToast({ title: '校验通过', icon: 'none' })
  }).catch((_err: any) => {
    // 字段错误已展示
  })
}
</script>

小程序端若对象里的函数规则被过滤，请在 onReady 中调用 setRules(rules)。

规则 trigger 对内置表单控件自动生效：控件在值变化时按 change、失焦时按 blur 触发本项校验，无需业务侧手动调用。已接入的控件：nax-input、nax-textarea、nax-search、nax-number-box、nax-checkbox（含 group）、nax-radio（含 group）、nax-switch、nax-rate、nax-slider、nax-calendar、nax-select、nax-datetime-picker、nax-upload。自定义控件可自行调用 validateField(prop, 'change') / validateField(prop, 'blur')。

nax-form Props

nax-form Methods（ref）

规则字段（常用）

未内置 validator 异步自定义函数（蒸汽模式 / 小程序传函数限制）；复杂逻辑可在提交前自行判断。

nax-form-item Props

插槽

主题

通过 CSS 变量覆盖：

平台说明

• 控件需自行 v-model 绑定到 model 字段；提交时调用 validate()。
• 内置表单控件的 trigger（blur / change）已自动联动，无需手动调 validateField；自定义控件可自行调用 validateField(prop, 'blur') / validateField(prop, 'change')。
• 字段级校验按控件当前值判定，不依赖业务侧 model 是否已同步（model 常在 @change / @blur 才写入）；validate() 提交校验仍以 model 为准，请在提交前保持 model 与控件值一致。