表单变体（Form Variant）完全指南：Ant Design 四种形态一次掌握

• 前端
• UI组件
• 设计系统

表单输入控件的外观形态（variant）直接决定了表单的整体视觉风格。在 Ant Design 中，你可以通过<Form variant="...">这一个属性，让表单内所有组件的变体一次性切换为outlined（描边）、filled（填充）、borderless（无边框）或underlined（下划线）中的任意一种。本文以仓库中的官方演示 components/form/demo/variant.tsx 为核心，讲解四种变体的差异、表单级变体的实现原理、组件级覆盖方式以及旧版bordered属性的兼容迁移，读完即可在自己的项目中灵活控制表单视觉形态。

四种变体形态一览

官方演示文档 components/form/demo/variant.md 明确指出，表单内所有组件支持四种变体：

其中underlined变体是后起之秀，直到 5.24.0 才加入。这四种取值在源码中通过常量数组严格约束，定义于 components/config-provider/context.ts：

export const Variants = ['outlined', 'borderless', 'filled', 'underlined'] as const;

同时，Form的 API 文档（见 components/form/index.zh-CN.md）也给出了该属性的完整定义：

从默认值可见，Ant Design 表单组件的默认形态是outlined；只有当你显式传入variant属性时，表单的视觉风格才会整体改变。

官方演示解读：用 Segmented 实时切换全表单变体

仓库自带的可运行示例 components/form/demo/variant.tsx 演示了最典型的应用场景：用一个Segmented分段控件作为“变体选择器”，用户点选后，表单内全部控件立即联动切换形态。

import React from 'react'; import { Button, Cascader, DatePicker, Form, Input, InputNumber, Mentions, Segmented, Select, TreeSelect, } from 'antd'; const { RangePicker } = DatePicker; const formItemLayout = { labelCol: { xs: { span: 24 }, sm: { span: 6 } }, wrapperCol: { xs: { span: 24 }, sm: { span: 14 } }, }; const App: React.FC = () => { const [form] = Form.useForm(); const variant = Form.useWatch('variant', form); return ( <Form {...formItemLayout} form={form} variant={variant || 'filled'} style={{ maxWidth: 600 }} initialValues={{ variant: 'filled' }} > <Form.Item label="Form variant" name="variant"> <Segmented options={['outlined', 'filled', 'borderless', 'underlined']} /> </Form.Item> <Form.Item label="Input" name="Input" rules={[{ required: true, message: 'Please input!' }]}> <Input /> </Form.Item> <Form.Item label="InputNumber" name="InputNumber" rules={[{ required: true, message: 'Please input!' }]}> <InputNumber style={{ width: '100%' }} /> </Form.Item> <Form.Item label="TextArea" name="TextArea" rules={[{ required: true, message: 'Please input!' }]}> <Input.TextArea /> </Form.Item> <Form.Item label="Mentions" name="Mentions" rules={[{ required: true, message: 'Please input!' }]}> <Mentions /> </Form.Item> <Form.Item label="Select" name="Select" rules={[{ required: true, message: 'Please input!' }]}> <Select /> </Form.Item> <Form.Item label="Cascader" name="Cascader" rules={[{ required: true, message: 'Please input!' }]}> <Cascader /> </Form.Item> <Form.Item label="TreeSelect" name="TreeSelect" rules={[{ required: true, message: 'Please input!' }]}> <TreeSelect /> </Form.Item> <Form.Item label="DatePicker" name="DatePicker" rules={[{ required: true, message: 'Please input!' }]}> <DatePicker /> </Form.Item> <Form.Item label="RangePicker" name="RangePicker" rules={[{ required: true, message: 'Please input!' }]}> <RangePicker /> </Form.Item> <Form.Item label={null}> <Button type="primary" htmlType="submit"> Submit </Button> </Form.Item> </Form> ); }; export default App;

这个示例有三个值得注意的实战技巧：

1. 用Form.useWatch把“变体选择”本身做成一个表单字段：const variant = Form.useWatch('variant', form)实时监听名为variant的表单项的值，再把该值作为Form的variant属性传入。选择器自身位于Form.Item内部，却反过来控制整个表单的外观，形成一种“表单控制表单”的优雅闭环。
2. 兜底默认值：variant={variant || 'filled'}确保在字段值为空时回退到filled，避免因未选中任何变体导致外观回落到默认的outlined，造成视觉跳动。同时initialValues={{ variant: 'filled' }}让页面初始加载时就处于filled形态，体验一致。
3. 覆盖了绝大多数支持变体的控件：示例一口气放置了Input、InputNumber、TextArea、Mentions、Select、Cascader、TreeSelect、DatePicker、RangePicker九类输入控件，均带required必填校验（rules={[{ required: true, message: 'Please input!' }]}），直观验证了“表单级变体一次生效于全部组件”。

实现原理：VariantContext 向下渗透

表单级变体之所以能一次性作用于所有子组件，其底层依赖 React Context 的逐层传递。在 components/form/Form.tsx 中，variant作为FormProps的公开属性被接收，然后在渲染树根部通过VariantContext.Provider注入：

return ( <VariantContext.Provider value={variant}> <DisabledContextProvider disabled={disabled}> {/* ... */} <FieldForm ... /> </DisabledContextProvider> </VariantContext.Provider> );

VariantContext定义于 components/form/context.tsx：

export const VariantContext = React.createContext<Variant | undefined>(undefined);

当variant未传入时，Provider的 value 为undefined，子组件会继续向上查找ConfigProvider的全局配置或使用默认值outlined。

变体解析优先级：从源码看清合并规则

真正决定每个控件最终采用哪种变体的，是 components/form/hooks/useVariants.ts 中的useVariant钩子。包括Select（components/select/index.tsx）、Input（components/input/Input.tsx）、TextArea（components/input/TextArea.tsx）、Password（components/input/Password.tsx）、Search（components/input/Search.tsx）、OTP（components/input/OTP/index.tsx）等组件都复用了这一钩子。

其合并逻辑可归纳为一条优先级链（源码注释form variant > component global variant > fallback component global variant > global variant）：

1. 组件自身variant属性：优先级最高，显式传入即直接采用；
2. 旧版bordered={false}：作为兼容写法映射为borderless（详见下文）；
3. 表单级variant（VariantContext）：来自<Form variant="...">；
4. ConfigProvider组件级配置：例如ConfigProvider中select: { variant: 'filled' }；
5. ConfigProvider全局variant：对所有支持变体的组件生效；
6. 兜底默认值outlined。

if (typeof variant !== 'undefined') { mergedVariant = variant; } else if (legacyBordered === false) { mergedVariant = 'borderless'; } else { // form variant > component global variant > fallback component global variant > global variant mergedVariant = ctxVariant ?? configComponentVariant ?? configVariant ?? 'outlined'; }

支持变体的组件清单

从useVariants.ts的VariantComponents类型定义（components/form/hooks/useVariants.ts）可以确认，以下组件支持变体能力，并在表单级variant的辐射范围内：

• 输入类：input、inputPassword、inputSearch、textArea、otp、inputNumber
• 选择类：select、cascader、treeSelect、mentions
• 日期时间类：datePicker、timePicker、rangePicker
• 展示类：card（卡片同样支持variant）

其中Password、Search、OTP还声明了fallbackComponent（回退组件），例如Password回退到input、OTP回退到input，这意味着当组件级配置缺省时，它们会继承其回退组件的变体配置。

三种设置方式对比

根据上述优先级，你可以从三个层面设置变体，由局部到全局依次为：

方式一：组件级，作用于单个控件

<Form> <Form.Item name="username"> <Input variant="filled" /> </Form.Item> </Form>

方式二：表单级，作用于表单内全部控件（本演示的核心用法）

<Form variant="borderless"> {/* 内部所有 Input、Select、DatePicker 等控件均为 borderless */} </Form>

方式三：全局级，通过 ConfigProvider 作用于整个应用

<ConfigProvider variant="underlined" // 也支持按组件单独配置 input={{ variant: 'filled' }} select={{ variant: 'borderless' }} > <App /> </ConfigProvider>

全局variant属性定义于 components/config-provider/context.ts 的ConfigConsumerProps中。当表单级、组件级均未设置时，控件会一路向上继承ConfigProvider的全局形态——这正是大型应用统一视觉规范（例如全站统一为filled）的推荐做法。

旧版 bordered 属性的兼容与迁移

在variant方案引入之前，Ant Design 通过bordered={false}让控件变成无边框形态。useVariant钩子中专门保留了这段兼容逻辑（components/form/hooks/useVariants.ts 注释为 "Compatible for legacyborderedprop"）：

} else if (legacyBordered === false) { mergedVariant = 'borderless'; }

也就是说，bordered={false}会被自动映射为variant="borderless"，旧代码无需改动即可继续工作。但官方推荐新代码直接使用variant属性，因为bordered是历史遗留写法，且只能表达“有/无边框”两种状态，无法覆盖filled、underlined等更丰富的形态。同时注意，钩子还通过isVariantConfigured标记判断变体是否被显式配置，供样式模块决定是否启用变体类名（enableVariantCls，见 components/form/hooks/useVariants.ts），避免默认outlined场景下产生冗余的变体样式。

实战建议

1. 切换时避免空值回跳：若用表单字段驱动variant（如官方演示的做法），记得用|| 'filled'之类的兜底表达式，或保证字段有initialValues，防止未选中状态下视觉形态来回跳动。
2. 按需混用：表单级variant是默认基调，个别需要突出的字段（如搜索框）可再叠加组件级variant单独覆盖，实现“整体统一、局部差异”。
3. 关注underlined的版本门槛：underlined需要 5.24.0+，若项目版本较低，应只在下拉选项中提供前三项，或对underlined做降级处理。
4. 配合style控制布局：官方示例使用style={{ maxWidth: 600 }}约束表单宽度，labelCol/wrapperCol控制标签与控件占比（小屏xs下标签占满一行），可照搬这套formItemLayout以保证变体效果在窄屏下同样清晰可辨。

通过variant属性，你可以在不逐一修改每个控件的前提下，从outlined、filled、borderless、underlined四种形态中快速切换整套表单的视觉语言——无论是做主题换肤、表单风格统一，还是产品内的形态切换器，这套能力都能直接落地。

• 前端
• UI组件
• 设计系统