QtShadcn
组件

ShadcnField

表单字段容器:组合 label / 控件 / 描述 / 错误提示,管间距与 orientation。

把「label + 控件 + 说明 + 错误」组合成一块的表单字段容器(shadcn field)。 Field 只管排版与间距,不含任何输入逻辑;输入控件由你自己放进去。

与 ShadcnInputGroup 的区别

管什么层级
ShadcnField多行之间:label / 控件 / 描述 / 错误的顺序与间距、必填标记、错误态配色字段外层
ShadcnInputGroup单个输入框内部:前后缀图标或文本、padding 让位字段内层

两者不冲突,正常用法是叠加:

ShadcnField {
    ShadcnFieldLabel { text: qsTr("搜索"); required: true }
    ShadcnInputGroup { prefixIcon: "search"; placeholderText: qsTr("关键词") }
    ShadcnFieldDescription { text: qsTr("支持正则") }
}

用法

纵向(默认)

ShadcnField {
    ShadcnFieldLabel { text: qsTr("用户名"); required: true }
    ShadcnInput { placeholderText: qsTr("小写字母与数字") }
    ShadcnFieldDescription { text: qsTr("创建后不可修改") }
}

横向(label 与控件同行)

ShadcnField {
    orientation: ShadcnField.Orientation.Horizontal
    ShadcnFieldLabel { text: qsTr("接收产品更新") }
    ShadcnSwitch { checked: true }
}

带描述时用 ShadcnFieldContent 把 label 与描述打包,描述就跟 label 同列、控件贴右:

ShadcnField {
    orientation: ShadcnField.Orientation.Horizontal
    ShadcnFieldContent {
        ShadcnFieldTitle { text: qsTr("飞行模式") }
        ShadcnFieldDescription { text: qsTr("关闭所有无线连接") }
    }
    ShadcnSwitch {}
}

错误态

ShadcnField {
    invalid: input.text.length === 0 && touched

    ShadcnFieldLabel { text: qsTr("邮箱"); required: true }
    ShadcnInput { id: input }
    ShadcnFieldError { text: qsTr("请输入有效的邮箱地址") }
}

invalid 会让 FieldLabel / FieldTitle 转成 destructive 色(等价官方 data-[invalid=true]:text-destructive)。Field 不会自己去问控件是否有效 —— 和官方一样,有效性只有业务知道,由调用方绑定。

多条错误(自动去重)

ShadcnFieldError { errors: model.errors }          // 字符串数组
ShadcnFieldError { errors: [{ message: "..." }] }  // 对象数组(react-hook-form 风格)

子组件

组件职责关键样式
ShadcnField字段容器(GridLayout),管 orientation 与间距gap-2(8px)
ShadcnFieldLabel字段标签,required 加红色星号text-sm / font-medium
ShadcnFieldTitle放在 FieldContent 里的标题(非可点击 label)text-sm / font-medium
ShadcnFieldDescription说明文字text-sm / mutedForeground
ShadcnFieldError错误提示,无内容不占位text-sm / destructive
ShadcnFieldContent横向时把 title + description 打包成一列gap-0.5(2px)
ShadcnFieldGroup多个 Field 的纵向分组,也是 responsive 的容器查询宿主gap-5(20px)
ShadcnFieldSet语义分组(Legend + Description + Group)gap-4(16px)
ShadcnFieldLegendFieldSet 标题,Legend(16px) / Label(14px) 两变体font-medium
ShadcnFieldSeparatorFieldGroup 内的分隔线,可带文字h-5,上下 -8px

属性

ShadcnField

属性类型默认说明
orientationenumVerticalVertical / Horizontal / Responsive
invalidboolfalse错误态:整块标签转 destructive
responsiveBreakpointint768Responsive 的切换阈值(px)

ShadcnFieldLabel

属性类型默认说明
textstring""标签文字
requiredboolfalse文字右侧追加 destructive *

ShadcnFieldError

属性类型默认说明
textstring""单条文案(优先于 errors)
errorsvar[]错误数组,string[] 或 { message }[]
messagesvar(只读)—去重后的最终条目

ShadcnFieldLegend

属性类型默认说明
variantenumLegendLegend(16px) / Label(14px)

布局注意

  • Field 的直接子项不要自己写 Layout.fillWidth —— 宽度由 Field 统一接管 (等价 CSS 的 *:w-full / *:w-auto),写了会被覆盖
  • 纵向时所有子项撑满宽度;横向时只有 FieldLabel / FieldContent 拉伸, 控件保持自然尺寸并贴右(*:w-auto)
  • 直接子项不要用裸 x / y,位置由 GridLayout 接管

Responsive 说明

Qt 没有 CSS 媒体查询/容器查询。这里用「容器宽度 >= 阈值」等价实现,宽度优先取 最近的 ShadcnFieldGroup(官方断点就挂在 @container/field-group 上),不在组里 则退回 Field 自身宽度。

官方 @md 断点是 768px,但 Qt 的 Field 常被放进 320~420px 的卡片里,照搬会让 Responsive 永远走纵向、等于没做,因此阈值开放成 responsiveBreakpoint 属性, 按容器实际宽度调小即可。

与官方 registry 的差异

核实自 base-nova/field.json(2026-11-17 抓取):

  • required 不是官方属性。官方 demo 里是手写 <FieldLabel>Required Field <span className="text-destructive">*</span></FieldLabel>, 本库收敛成 ShadcnFieldLabel.required 开关
  • FieldError 的 errors 去重:官方用 new Map(errors.map(e => [e.message, e])) 按 message 去重,去重后 1 条输出纯文本、多条输出 list-disc 列表 —— 已对齐
  • description 与 error 不互斥:官方没有互斥逻辑,两者各占一行。 需要注意 FieldDescription 自带 text-muted-foreground,因此 invalid 时 描述文字不会变红(只有继承 Field 颜色的元素会变),这是官方行为
  • FieldTitle 的 data-slot 在官方源码里也写成 field-label(疑似笔误), 因此 CSS 的 *:data-[slot=field-label]:flex-auto 会一并命中它 —— Qt 侧同样给 __fieldFlex = true,保持行为一致
  • FieldSet 的 has-[>[data-slot=checkbox-group]]:gap-3 分支未实现: 本库没有 checkbox-group / radio-group 的标记位,需要更紧的间距时直接设 spacing
  • cn-field-description 的 text-balance(横向时的平衡换行)Qt 无对应能力, 仅保留 WordWrap
  • Choice Card 玩法(把 Field 塞进 FieldLabel 做可选中卡片)未实现: 依赖官方 has-[>[data-slot=field]] 系列选择器与 :has() 组合,QML 无法表达

无障碍

  • ShadcnField → Accessible.Grouping(等价官方 role="group")
  • ShadcnFieldLabel / ShadcnFieldTitle → Accessible.name,必填时拼「(必填)」
  • ShadcnFieldError → Accessible.AlertMessage(等价官方 role="alert")
  • ShadcnFieldLegend → Accessible.Heading

相关

Copyright © 2026