Field 表单字段

组合标签、控件与帮助文字，构成无障碍的表单字段。响应式字段在自身宽度至少 480vp 时把标签放在控件旁边——没有断点。

基础用法

SFieldSet() {
  SFieldLegend({ text: 'Profile' })
  SFieldDescription({ text: 'Fill in your public profile.' })
  SFieldGroup() {
    SField() {
      SFieldLabel({ text: 'Full name' })
      SInput({ placeholder: 'Evil Rabbit', value: this.name!! })
      SFieldDescription({ text: 'This appears on invoices and emails.' })
    }
    SField({ invalid: this.username.length < 3 }) {
      SFieldLabel({ text: 'Username' })
      SInput({ value: this.username!! })
      SFieldError({ text: this.username.length < 3 ? 'At least 3 characters.' : '' })
    }
  }
}

网页近似预览，真机效果以 HarmonyOS 渲染为准。

响应式

调整窗口大小（或收窄示例）——字段会测量自身宽度。

// label beside the control from 480vp of field width, stacked below
SField({ orientation: 'responsive' }) {
  SFieldContent() {
    SFieldLabel({ text: 'Name' })
    SFieldDescription({ text: 'Provide your full name for identification.' })
  }
  SInput({ placeholder: 'Evil Rabbit' })
}

网页近似预览，真机效果以 HarmonyOS 渲染为准。

横向

复选框、开关与标签在同一行。

SField({ orientation: 'horizontal' }) {
  SCheckbox({ checked: this.sync!! })
  SFieldLabel({ text: 'Sync across devices' })
}
SField({ orientation: 'horizontal' }) {
  SFieldContent() {
    SFieldLabel({ text: 'Multi-factor authentication' })
    SFieldDescription({ text: 'Enable MFA to secure your account.' })
  }
  SSwitch({ checked: this.mfa!! })
}

网页近似预览，真机效果以 HarmonyOS 渲染为准。

API

从组件库源码中的 @Param / @Event / @BuilderParam 声明自动提取。

SField

shadcn-vue 的 Field：标签、控件、描述与错误信息一起排布。

• vertical：纵向堆叠（flex-col gap-3）。
• horizontal：横向排列（flex-row items-center gap-3）；SFieldLabel / SFieldContent / 文本控件共享剩余宽度。
• responsive（默认）：测量自身宽度——宽度不小于 480vp 时并排，否则上下堆叠（相当于 shadcn 的 @md/field-group:flex-row 容器查询）。

属性	类型	默认值	说明
orientation	FieldOrientation FieldOrientation = 'vertical' | 'horizontal' | 'responsive'	'responsive'
invalid	boolean	false	错误外观：SFieldLabel 变为 destructive 颜色，SInput / STextarea 显示无效边框。
disabled	boolean	false	标签的禁用外观（透明度 50%）。

插槽: 子组件（尾随闭包）

SFieldLabel

字段的标签。字段无效时变为 destructive 颜色；横向字段中占据剩余宽度。

属性	类型	默认值	说明
text	ResourceStr	''
required	boolean	false

SFieldContent

将标签与描述组合在控件旁边（flex flex-1 flex-col gap-1.5）。

插槽: 子组件（尾随闭包）

SFieldDescription

辅助文字（text-muted-foreground text-sm）。

属性	类型	默认值	说明
text	ResourceStr	''

SFieldError

校验信息（text-destructive text-sm）。text 为空时不渲染任何内容。

属性	类型	默认值	说明
text	string	''

SFieldGroup

字段堆叠（flex w-full flex-col gap-7）。

插槽: 子组件（尾随闭包）

SFieldSet

字段的语义化分组，可选 SFieldLegend（flex flex-col gap-6）。

插槽: 子组件（尾随闭包）

SFieldLegend

SFieldSet 的标题：legend 为 text-base font-medium，label 为 text-sm font-medium。

属性	类型	默认值	说明
text	ResourceStr	''
variant	FieldLegendVariant FieldLegendVariant = 'legend' | 'label'	'legend'

SFieldSeparator

字段分组之间的水平分割线。

无属性。