Fieldset 字段集
Fieldset 现在同时支持两类用法：展示基础的Fieldset.Legend/ Fieldset.Label组合写法，也补上更适合表单场景的结构化 props 与 Fieldset.Item。
何时使用
- 需要把一组相关输入控件组织成一个明确的表单区块。
- 需要同时表达标题、说明、字段提示、操作区和错误态。
- 希望小表单走结构化 props，大表单展示基础 JSX 组合写法。
# 推荐写法
legend / description / items / hint / actions 适合直接搭表单区块。
# Fieldset.Item 复合字段
当字段布局更复杂时，可以用 children 组合，但把重复行收敛到 Fieldset.Item。
# 尺寸与状态
size 管信息密度，invalid 管容器错误态；原生 disabled 仍透传给 fieldset。
# Fieldset fieldset-legend and label
基础示例保持不变，展示最轻量的组合写法。
# Fieldset with background and border
展示手动 className 覆盖方式，和新 variant 可以自由混用。
# Fieldset with multiple inputs
基础多输入框示例保持，适合对比 items 写法和纯 JSX 写法。
# Fieldset with multiple join items
基础 join 场景保持，适合放紧凑操作条或搜索表单。
# Login form with fieldset
登录表单示例展示，能直接对照推荐结构。
API
当前页面展示的是语义化的完整可用 API，同时展示基础 children 组合写法。
Fieldset
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
legend | 推荐写法的标题内容；未传 children 时会自动渲染到 Fieldset.Legend | any | - |
description | 标题下方的说明文本 | any | - |
items | 数据驱动字段项，内部自动映射为 Fieldset.Item | ReadonlyArray<FieldsetItemData> | [] |
content | 自定义主体内容；适合放复杂布局 | any | - |
hint | 底部提示文本 | any | - |
actions | 底部操作区，默认右对齐 | any | - |
variant | 容器表现层，使用 Rue 当前视觉风格 | 'default' | 'soft' | 'outlined' | 'default' |
tone | 容器主题色，主要影响 soft / outlined 分支 | 'default' | 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'error' | 'default' |
size | 控制字段间距和说明文字密度，支持语义别名 | 'sm' | 'md' | 'lg' | 'small' | 'middle' | 'medium' | 'large' | 'md' |
bordered | 默认分支下快速补一层边框和内边距 | boolean | false |
invalid | 错误态容器，输出错误色并补 aria-invalid | boolean | false |
Fieldset.Item
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
label | 字段标题 | any | - |
description | 字段标题下的补充说明 | any | - |
control | 字段控件内容；不传时回退到 children | any | - |
hint | 字段底部提示，可用于校验说明 | any | - |
required | 显示“必填”标识 | boolean | false |
optional | 显示“可选”标识 | boolean | false |
horizontal | 切换为左右两列的字段布局 | boolean | false |
invalid | 字段级错误态，会把标题和提示切成错误色 | boolean | false |
复合子组件
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
Fieldset.Legend | 展示基础 legend 组合写法，并支持 aside 右侧辅助信息 | component | - |
Fieldset.Label | 支持 label / p / span / div 与 tone | component | - |
Fieldset.Item | 复合字段项，适合复用字段布局与提示文案 | component | - |
推荐用法总结
legend + items适合直接搭一整块表单Fieldset.Item适合沉淀复用字段行children + Legend/Label支持基础写法variant / tone / invalid用来表达区块层级和状态FAQ
结构化 props 和 children 可以同时用吗？
当前组件里，children仍然是最高优先级。想走推荐写法时使用legend、description、items；想自由拼装时继续直接写 children。
什么时候该用 items，什么时候该用 Fieldset.Item？
简单表单优先用items，这样信息更集中；字段布局开始变复杂、需要横向排版或局部复用时， 更适合切到 Fieldset.Item。
variant 和手写 className 会冲突吗？
不会。variant只是给出一套推荐容器样式，仍然可以继续叠加当前的rounded-box、border、bg-*等类名做局部覆盖。