FormControl

基础表单

基于 Bootstrap 5 的表单控件组件，为 input、select、textarea 等元素提供统一的表单控件样式，支持尺寸、禁用、只读、只读纯文本、文件与颜色输入、数据列表及有效/无效校验状态，并配套 FormText 表单帮助文本组件

Component Demo

Basic usage and examples of the FormControl component

基础用法

尺寸

表单文本

密码

你的密码必须为 8-20 个字符，包含字母和数字，且不能包含空格、特殊字符或表情符号。

密码建议使用混合大小写字母与数字。

禁用状态

禁用的控件不可聚焦、不响应交互，且不会参与表单提交

只读

只读控件保留外观样式，可以聚焦但内容不可编辑

只读纯文本

使用 plaintext 属性可去除边框与背景，使控件看起来像普通文本

文件输入

默认文件输入示例

多文件输入示例

禁用文件输入示例

文件输入不支持尺寸类（form-control-sm / form-control-lg）

颜色输入

type 为 color 时自动附加 form-control-color 类

数据列表

校验状态

看起来不错！

请输入内容。

通过 isValid / isInvalid 属性应用 is-valid / is-invalid 校验样式，配合 FormFeedback 提供有效/无效反馈文本

交互演示

请输入邮箱地址

API Documentation

Complete API reference for the FormControl component

Props

Common Props

属性名	类型	默认值	描述
`as`	`ElementType`	`'input'`	渲染的根元素类型，可传入 `textarea`、`select` 或自定义组件以复用表单控件样式
`className`	`string`	-	自定义类名
`disabled`	`boolean`	-	是否禁用输入控件，禁用的控件不可聚焦且不参与表单提交
`htmlSize`	`number`	-	原生 `input` 的 `size` 属性，控制以字符为单位的可见宽度
`id`	`string`	-	原生 `id` 属性，用于与 `label` 的 `htmlFor` 关联
`isInvalid`	`boolean`	`false`	是否应用无效状态样式（`is-invalid`），通常配合校验反馈使用
`isValid`	`boolean`	`false`	是否应用有效状态样式（`is-valid`）
`plaintext`	`boolean`	`false`	是否渲染为只读纯文本样式（`form-control-plaintext`），去除边框与背景
`readOnly`	`boolean`	-	是否只读，只读控件可聚焦但不可编辑
`size`	`FormControlSize`	-	控件尺寸，可选 `sm`、`lg`，对应 `form-control-sm`、`form-control-lg`（不适用于文件输入）
`type`	`string`	-	原生 `input` 的 `type` 属性，如 `text`、`email`、`password`、`file`、`color` 等；为 `color` 时自动附加 `form-control-color`
`...rest`	`InputHTMLAttributes`	-	根元素的所有原生属性（如 `placeholder`、`value`、`onChange`、`list` 等）

FormText

属性名	类型	默认值	描述
`as`	`ElementType`	`'small'`	渲染的根元素类型，默认为 `small`，可传入 `div` 等以渲染块级文本
`children`	`ReactNode`	-	帮助文本内容
`className`	`string`	-	自定义类名
`muted`	`boolean`	`false`	是否应用静音文字颜色（`text-muted`）
`...rest`	`HTMLAttributes`	-	根元素的所有原生属性（如 `id`、`aria-*` 等）

Type Definitions

FormControlElement

表单控件元素类型

export type FormControlElement = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;

FormControlSize

表单控件尺寸类型

export type FormControlSize = 'lg' | 'sm';

FormControlProps

表单控件组件属性接口

export interface FormControlProps extends Omit<
  InputHTMLAttributes<HTMLInputElement>,
  'size' | 'type'
> {
  as?: ElementType;
  htmlSize?: number;
  isInvalid?: boolean;
  isValid?: boolean;
  plaintext?: boolean;
  size?: FormControlSize;
  type?: string;
}

FormTextProps

表单文本组件属性接口

export interface FormTextProps extends HTMLAttributes<HTMLElement> {
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  muted?: boolean;
}