# 文本字段

捕捉用户输入，并可选配按钮和图标的插槽。

```jsx
<TextField.Root placeholder="搜索文档…">
  <TextField.Slot>
    <MagnifyingGlassIcon height="16" width="16" />
  </TextField.Slot>
</TextField.Root>
```

## [API 参考](#api-参考)

### [根组件](#根组件)

将插槽和输入部分分组。该组件基于 `div` 元素，并支持 [常见的边距属性](/themes/docs/overview/layout#margin-props)。

| Prop      | Type                                                 | Default          |
| --------- | ---------------------------------------------------- | ---------------- |
| `size`    | `Responsive<"1" \| "2" \| "3">`                      | `"2"`            |
| `variant` | `"classic" \| "surface" \| "soft"`                   | `"surface"`      |
| `color`   | `enum`                                               | No default value |
| `radius`  | `"none" \| "small" \| "medium" \| "large" \| "full"` | No default value |

### [插槽](#插槽)

包含与输入相关的图标或按钮。

| Prop    | Type                         | Default          |
| ------- | ---------------------------- | ---------------- |
| `side`  | `"left" \| "right"`          | No default value |
| `color` | `enum`                       | No default value |
| `gap`   | `Responsive<enum \| string>` | No default value |
| `px`    | `Responsive<enum \| string>` | No default value |
| `pl`    | `Responsive<enum \| string>` | No default value |
| `pr`    | `Responsive<enum \| string>` | No default value |

## [示例](#示例)

### [尺寸](#尺寸)

使用 `size` 属性来控制大小。

```jsx
<Flex direction="column" gap="3">
  <Box maxWidth="200px">
    <TextField.Root size="1" placeholder="搜索文档…" />
  </Box>

  <Box maxWidth="250px">
    <TextField.Root size="2" placeholder="搜索文档…" />
  </Box>

  <Box maxWidth="300px">
    <TextField.Root size="3" placeholder="搜索文档…" />
  </Box>
</Flex>
```

在组合文本字段和按钮时，使用匹配的组件尺寸。然而，不要使用尺寸为 1 的输入框与按钮—在这个尺寸下，没有足够的垂直空间来嵌套其他交互元素。

```jsx
<Flex direction="column" gap="3" maxWidth="400px">
  <Box maxWidth="200px">
    <TextField.Root placeholder="搜索文档…" size="1">
      <TextField.Slot>
        <MagnifyingGlassIcon height="16" width="16" />
      </TextField.Slot>
    </TextField.Root>
  </Box>

  <Box maxWidth="250px">
    <TextField.Root placeholder="搜索文档…" size="2">
      <TextField.Slot>
        <MagnifyingGlassIcon height="16" width="16" />
      </TextField.Slot>

      <TextField.Slot>
        <IconButton size="1" variant="ghost">
          <DotsHorizontalIcon height="14" width="14" />
        </IconButton>
      </TextField.Slot>
    </TextField.Root>
  </Box>

  <Box maxWidth="300px">
    <TextField.Root placeholder="搜索文档…" size="3">
      <TextField.Slot>
        <MagnifyingGlassIcon height="16" width="16" />
      </TextField.Slot>

      <TextField.Slot pr="3">
        <IconButton size="2" variant="ghost">
          <DotsHorizontalIcon height="16" width="16" />
        </IconButton>
      </TextField.Slot>
    </TextField.Root>
  </Box>
</Flex>
```

### [变体](#变体)

使用 `variant` 属性来控制视觉风格。

```jsx
<Flex direction="column" gap="3" maxWidth="250px">
  <TextField.Root variant="surface" placeholder="搜索文档…" />

  <TextField.Root variant="classic" placeholder="搜索文档…" />

  <TextField.Root variant="soft" placeholder="搜索文档…" />
</Flex>
```

### [颜色](#颜色)

使用 `color` 属性来指定特定的 [颜色](/themes/docs/theme/color)。

```jsx
<Flex direction="column" gap="3" maxWidth="250px">
  <TextField.Root color="indigo" variant="soft" placeholder="搜索文档…" />

  <TextField.Root color="green" variant="soft" placeholder="搜索文档…" />

  <TextField.Root color="red" variant="soft" placeholder="搜索文档…" />
</Flex>
```

### [半径](#半径)

使用 `radius` 属性来指定特定的半径值。

```jsx
<Flex direction="column" gap="3" maxWidth="250px">
  <TextField.Root radius="none" placeholder="搜索文档…" />

  <TextField.Root radius="large" placeholder="搜索文档…" />

  <TextField.Root radius="full" placeholder="搜索文档…" />
</Flex>
```

<!--$-->

<!--/$-->