@composy/form-vue

@composy/form-vue

LDesign Form Vue 3 适配层 — 组件、组合式 API、指令和插件。

安装

npm install @composy/form-vue
# or
pnpm add @composy/form-vue

快速开始

<script setup>
import { LForm, LQueryForm, useForm } from '@composy/form-vue'

const { formData, validate, reset } = useForm({
  fields: [
    { name: 'name', label: '姓名', component: 'input', required: true },
    { name: 'email', label: '邮箱', component: 'input' },
  ],
})
</script>

<template>
  <LForm :fields="fields" v-model="formData" @submit="onSubmit" />
</template>

组件列表

Composable

import { useForm, useQueryForm, useFormField, useFormContext } from '@composy/form-vue'

// 创建表单实例
const { formData, validate, reset, submit } = useForm({ fields: [...] })

// 查询表单（支持展开/收起）
const queryForm = useQueryForm({
  fields: [...],
  layout: { maxCols: 4, previewRows: 2 },
})

// 字段级 composable
const { value, error, validate: validateField } = useFormField('fieldName')

// 表单上下文
const context = useFormContext()

动态选项

LForm 复用 Core 的 Options DataSource。字段配置 code、load 或 metadata.optionsSource 后，组件挂载时会自动加载选项；dependsOn 变化会取消旧请求并刷新下游字段。通过组件 ref 可以调用 loadOptions()、reloadOptions()、invalidateOptions() 和 subscribeOptions()，也可以监听 options-change 事件。

<LForm
  ref="formRef"
  v-model="formData"
  :options="[
    { name: 'country', control: 'select' },
    {
      name: 'city',
      control: 'select',
      dependsOn: ['country'],
      metadata: { optionsSource: { type: 'remote', load: loadCities } },
    },
  ]"
  @options-change="onOptionsChange"
/>

Control Registry 与 readonly

LForm 支持传入 Core 的 ControlRegistry，注册项可以提供 Vue renderer、model contract 和 readonly display formatter/renderer。字段级 controlDefinition / controlRegistry 的优先级高于表单级 registry。

import { createControlRegistry } from '@composy/form-core'

const registry = createControlRegistry()
registry.register('user-picker', {
  renderer: UserPicker,
  model: { valueProp: 'modelValue', changeEvent: 'update:modelValue' },
  display: value => value?.name ?? '-',
})

<LForm
  :registry="registry"
  :options="[{ name: 'owner', control: 'user-picker', label: '负责人' }]"
/>

只读字段渲染 display protocol，而不是 disabled input；内置 select、radio、checkbox 在提供 options 时展示选项 label。

指令

import { vFormField, vFormValidate } from '@composy/form-vue'

// v-form-field: 绑定字段值到输入控件
// v-form-validate: 触发字段校验

插件

import { createFormPlugin, createEngineFormPlugin } from '@composy/form-vue'

// Vue 插件 - 注册全局组件和指令
app.use(createFormPlugin({ registerComponents: true, registerDirectives: true }))

// Engine 插件 - 集成到 LDesign Engine
app.use(createEngineFormPlugin())

样式导入

import '@composy/form-vue/styles' // 完整样式
import '@composy/form-vue/styles/form.css' // 仅表单样式

构建产物

dist/index.js       # UMD bundle
dist/index.min.js   # Minified UMD
dist/index.css      # 样式
es/index.js         # ESM preserveModules
esm/index.js        # ESM preserveModules
lib/index.cjs       # CJS preserveModules
lib/package.json    # { "type": "commonjs" }

验证命令

构建配置位于 .ldesign/builder.config.ts，TypeScript 配置权威文件位于 .ldesign/tsconfig.json；tsconfig.json 与 tsconfig.cjs.json 是兼容入口。

pnpm type-check    # TypeScript 类型检查
pnpm build         # 构建产物
pnpm dev           # 通过 @composy/builder 监听构建
pnpm test:run      # 运行测试
pnpm lint:check    # ESLint 检查

Core 状态边界增强

Vue 适配层继续直接使用 Core 的 controller、store 和 options data source，不复制内部状态。useFormState(form, { selector }) 与 useFormField 收到的是 Core 的稳定状态通知；调用 getFieldConfig / getFields 得到的字段配置是隔离快照，适合用于 computed、调试面板和表单设计器。

动态 options 在 Vue 中可观察到 loading、error、items 和 aborted 结果，但 provider 的取消、缓存 key 和结果隔离由 Core 负责。字段依赖缺失会出现在 Core diagnostics 中，Vue 应用可以通过诊断订阅统一展示，而不需要在组件内重复解析依赖。

可访问性与精确订阅

LForm / LQueryForm 会生成稳定字段 DOM id，并关联 label、帮助文本和校验错误；组件 ref 暴露 focusField(name) 与 focusFirstError()。提交失败后的自动聚焦和滚动可通过 focusFirstErrorOnSubmit、scrollToFirstError 配置。

useFormState(form, { selector }) 直接桥接 Core 的 subscribeSelector；useFormField 使用字段级订阅，避免无关字段变更触发整表单状态计算。

<LForm
  id="profile-form"
  :focus-first-error-on-submit="true"
  :scroll-to-first-error="true"
  @submit="save"
/>