Fluent UI Forms

Fluent UI Forms 是一份围绕 Fluent UI React v9 表单组件的知识库，介绍如何用微软设计语言构建表单。

一、用途与整体架构 Fluent UI React v9 提供了一套遵循微软设计语言的表单组件。与原生 HTML 表单的关键区别在于 Field 组件：它作为包装器，统一处理标签、校验消息、提示文本和必填标识。整体结构为 FluentProvider（主题上下文）→ 原生 <form> → Field（标签 + 校验 + 提示包装）→ Input / Textarea / Select / Combobox 等实际控件。Fluent 表单组件默认是受控组件，接受 value 和 onChange 属性，遵循标准 React 受控组件约定，因此可与任意状态管理或表单库集成。

二、主要组件与能力

1. Field：所有 Fluent 表单的基础。属性包括 label（标签文本或 JSX）、validationMessage（校验消息）、validationState（"error" | "warning" | "success" | "none"，控制图标与颜色）、hint（常驻帮助文本）、required（布尔值或字符串，字符串可覆盖默认必填文案）、orientation（"vertical" | "horizontal"）、size（"small" | "medium" | "large"）。注意 Field 本身不渲染输入控件，始终包裹子输入组件，因此可搭配 Input、Textarea、Combobox、Dropdown、DatePicker 或任意自定义输入组件。
2. Input：单行文本输入，支持 type（text/email/password/number/tel/url）、placeholder、contentBefore、contentAfter、appearance（outline/underline/filled-darker/filled-lighter）、size、disabled。其 onChange 回调接收 (event, data)，新值在 data.value 中，与原生 React 的 event.target.value 不同。
3. Textarea：多行文本输入，支持 resize（none/horizontal/vertical/both）、rows、appearance。
4. Select：原生 HTML select 的封装，使用 Fluent token 样式。
5. Combobox 与 Dropdown：用于更丰富的选择体验，支持过滤、多选和自定义渲染。Combobox 支持 freeform（允许输入不在选项中的文本）和 multiselect（多选）；Dropdown 类似但没有文本输入，是打开列表框的按钮。两者通过 onOptionSelect 获取 data.optionText。
6. Checkbox、RadioGroup/Radio、Switch：分别用于勾选、单选组和开关，onChange 分别提供 data.checked 或 data.value。
7. SpinButton、Slider、Rating：SpinButton 为带增减的数值输入（min/max/step）；Slider 为连续或离散范围；Rating 为星级评分输入（max）。
8. DatePicker 与 TimePicker：属于 compat 组件，用 v9 样式包装 v8 实现，需单独安装 @fluentui/react-datepicker-compat 和 @fluentui/react-timepicker-compat。DatePicker 使用 onSelectDate 和 formatDate；TimePicker 使用 selectedTime、onTimeChange、startHour、endHour、increment。

三、使用方式 安装核心包：npm install @fluentui/react-components；日期与时间组件需额外安装上述两个 compat 包。Field 的校验状态通过 validationState 控制：error 为红色图标与文字，warning 为黄色，success 为绿色，none 为无图标的中性文字。required 可传布尔值或自定义字符串（如 "(mandatory)"）。orientation 为 horizontal 时，标签以固定宽度列（通常 33%）渲染，输入占据剩余空间，适合设置类表单。

四、与表单库集成

1. Formik + Yup：安装 formik、yup（TypeScript 用户可装 @types/yup，Yup 自 v1 起自带类型）。核心模式是创建适配组件，用 useField(name) 获取 field 与 meta，将 meta.touched && meta.error 映射到 Field 的 validationState 与 validationMessage。注意 Formik 的 field.onChange 期望带 target.name 和 target.value 的 React 合成事件，而 Fluent Input 的 onChange 提供 (event, data)，需手动构造期望结构。Yup 用于定义校验 schema，如 min、email、matches、oneOf 等。
2. React Hook Form + Zod：安装 react-hook-form、@hookform/resolvers、zod。使用 Controller 组件桥接 RHF 与受控的 Fluent 组件，通过 zodResolver(schema) 设置解析器，将 errors 映射到 Field 的校验状态与消息。为减少样板代码，可创建泛型包装器 FluentControlledField，内部使用 useFormContext 与 Controller。

五、适用场景与限制 适用于在 React 项目中使用 Fluent UI v9 构建表单、需要统一标签与校验展示、或需要与 Formik/Yup、React Hook Form/Zod 集成的场景。资料中未提供关于收费、价格、平台支持范围、性能效果或具体使用步骤之外的额外信息。