# 输入框

- 页面: https://jiguang132.com/zh/resources/ant-design/docs/input
- 资源: Ant Design (https://jiguang132.com/zh/resources/ant-design.md)
- 全部指南: https://jiguang132.com/zh/resources/ant-design/docs.md

通过鼠标或键盘输入内容，是最基础的表单域的包装。


## 何时使用 {#when-to-use}

- 需要用户输入表单域内容时。
- 提供组合型输入框，带搜索的输入框，还可以进行大小选择。

## 代码演示 {#examples}


- 基本使用 · `basic`
- 三种大小 · `size`
- 形态变体 · `variant`



- 紧凑模式 · `compact-style`

- 搜索框 · `search-input`
- 搜索框 loading · `search-input-loading`
- 文本域 · `textarea`
- 适应文本高度的文本域 · `autosize-textarea`
- 一次性密码框 · `otp`
- 输入时格式化展示 · `tooltip`
- 前缀和后缀 · `presuffix`
- 密码框 · `password-input`
- 带移除图标 · `allowClear`
- 带字数提示 · `show-count`
- 定制计数能力 · `advance-count`
- 自定义状态 · `status`
- 聚焦 · `focus`
- 自定义语义结构的样式和类 · `style-class`






## API

通用属性参考：[通用属性](#jguang-common-props)

### Input

| 参数 | 说明 | 类型 | 默认值 | 版本 | [全局配置](/components/config-provider#component-config) |
| --- | --- | --- | --- | --- | --- |
| ~~addonAfter~~ | 带标签的 input，设置后置标签，请使用 Space.Compact 替换 | ReactNode | - |  | × |
| ~~addonBefore~~ | 带标签的 input，设置前置标签，请使用 Space.Compact 替换 | ReactNode | - |  | × |
| allowClear | 可以点击清除图标删除内容 | boolean \| { clearIcon: ReactNode, disabled?: boolean } | - | disabled: 6.4.0 | 5.15.0 |
| ~~bordered~~ | 是否有边框, 请使用 `variant` 替换 | boolean | true | 4.5.0 | × |
| classNames | 用于自定义组件内部各语义化结构的 class，支持对象或函数 | Record<[SemanticDOM](#semantic-input), string> \| (info: { props })=> Record<[SemanticDOM](#semantic-input), string> | - | 5.4.0 | 5.7.0 |
| count | 字符计数配置 | [CountConfig](#countconfig) | - | 5.10.0 | × |
| defaultValue | 输入框默认内容 | string | - |  | × |
| disabled | 是否禁用状态，默认为 false | boolean | false | - | × |
| id | 输入框的 id | string | - |  | × |
| maxLength | 最大长度 | number | - |  | × |
| prefix | 带有前缀图标的 input | ReactNode | - |  | × |
| showCount | 是否展示字数 | boolean \| { formatter: (info: { value: string, count: number, maxLength?: number }) => ReactNode } | false | 4.18.0 info.value: 4.23.0 | × |
| status | 设置校验状态 | 'error' \| 'warning' | - | 4.19.0 | × |
| styles | 用于自定义组件内部各语义化结构的行内 style，支持对象或函数 | Record<[SemanticDOM](#semantic-input), CSSProperties> \| (info: { props })=> Record<[SemanticDOM](#semantic-input), CSSProperties> | - | 5.4.0 | 5.7.0 |
| size | 控件大小。注：标准表单内的输入框大小限制为 `medium` | `large` \| `medium` \| `small` | - |  | × |
| suffix | 带有后缀图标的 input | ReactNode | - |  | × |
| type | 声明 input 类型，同原生 input 标签的 type 属性，见：[MDN](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#属性)(请直接使用 `Input.TextArea` 代替 `type="textarea"`) | string | `text` |  | × |
| value | 输入框内容 | string | - |  | × |
| variant | 形态变体 | `outlined` \| `borderless` \| `filled` \| `underlined` | `outlined` | 5.13.0 \| `underlined`: 5.24.0 | 5.19.0 |
| onChange | 输入框内容变化时的回调 | function(e) | - |  | × |
| onPressEnter | 按下回车的回调 | function(e) | - |  | × |
| onClear | 按下清除按钮的回调 | () => void | - | 5.20.0 | × |

> 如果 `Input` 在 `Form.Item` 内，并且 `Form.Item` 设置了 `id` 属性，则 `value` `defaultValue` 和 `id` 属性会被自动设置。

Input 的其他属性和 React 自带的 [input](https://zh-hans.react.dev/reference/react-dom/components/input) 一致。

#### CountConfig

```tsx
interface CountConfig {
  // 最大字符数，不同于原生 `maxLength`，超出后标红但不会截断
  max?: number;
  // 自定义字符计数，例如标准 emoji 长度大于 1，可以自定义计数策略将其改为 1
  strategy?: (value: string) => number;
  // 同 `showCount`
  show?: boolean | ((args: { value: string; count: number; maxLength?: number }) => ReactNode);
  // 当字符数超出 `count.max` 时的自定义裁剪逻辑，不配置时不进行裁剪
  exceedFormatter?: (value: string, config: { max: number }) => string;
}
```

### Input.TextArea

同 Input 属性，外加：

| 参数 | 说明 | 类型 | 默认值 | 版本 | [全局配置](/components/config-provider#component-config) |
| --- | --- | --- | --- | --- | --- |
| autoSize | 自适应内容高度，可设置为 true \| false 或对象：{ minRows: 2, maxRows: 6 } | boolean \| object | false |  | × |
| classNames | 用于自定义组件内部各语义化结构的 class，支持对象或函数 | Record<[SemanticDOM](#semantic-textarea), string> \| (info: { props })=> Record<[SemanticDOM](#semantic-textarea), string> | - | 5.4.0 | 5.15.0 |
| styles | 用于自定义组件内部各语义化结构的行内 style，支持对象或函数 | Record<[SemanticDOM](#semantic-textarea) , CSSProperties> \| (info: { props }) => Record<[SemanticDOM](#semantic-textarea) , CSSProperties> | - | 5.4.0 | 5.15.0 |

`Input.TextArea` 的其他属性和浏览器自带的 [textarea](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea) 一致。

### Input.Search

| 参数 | 说明 | 类型 | 默认值 | 版本 | [全局配置](/components/config-provider#component-config) |
| --- | --- | --- | --- | --- | --- |
| classNames | 用于自定义组件内部各语义化结构的 class，支持对象或函数 | Record<[SemanticDOM](#semantic-search), string> \| (info: { props })=> Record<[SemanticDOM](#semantic-search), string> | - | 6.0.0 | 6.0.0 |
| enterButton | 是否有确认按钮，可设为按钮文字。该属性会与 `addonAfter` 冲突。 | ReactNode | false |  | × |
| loading | 搜索 loading | boolean | false |  | × |
| onSearch | 点击搜索图标、清除图标，或按下回车键时的回调 | function(value, event, { source: "input" \| "clear" }) | - |  | × |
| styles | 用于自定义组件内部各语义化结构的行内 style，支持对象或函数 | Record<[SemanticDOM](#semantic-search) , CSSProperties> \| (info: { props }) => Record<[SemanticDOM](#semantic-search) , CSSProperties> | - | 6.0.0 | 6.0.0 |
| searchIcon | 自定义搜索图标 | ReactNode | - | 6.4.0 | 6.4.0 |
| variant | 形态变体 | `outlined` \| `borderless` \| `filled` \| `underlined` | `outlined` | 5.13.0 \| `underlined`: 5.24.0 | 6.6.0 |

其余属性和 Input 一致。

### Input.Password

| 参数 | 说明 | 类型 | 默认值 | 版本 | [全局配置](/components/config-provider#component-config) |
| --- | --- | --- | --- | --- | --- |
| classNames | 语义化结构 class | Record<[SemanticDOM](#semantic-password), string> | - | 5.4.0 | 6.4.0 |
| iconRender | 自定义切换按钮 | (visible) => ReactNode | (visible) => (visible ? &lt;EyeOutlined /> : &lt;EyeInvisibleOutlined />) | 4.3.0 | 6.4.0 |
| styles | 语义化结构 style | Record<[SemanticDOM](#semantic-password), CSSProperties> | - | 5.4.0 | 6.4.0 |
| variant | 形态变体 | `outlined` \| `borderless` \| `filled` \| `underlined` | `outlined` | 5.13.0 \| `underlined`: 5.24.0 | 6.6.0 |
| visibilityToggle | 是否显示切换按钮或者控制密码显隐 | boolean \| [VisibilityToggle](#visibilitytoggle) | true |  | × |

### Input.OTP

`5.16.0` 新增。

> 开发者注意事项：
>
> 当 `mask` 属性的类型为 string 时，我们强烈推荐接收单个字符或单个 emoji，如果传入多个字符或多个 emoji，则会在控制台抛出警告。

| 参数 | 说明 | 类型 | 默认值 | 版本 | [全局配置](/components/config-provider#component-config) |
| --- | --- | --- | --- | --- | --- |
| autoComplete | 输入元素的 autocomplete 属性，例如 `one-time-code` 可用于 OTP 自动填充 | string | - | 6.3.0 | × |
| classNames | 用于自定义组件内部各语义化结构的 class，支持对象或函数 | Record<[SemanticDOM](#semantic-otp), string> \| (info: { props })=> Record<[SemanticDOM](#semantic-otp), string> | - | 6.0.0 | 6.0.0 |
| defaultValue | 默认值 | string | - |  | × |
| disabled | 是否禁用 | boolean | false |  | × |
| formatter | 格式化展示，留空字段会被 ` ` 填充 | (value: string) => string | - |  | × |
| separator | 分隔符，在指定索引的输入框后渲染分隔符 | ReactNode \|((i: number) => ReactNode) | - | 5.24.0 | × |
| mask | 自定义展示，和 `formatter` 的区别是不会修改原始值 | boolean \| string | `false` | `5.17.0` | × |
| length | 输入元素数量 | number | 6 |  | × |
| status | 设置校验状态 | 'error' \| 'warning' | - |  | × |
| styles | 用于自定义组件内部各语义化结构的行内 style，支持对象或函数 | Record<[SemanticDOM](#semantic-otp) , CSSProperties> \| (info: { props }) => Record<[SemanticDOM](#semantic-otp) , CSSProperties> | - | 6.0.0 | 6.0.0 |
| size | 输入框大小 | `small` \| `medium` \| `large` | `medium` |  | × |
| variant | 形态变体 | `outlined` \| `borderless` \| `filled` \| `underlined` | `outlined` | `underlined`: 5.24.0 | 6.6.0 |
| value | 输入框内容 | string | - |  | × |
| onChange | 当输入框内容全部填充时触发回调 | (value: string) => void | - |  | × |
| onInput | 输入值变化时触发的回调 | (value: string[]) => void | - | `5.22.0` | × |

#### VisibilityToggle

| 参数            | 说明                      | 类型              | 默认值 | 版本   |
| --------------- | ------------------------- | ----------------- | ------ | ------ |
| tabIndex        | 设置切换按钮的 `tabIndex` | number            | 0      | 6.5.0  |
| visible         | 用于手动控制密码显隐      | boolean           | false  | 4.24.0 |
| onVisibleChange | 显隐密码的回调            | (visible) => void | -      | 4.24.0 |

#### Input Methods

| 名称 | 说明 | 参数 | 版本 |
| --- | --- | --- | --- |
| blur | 取消焦点 | - |  |
| focus | 获取焦点 | (option?: { preventScroll?: boolean, cursor?: 'start' \| 'end' \| 'all' }) | option - 4.10.0 |

## Semantic DOM

### Input {#semantic-input}

| 语义节点 | 原生说明 | 版本 |
| --- | --- | --- |
| `root` | 根元素，包含相对定位、行内块布局、宽度、最小宽度、内边距、颜色、字体、行高、圆角、过渡动画等输入框容器的基础样式 | — |
| `prefix` | 前缀的包裹元素，包含前缀内容的布局和样式 | — |
| `input` | 输入框元素，包含输入框的核心交互样式和文本输入相关的样式 | — |
| `suffix` | 后缀的包裹元素，包含后缀内容的布局和样式 | — |
| `clear` | 清除按钮元素，包含清除内容按钮的布局、显隐和交互样式 | 6.4.0 |
| `count` | 文字计数元素，包含字符计数显示的字体和颜色样式 | — |

语义说明来源: `vendor/components/input/demo/_semantic_input.tsx`

### Input.TextArea {#semantic-textarea}

| 语义节点 | 原生说明 | 版本 |
| --- | --- | --- |
| `root` | 根元素，设置文本域包装器的样式、边框、圆角、过渡动画和状态控制 | — |
| `textarea` | 文本域元素，设置字体、行高、内边距、颜色、背景、边框、文本输入和多行文本展示样式 | — |
| `clear` | 清除按钮元素，包含清除内容按钮的布局、显隐和交互样式 | 6.4.0 |
| `count` | 文字计数元素，设置字符计数显示的位置、字体、颜色和数值统计样式 | — |

语义说明来源: `vendor/components/input/demo/_semantic_textarea.tsx`

### Input.Search {#semantic-search}

| 语义节点 | 原生说明 | 版本 |
| --- | --- | --- |
| `root` | 根元素 | — |
| `prefix` | 前缀的包裹元素 | — |
| `input` | 输入框元素 | — |
| `suffix` | 后缀的包裹元素 | — |
| `clear` | 清除按钮元素 | 6.4.0 |
| `count` | 文字计数元素 | — |
| `button.root` | 按钮根元素 | — |
| `button.icon` | 按钮图标元素 | — |
| `button.content` | 按钮内容元素 | — |

语义说明来源: `vendor/components/input/demo/_semantic_search.tsx`

### Input.Password {#semantic-password}

| 语义节点 | 原生说明 | 版本 |
| --- | --- | --- |
| `root` | 根元素 | — |
| `prefix` | 前缀的包裹元素 | — |
| `input` | 输入框元素 | — |
| `suffix` | 后缀的包裹元素 | — |
| `clear` | 清除按钮元素 | 6.4.0 |
| `count` | 文字计数元素 | — |

语义说明来源: `vendor/components/input/demo/_semantic_password.tsx`

### Input.OTP {#semantic-otp}

| 语义节点 | 原生说明 | 版本 |
| --- | --- | --- |
| `root` | 根元素，设置行内flex布局、对齐方式、列间距和包装样式 | — |
| `input` | 输入框元素，设置文本居中、内边距和数字输入样式 | — |
| `separator` | 分隔符元素，设置OTP输入框之间的分隔符显示样式 | — |

语义说明来源: `vendor/components/input/demo/_semantic_otp.tsx`

## 主题变量（Design Token）{#design-token}

类型、继承关系和原生令牌声明保持固定源码原文；默认值由原生主题计算，并可能受 ConfigProvider 覆盖。本表不伪造静态默认值。

原生 ComponentToken 未声明可直接提取的自有字段；共享令牌或继承关系以以下声明为准。

声明来源: `vendor/components/input/style/token.ts`

```ts
import { mergeToken } from '../../theme/internal';

import type { AliasToken, FullToken } from '../../theme/internal';

export interface SharedComponentToken {
  /**
   * @desc 输入框横向内边距
   * @descEN Horizontal padding of input
   */
  paddingInline: number;
  /**
   * @desc 小号输入框横向内边距
   * @descEN Horizontal padding of small input
   */
  paddingInlineSM: number;
  /**
   * @desc 大号输入框横向内边距
   * @descEN Horizontal padding of large input
   */
  paddingInlineLG: number;
  /**
   * @desc 输入框纵向内边距
   * @descEN Vertical padding of input
   */
  paddingBlock: number;
  /**
   * @desc 小号输入框纵向内边距
   * @descEN Vertical padding of small input
   */
  paddingBlockSM: number;
  /**
   * @desc 大号输入框纵向内边距
   * @descEN Vertical padding of large input
   */
  paddingBlockLG: number;
  /**
   * @desc 前/后置标签背景色
   * @descEN Background color of addon
   */
  addonBg: string;
  /**
   * @desc 悬浮态边框色
   * @descEN Hover border color
   */
  hoverBorderColor: string;
  /**
   * @desc 激活态边框色
   * @descEN Active border color
   */
  activeBorderColor: string;
  /**
   * @desc 激活态阴影
   * @descEN Box-shadow when active
   */
  activeShadow: string;
  /**
   * @desc 错误状态时激活态阴影
   * @descEN Box-shadow when active in error status
   */
  errorActiveShadow: string;
  /**
   * @desc 警告状态时激活态阴影
   * @descEN Box-shadow when active in warning status
   */
  warningActiveShadow: string;
  /**
   * @desc 输入框hover状态时背景颜色
   * @descEN Background color when the input box hovers
   */
  hoverBg: string;
  /**
   * @desc 输入框激活状态时背景颜色
   * @descEN Background color when the input box is activated
   */
  activeBg: string;
  /**
   * @desc 字体大小
   * @descEN Font size
   */
  inputFontSize: number;
  /**
   * @desc 大号字体大小
   * @descEN Font size of large
   */
  inputFontSizeLG: number;
  /**
   * @desc 小号字体大小
   * @descEN Font size of small
   */
  inputFontSizeSM: number;
}

export interface ComponentToken extends SharedComponentToken {}

export interface SharedInputToken {
  inputAffixPadding: number;
}

export interface InputToken extends FullToken<'Input'>, SharedInputToken {}
```

## FAQ

### 为什么我动态改变 `prefix/suffix/showCount` 时，Input 会失去焦点？ {#faq-lose-focus}

当 Input 动态添加或者删除 `prefix/suffix/showCount` 时，React 会重新创建 DOM 结构而新的 input 是没有焦点的。你可以预设一个空的 `<span />` 来保持 DOM 结构不变：

```jsx
const suffix = condition ? <Icon type="smile" /> : <span />;

<Input suffix={suffix} />;
```

### 为何 TextArea 受控时，`value` 可以超过 `maxLength`？ {#faq-textarea-exceed-max}

受控时，组件应该按照受控内容展示，这是为了防止在表单组件内使用时显示值和提交值不一致的问题。


## 原生通用属性 {#jguang-common-props}


> Tips: 以下通用属性适用于 antd 大部分组件，不支持的组件会单独说明。

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| style | 自定义样式 | CSSProperties | - |
| className | 自定义类名 | string | - |
| rootClassName | 添加在组件最外层的 className | string | - |
| autoFocus | 自动获取焦点，仅对表单类、链接、交互容器等可聚焦元素生效 | boolean | false |


## 安装并复现示例

```bash
npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23
```

使用 ConfigProvider 和原生 App，并单独配置 dayjs 语言。每个示例在查看代码中列出完整源码文件和额外固定依赖。示例名称用于选择演示，不是组件通用属性。主题、语言与 SSR 初始化见资源安装指南。

## 原生类型参考

源码查看器包含未修改的原生实现和以下声明文件，继承类型仍位于原生包中。代码中的英文注释保留为源码参考。

- `vendor/components/input/Group.tsx`
- `vendor/components/input/Input.tsx`
- `vendor/components/input/OTP/OTPInput.tsx`
- `vendor/components/input/OTP/index.tsx`
- `vendor/components/input/Password.tsx`
- `vendor/components/input/Search.tsx`
- `vendor/components/input/TextArea.tsx`
- `vendor/components/input/index.tsx`
- `vendor/components/input/style/token.ts`

## 来源与许可

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

保留原生中英文正文与可执行示例；官网专用的嵌入章节和令牌表格在本地展开。Ant Design 使用 MIT 许可，另列依赖的许可证也需保留。上传预览禁止向外发起请求，不提供后端服务。

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt