Form 表單

LhForm 和 LhFormItem 提供模型綁定、必填校驗和欄位錯誤展示。

基礎用法

vue

<script setup lang="ts">
import { reactive, ref } from 'vue'
import { LhForm, LhFormItem, LhInput, LhButton, LhMessage } from '@lh-ui/vue3'

const formRef = ref()
const formModel = reactive({
  name: '',
  email: '',
})

const formRules = {
  name: [{ required: true, message: '请输入姓名' }],
  email: [{ required: true, message: '请输入邮箱' }],
}

async function submitForm() {
  const valid = await formRef.value.validate()
  if (valid) {
    LhMessage.success('提交成功')
    console.log('提交成功', formModel)
  }
}

function resetForm() {
  formRef.value?.resetFields()
}
</script>

<template>
  <LhForm ref="formRef" :model="formModel" :rules="formRules" label-width="80px">
    <LhFormItem prop="name" label="姓名" required>
      <LhInput v-model="formModel.name" placeholder="请输入姓名" />
    </LhFormItem>
    <LhFormItem prop="email" label="邮箱" required>
      <LhInput v-model="formModel.email" placeholder="请输入邮箱" />
    </LhFormItem>
    <LhFormItem>
      <LhButton type="primary" @click="submitForm">提交</LhButton>
      <LhButton plain @click="resetForm" style="margin-left: 8px">重置</LhButton>
    </LhFormItem>
  </LhForm>
</template>

vue

<script>
import { LhForm, LhFormItem, LhInput, LhButton, LhMessage } from '@lh-ui/vue3'

export default {
  components: { LhForm, LhFormItem, LhInput, LhButton },
  data() {
    return {
      formModel: { name: '', email: '' },
      formRules: {
        name: [{ required: true, message: '请输入姓名' }],
        email: [{ required: true, message: '请输入邮箱' }],
      },
    }
  },
  methods: {
    async submitForm() {
      const valid = await this.$refs.formRef.validate()
      if (valid) {
        LhMessage.success('提交成功')
        console.log('提交成功', this.formModel)
      }
    },
    resetForm() { this.$refs.formRef?.resetFields() },
  },
}
</script>

<template>
  <LhForm ref="formRef" :model="formModel" :rules="formRules" label-width="80px">
    <LhFormItem prop="name" label="姓名" required>
      <LhInput v-model="formModel.name" placeholder="请输入姓名" />
    </LhFormItem>
    <LhFormItem prop="email" label="邮箱" required>
      <LhInput v-model="formModel.email" placeholder="请输入邮箱" />
    </LhFormItem>
    <LhFormItem>
      <LhButton type="primary" @click="submitForm">提交</LhButton>
      <LhButton plain @click="resetForm">重置</LhButton>
    </LhFormItem>
  </LhForm>
</template>

自訂主題

表單可以套用自訂主題色。

vue

<script setup lang="ts">
import { reactive } from 'vue'
import { LhConfigProvider, LhForm, LhFormItem, LhInput, LhButton } from '@lh-ui/vue3'

const themeForm = reactive({ name: '' })
const cerblueTheme = {
  'primary-color': '#2B4C7C',
  'primary-color-hover': '#3D649E',
  'primary-color-bg': '#E8EDF3',
}
</script>

<template>
  <!-- 青花瓷主題 -->
  <LhConfigProvider :theme-vars="cerblueTheme">
    <LhForm :model="themeForm" label-width="80px">
      <LhFormItem label="姓名">
        <LhInput v-model="themeForm.name" />
      </LhFormItem>
      <LhFormItem>
        <LhButton type="primary">提交</LhButton>
      </LhFormItem>
    </LhForm>
  </LhConfigProvider>
</template>

vue

<script>
import { LhConfigProvider, LhForm, LhFormItem, LhInput, LhButton } from '@lh-ui/vue3'

export default {
  data() {
    return {
      themeForm: { name: '' },
      cerblueTheme: {
        'primary-color': '#2B4C7C',
        'primary-color-hover': '#3D649E',
        'primary-color-bg': '#E8EDF3',
      },
    }
  },
}
</script>

<template>
  <!-- 青花瓷主題 -->
  <LhConfigProvider :theme-vars="cerblueTheme">
    <LhForm :model="themeForm" label-width="80px">
      <LhFormItem label="姓名">
        <LhInput v-model="themeForm.name" />
      </LhFormItem>
      <LhFormItem>
        <LhButton type="primary">提交</LhButton>
      </LhFormItem>
    </LhForm>
  </LhConfigProvider>
</template>

國際化

vue

<script setup lang="ts">
import { reactive, ref } from 'vue'
import { LhConfigProvider, LhForm, LhFormItem, LhInput, LhButton } from '@lh-ui/vue3'
import { zhCN } from '@lh-ui/vue3'
import { enUS } from '@lh-ui/vue3'

const locale = ref('zh-CN')
const formModel = reactive({ name: '' })
</script>

<template>
  <!-- 國際化設定 -->
  <LhConfigProvider :locale="locale === 'zh-CN' ? zhCN : enUS">
    <LhForm :model="formModel" label-width="80px">
      <LhFormItem :label="locale === 'zh-CN' ? '姓名' : 'Name'">
        <LhInput v-model="formModel.name" :placeholder="locale === 'zh-CN' ? '请输入姓名' : 'Enter name'" />
      </LhFormItem>
      <LhFormItem>
        <LhButton type="primary">{{ locale === 'zh-CN' ? '提交' : 'Submit' }}</LhButton>
      </LhFormItem>
    </LhForm>
  </LhConfigProvider>
</template>

vue

<script>
import { LhConfigProvider, LhForm, LhFormItem, LhInput, LhButton } from '@lh-ui/vue3'
import { zhCN } from '@lh-ui/vue3'
import { enUS } from '@lh-ui/vue3'

export default {
  data() {
    return {
      locale: 'zh-CN',
      formModel: { name: '' },
      zhCN: zhCN,
      enUS: enUS,
    }
  },
}
</script>

<template>
  <!-- 國際化設定 -->
  <LhConfigProvider :locale="locale === 'zh-CN' ? zhCN : enUS">
    <LhForm :model="formModel" label-width="80px">
      <LhFormItem :label="locale === 'zh-CN' ? '姓名' : 'Name'">
        <LhInput v-model="formModel.name" :placeholder="locale === 'zh-CN' ? '请输入姓名' : 'Enter name'" />
      </LhFormItem>
      <LhFormItem>
        <LhButton type="primary">{{ locale === 'zh-CN' ? '提交' : 'Submit' }}</LhButton>
      </LhFormItem>
    </LhForm>
  </LhConfigProvider>
</template>

標籤位置與行內版面配置

label-position 切換標籤對齊（left / right / top）；inline 讓表單項水平排列。

vue

<script setup lang="ts">
import { reactive } from 'vue'
const fpModel = reactive({ name: '', city: '' })
</script>

<template>
  <LhForm :model="fpModel" label-position="top" inline>
    <LhFormItem prop="name" label="名称" required>
      <LhInput v-model="fpModel.name" />
    </LhFormItem>
    <LhFormItem prop="city" label="城市">
      <LhInput v-model="fpModel.city" />
    </LhFormItem>
  </LhForm>
</template>

vue

<script>
export default {
  data() {
    return {
      fpModel: { name: '', city: '' },
    }
  },
}
</script>

<template>
  <LhForm :model="fpModel" label-position="top" inline>
    <LhFormItem prop="name" label="名称" required>
      <LhInput v-model="fpModel.name" />
    </LhFormItem>
    <LhFormItem prop="city" label="城市">
      <LhInput v-model="fpModel.city" />
    </LhFormItem>
  </LhForm>
</template>

LhForm Props

屬性	說明	類型	預設值
model	表單資料物件	`{ [x: string]: unknown; }`	—
rules	欄位校驗規則	`{ [x: string]: LhFormRule[]; }`	—
labelPosition	標籤位置	`"left" \| "right" \| "top"`	`'right'`
labelWidth	標籤寬度	`string \| number`	—
inline	是否使用行內版面配置	`boolean`	`false`
sx	sx 快速版面配置屬性	`LhSxProps`	—

LhFormItem Props

屬性	說明	類型	預設值
prop	對應 model 的欄位路徑，支援 `user.name`	`string`	—
label	標籤文字	`string`	—
required	是否必填	`boolean`	`false`
rules	目前欄位的校驗規則，優先級高於 Form rules	`LhFormRule[]`	—

校驗規則

type LhFormRule = {
  required?: boolean
  message?: string
  validator?: (value: unknown, model: Record<string, unknown>) => string | undefined
}

LhForm 暴露 validate() 和 resetFields() 方法。

無障礙

LhFormItem 的錯誤文案帶 role="alert"，校驗失敗時螢幕閱讀器立即播報
內容區透過 aria-describedby 關聯錯誤文案，輔助技術可讀取「欄位 → 錯誤」的對應關係；無錯誤時關聯自動移除
表單控制項（Input / Select / Checkbox / Radio / Switch / Slider / InputNumber / DatePicker / TimePicker / Cascader）讀取所屬 LhFormItem 的校驗狀態，校驗失敗時在控制項上標記 aria-invalid，錯誤消除後自動移除；控制項放在 LhFormItem 之外時不受影響
必填兜底文案取自語言包 form.required（中文「此項為必填」），隨 ConfigProvider 語言切換；rules 裡的 message 優先級更高

類型定義

本元件對外匯出的 TypeScript 類型結構如下（自動提取自 packages/components/form/src/types.ts 與 @lh-ui/share/core/* 原始碼，點選各條目展開檢視完整定義；屬性說明見上方 Props 表）：

LhFormLabelPosition

export type LhFormLabelPosition = 'left' | 'right' | 'top'

LhFormProps

export interface LhFormProps {
  model: Record<string, unknown>
  rules?: Record<string, LhFormRule[]>
  labelPosition?: LhFormLabelPosition
  labelWidth?: string | number
  inline?: boolean
  /** sx 快速版面配置屬性 */
  sx?: LhSxProps
}

LhFormItemProps

export interface LhFormItemProps {
  prop?: string
  label?: string
  required?: boolean
  rules?: LhFormRule[]
}

LhFormRule _{（來自 @lh-ui/share/core/form）}

export interface LhFormRule {
  required?: boolean
  message?: string
  validator?: (value: unknown, model: Record<string, unknown>) => string | undefined
}

Form 表單 ​

基礎用法 ​

自訂主題 ​

國際化 ​

標籤位置與行內版面配置 ​

LhForm Props ​

LhFormItem Props ​

校驗規則 ​

無障礙 ​

類型定義 ​