shadcn-svelte Field 组件指南Svelte 5 里做出对齐、分组、读屏友好的表单【免费下载链接】shadcn-svelteshadcn/ui, but for Svelte. ✨项目地址: https://gitcode.com/GitHub_Trending/sh/shadcn-svelte标签对不齐、分组没有语义、读屏软件听不到校验错误——这是写基础表单的三个通病。shadcn-svelte Field 组件是一组可组合的表单字段组件用它能在 5 分钟内搭出专业且可访问的 Svelte 5 表单。一条命令安装 Field 并写出第一个表单字段 安装只需一条命令npx shadcn-sveltelatest add field。跑完后按命名空间导入一个字段立刻能跑起来script langts import * as Field from $lib/components/ui/field/index.js; import { Input } from $lib/components/ui/index.js; /script Field.Field Field.Label fornickname昵称/Field.Label Input idnickname placeholder请输入昵称 / /Field.Field整个家族共 10 个子组件源码集中在 docs/src/lib/registry/ui/field/ 目录速查如下组件渲染元素一句话职责Field.Fielddivrolegroup单个字段的包装器管纵向/横向布局Field.Setfieldset语义分组容器Field.Legendlegend分组标题Field.Groupdiv堆叠多个字段自带容器查询Field.Contentdiv标签 描述的弹性列Field.Labellabel字段标签for关联控件Field.Titlediv卡片式标题不参与表单关联Field.Descriptionp辅助说明文字Field.Errordivrolealert校验错误消息Field.Separatordiv字段之间的视觉分割线每个子组件都支持class覆盖样式、ref绑定 DOM并透传剩余原生属性后文代码默认依赖这一约定。用 3 个业务场景把核心组合学会 场景统一假设是「账号设置」页昵称、邮箱、订阅开关外加一个主题选择。场景一如何写出一个带说明的单个输入字段做什么给昵称输入框配一行辅助说明告诉用户它会显示在哪里。Field.Field Field.Label fornickname昵称/Field.Label Input idnickname autocompleteoff placeholder请输入昵称 / Field.Description会显示在你的个人主页和评论里/Field.Description /Field.Field关键原理Field.Field渲染为带rolegroup的div见 field.svelte默认垂直布局让子元素自动占满整行标签与控件的关联靠for/id完成组件只负责排版和语义外壳。场景二如何写出带 fieldset legend 语义的分组表单做什么把邮箱和订阅开关装进「账号设置」分组让读屏软件进入分组时先念出标题。Field.Set Field.Legend账号设置/Field.Legend Field.Description用于登录与产品更新通知/Field.Description Field.Group Field.Field Field.Label foremail邮箱/Field.Label Input idemail typeemail placeholderyouexample.com / /Field.Field Field.Field orientationhorizontal Switch idsubscribe / Field.Label forsubscribe订阅每周邮件/Field.Label /Field.Field /Field.Group /Field.Set关键原理Set和Legend渲染原生fieldset/legend——HTML 原生的分组标签读屏软件靠它识别表单分区分组边界与标题不靠任何 JavaScriptField.Group内建容器查询 按父容器宽度而不是屏幕宽度做布局决策这是后面响应式布局的地基。场景三如何把表单控件做成整卡可选的选择卡片做什么主题选择做成两张卡片点卡片任意位置都能选中对应的单选按钮。script langts import * as Field from $lib/components/ui/field/index.js; import * as RadioGroup from $lib/components/ui/radio-group/index.js; let theme $state(light); /script RadioGroup.Root bind:value{theme} Field.Label fortheme-light Field.Field orientationhorizontal Field.Content Field.Title浅色/Field.Title Field.Description白底适合白天使用/Field.Description /Field.Content RadioGroup.Item valuelight idtheme-light / /Field.Field /Field.Label Field.Label fortheme-dark Field.Field orientationhorizontal Field.Content Field.Title深色/Field.Title Field.Description黑底夜间更护眼/Field.Description /Field.Content RadioGroup.Item valuedark idtheme-dark / /Field.Field /Field.Label /RadioGroup.Root关键原理卡片内用Field.Title一个普通div而不是Field.Label——承担关联职责的是包住整张卡片的外层Field.Labelfor指向RadioGroup.Item内层再套label会让同一个控件被读屏软件念两遍。vertical / horizontal / responsive 三种布局怎么选 orientation只有三种取值覆盖响应式表单布局的常见需求选错只会让表单要么太空要么太挤你的场景推荐形态原因移动优先字段逐个堆叠vertical默认标签、控件、描述上下排列子元素占满整行桌面端并排、字段多的长表单orientationhorizontal标签和控件左右并排、垂直方向居中配合Field.Content对齐描述同一表单要进弹窗和整页两种容器orientationresponsive容器窄时纵向达到md/field-group断点自动横排不写媒体查询容器查询的原理一句话父容器够宽才切横向布局与屏幕尺寸无关——同一份表单塞进 400px 的侧边栏和放进整页表现会自动不同。Field.Group Field.Field orientationresponsive Field.Content Field.Label foremail邮箱/Field.Label Field.Description用于接收验证码与通知邮件/Field.Description /Field.Content Input idemail typeemail / /Field.Field /Field.Group让读屏软件念出表单错误的三层写法 ⚠️错误反馈拆给三个角色各管一层缺任何一层用户都会看不到或听不到标记写在哪负责什么data-invalidField.Field上视觉层整个字段块进入错误样式aria-invalid控件本身读屏层焦点落在控件上时播报无效Field.Error控件之后播报层渲染rolealert出错即时朗读Field.Field>Field.Set/Field.Legend输出原生fieldsetlegend键盘与读屏可按组导航Field.Field输出rolegroup嵌套控件继承组级标注Field.Error带rolealert错误即时播报Field.Error为空时不渲染无错误字段不留白你还要自己补的每个Field.Label写for且与控件id完全一致错误时给控件加aria-invalid——data-invalid只改样式读屏不认不用Field.Separator代替语义分组它只是一条视觉线常见坑表单里最容易翻车的 3 个细节for/id必须成对出现。两者不一致时点击标签不会聚焦输入框是纯手写表单最常见的隐形 bug水平布局里控件在标签之前如上面的订阅开关关联同样不能省。横排 描述要对齐靠Field.Content。字段里存在Field.Content时横排布局会自动从垂直居中切到顶部对齐复选框、单选框再上移 1px 对齐标签基线描述错位时先检查有没有用它包住标签和描述。Field.Separator克制使用。分割线对读屏没有语义插多了朗读节奏会被切碎它支持在中间放一段文字文字自动用背景色盖住线条但一个分组里一两条足够。Field 用原生 fieldset/legend 语义打底、容器查询管响应式、三层标记打通错误反馈——组合用对表单的专业感基本就到位了。更多控件组合可直接参考 示例目录完整 API 见 官方文档。【免费下载链接】shadcn-svelteshadcn/ui, but for Svelte. ✨项目地址: https://gitcode.com/GitHub_Trending/sh/shadcn-svelte创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
