---
nav:
  title: 组件
  order: 1
group:
  title: Form Fields
  order: 1
title: PisellSingleLineText
order: 1
category: pro
---

# PisellSingleLineText 单行文本组件

通用的单行文本输入/展示组件，支持只读、编辑、禁用三种状态模式，提供完整的校验框架。

> **样式说明**：本组件使用内置样式，不依赖全局 antd token 配置，确保在任何环境下都保持一致的外观和设计规范。

## 何时使用

- 需要单行文本输入的场景（用户名、标题、编号等）
- 需要展示短文本内容
- 需要表单校验功能
- 需要切换只读/编辑状态

## 代码演示

### 基础用法

最简单的用法，默认为编辑态。

```tsx
import { PisellSingleLineText } from '@pisell/materials';

export default () => {
  return <PisellSingleLineText placeholder="请输入内容" />;
};
```

### 受控模式

通过 `value` 和 `onChange` 控制输入值。

```tsx
import { PisellSingleLineText } from '@pisell/materials';
import { useState } from 'react';

export default () => {
  const [value, setValue] = useState('');

  return (
    <PisellSingleLineText
      value={value}
      onChange={(newValue) => setValue(newValue)}
      placeholder="请输入内容"
    />
  );
};
```

### 只读态

使用 `mode="read"` 展示文本内容。

```tsx
import { PisellSingleLineText } from '@pisell/materials';

export default () => {
  return (
    <div>
      <PisellSingleLineText mode="read" value="这是一段展示的文本内容" />
    </div>
  );
};
```

### 只读态 - 文本截断

超出容器宽度时自动截断，鼠标悬停显示完整内容。

```tsx
import { PisellSingleLineText } from '@pisell/materials';

export default () => {
  return (
    <div style={{ width: '200px' }}>
      <PisellSingleLineText
        mode="read"
        value="这是一段非常非常非常长的文本内容，会被自动截断显示省略号"
        ellipsis
        showTooltip
      />
    </div>
  );
};
```

### 只读态 - 展示样式变体

支持 4 种展示样式：普通文本、超链接、徽标、标签。

```tsx
import { PisellSingleLineText } from '@pisell/materials';

export default () => {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
      {/* 普通文本 */}
      <PisellSingleLineText mode="read" value="普通文本" displayVariant="text" />

      {/* 超链接样式 */}
      <PisellSingleLineText
        mode="read"
        value="点击查看详情"
        displayVariant="link"
        onLinkClick={() => window.open('https://example.com')}
      />

      {/* 徽标样式 */}
      <PisellSingleLineText
        mode="read"
        value="5"
        displayVariant="badge"
        badgeStatus="error"
      />

      {/* 标签样式 */}
      <PisellSingleLineText mode="read" value="标签" displayVariant="tag" />
    </div>
  );
};
```

### 禁用态

设置 `disabled` 为 true。

```tsx
import { PisellSingleLineText } from '@pisell/materials';

export default () => {
  return (
    <PisellSingleLineText
      mode="edit"
      value="禁用状态的内容"
      disabled
      placeholder="禁用状态"
    />
  );
};
```

### 必填校验

通过 `required` 属性设置必填项。

```tsx
import { PisellSingleLineText } from '@pisell/materials';
import { useState } from 'react';

export default () => {
  const [value, setValue] = useState('');

  return (
    <PisellSingleLineText
      value={value}
      onChange={setValue}
      required
      placeholder="请输入（必填）"
      validateTrigger="onBlur"
    />
  );
};
```

### 长度校验

限制输入的最小和最大长度。

```tsx
import { PisellSingleLineText } from '@pisell/materials';

export default () => {
  return (
    <PisellSingleLineText
      placeholder="请输入 3-20 个字符"
      minLength={3}
      maxLength={20}
      showCount
      validateTrigger="onChange"
    />
  );
};
```

### 正则校验

使用正则表达式进行格式校验。

```tsx
import { PisellSingleLineText } from '@pisell/materials';

export default () => {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
      {/* 仅数字 */}
      <PisellSingleLineText
        placeholder="请输入数字"
        pattern="^[0-9]+$"
        errorMessage="只能输入数字"
        validateTrigger="onChange"
      />

      {/* 邮箱格式 */}
      <PisellSingleLineText
        placeholder="请输入邮箱"
        pattern="^[^\s@]+@[^\s@]+\.[^\s@]+$"
        errorMessage="邮箱格式不正确"
        validateTrigger="onBlur"
      />
    </div>
  );
};
```

### 自定义校验

使用自定义校验函数实现复杂校验逻辑。

```tsx
import { PisellSingleLineText } from '@pisell/materials';

export default () => {
  const validator = (value: string) => {
    if (value.includes('禁止')) {
      return '内容不能包含敏感词';
    }
    if (value.length > 0 && value.length < 3) {
      return '至少输入3个字符';
    }
    return true;
  };

  return (
    <PisellSingleLineText
      placeholder="请输入内容"
      validator={validator}
      validateTrigger="onChange"
    />
  );
};
```

### 前缀和后缀

添加前缀图标或后缀文本。

```tsx
import { PisellSingleLineText } from '@pisell/materials';
import { UserOutlined, InfoCircleOutlined } from '@ant-design/icons';

export default () => {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
      {/* 前缀图标 */}
      <PisellSingleLineText
        placeholder="请输入用户名"
        prefix={<UserOutlined />}
      />

      {/* 后缀文本 */}
      <PisellSingleLineText placeholder="请输入金额" suffix="元" />

      {/* 前缀和后缀 */}
      <PisellSingleLineText
        placeholder="请输入"
        prefix={<UserOutlined />}
        suffix={<InfoCircleOutlined />}
      />
    </div>
  );
};
```

### 前置和后置标签

添加前置或后置标签。

```tsx
import { PisellSingleLineText } from '@pisell/materials';
import { Button } from 'antd';

export default () => {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
      {/* 前置标签 */}
      <PisellSingleLineText
        placeholder="www.example.com"
        addonBefore="https://"
      />

      {/* 后置标签 */}
      <PisellSingleLineText
        placeholder=".com"
        addonAfter=".com"
      />

      {/* 后置按钮 */}
      <PisellSingleLineText
        placeholder="请输入搜索内容"
        addonAfter={<Button type="primary">搜索</Button>}
      />
    </div>
  );
};
```

### 字数统计

显示当前输入的字符数。

```tsx
import { PisellSingleLineText } from '@pisell/materials';

export default () => {
  return (
    <PisellSingleLineText
      placeholder="请输入内容"
      maxLength={100}
      showCount
    />
  );
};
```

### 清空按钮

显示清空按钮，快速清空输入内容。

```tsx
import { PisellSingleLineText } from '@pisell/materials';
import { useState } from 'react';

export default () => {
  const [value, setValue] = useState('测试内容');

  return (
    <PisellSingleLineText
      value={value}
      onChange={setValue}
      allowClear
      placeholder="请输入内容"
    />
  );
};
```

### 组合校验

组合使用多种校验规则。

```tsx
import { PisellSingleLineText } from '@pisell/materials';

export default () => {
  return (
    <PisellSingleLineText
      placeholder="请输入用户名"
      required
      minLength={3}
      maxLength={20}
      pattern="^[a-zA-Z0-9_]+$"
      errorMessage="用户名只能包含字母、数字和下划线"
      showCount
      validateTrigger="both"
    />
  );
};
```

### 自定义样式（只读态）

自定义文本的字号、字重、颜色等样式。

```tsx
import { PisellSingleLineText } from '@pisell/materials';

export default () => {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
      <PisellSingleLineText
        mode="read"
        value="大号粗体文本"
        fontSize="20px"
        fontWeight="bold"
      />

      <PisellSingleLineText
        mode="read"
        value="红色文本"
        color="#ff0000"
      />

      <PisellSingleLineText
        mode="read"
        value="居中对齐"
        textAlign="center"
      />
    </div>
  );
};
```

### 校验回调

监听校验结果。

```tsx
import { PisellSingleLineText } from '@pisell/materials';
import { message } from 'antd';

export default () => {
  const handleValidate = (isValid: boolean, errors: string[]) => {
    if (!isValid) {
      message.error(errors[0]);
    }
  };

  return (
    <PisellSingleLineText
      placeholder="请输入内容"
      required
      minLength={3}
      onValidate={handleValidate}
      validateTrigger="onBlur"
    />
  );
};
```

### 回车事件

监听回车键按下事件。

```tsx
import { PisellSingleLineText } from '@pisell/materials';
import { message } from 'antd';

export default () => {
  const handlePressEnter = (value: string) => {
    message.success(`提交内容：${value}`);
  };

  return (
    <PisellSingleLineText
      placeholder="输入后按回车提交"
      onPressEnter={handlePressEnter}
    />
  );
};
```

## API

### Props

| 参数               | 说明                | 类型                                                               | 默认值         |
|------------------|-------------------|------------------------------------------------------------------|-------------|
| mode             | 状态模式              | `'read' \| 'edit'`                                               | `'edit'`    |
| disabled         | 是否禁用              | `boolean`                                                        | `false`     |
| value            | 输入值（受控模式）         | `string`                                                         | -           |
| defaultValue     | 默认值（非受控模式）        | `string`                                                         | -           |
| placeholder      | 占位文本              | `string`                                                         | -           |
| maxLength        | 最大长度              | `number`                                                         | -           |
| showCount        | 是否显示字数统计          | `boolean`                                                        | `false`     |
| allowClear       | 是否显示清空按钮          | `boolean`                                                        | `false`     |
| autoFocus        | 是否自动聚焦            | `boolean`                                                        | `false`     |
| prefix           | 前缀图标或文本           | `ReactNode`                                                      | -           |
| suffix           | 后缀图标或文本           | `ReactNode`                                                      | -           |
| addonBefore      | 前置标签              | `ReactNode`                                                      | -           |
| addonAfter       | 后置标签              | `ReactNode`                                                      | -           |
| displayVariant   | 展示样式变体（只读态）       | `'text' \| 'link' \| 'badge' \| 'tag'`                           | `'text'`    |
| onLinkClick      | 超链接点击回调           | `() => void`                                                     | -           |
| badgeStatus      | 徽标状态              | `'success' \| 'processing' \| 'default' \| 'error' \| 'warning'` | `'default'` |
| tagColor         | 标签颜色              | `string`                                                         | -           |
| tagClosable      | 标签是否可关闭           | `boolean`                                                        | `false`     |
| onTagClose       | 标签关闭回调            | `() => void`                                                     | -           |
| ellipsis         | 超出是否省略（只读态）       | `boolean`                                                        | `true`      |
| showTooltip      | 是否显示 Tooltip（只读态） | `boolean`                                                        | `true`      |
| fontSize         | 字号（只读态）           | `string \| number`                                               | `16`        |
| fontWeight       | 字重（只读态）           | `string \| number`                                               | `500`       |
| color            | 文本颜色（只读态）         | `string`                                                         | `'#101828'` |
| textAlign        | 对齐方式（只读态）         | `'left' \| 'center' \| 'right'`                                  | `'left'`    |
| required         | 是否必填              | `boolean`                                                        | `false`     |
| minLength        | 最小长度              | `number`                                                         | -           |
| pattern          | 正则校验              | `string \| RegExp`                                               | -           |
| validator        | 自定义校验函数           | `(value: string) => boolean \| string`                           | -           |
| validateTrigger  | 校验触发时机            | `'onChange' \| 'onBlur' \| 'both'`                               | `'onBlur'`  |
| errorMessage     | 自定义错误提示           | `string`                                                         | -           |
| onChange         | 值变化回调             | `(value: string) => void`                                        | -           |
| onBlur           | 失焦回调              | `(value: string) => void`                                        | -           |
| onFocus          | 聚焦回调              | `() => void`                                                     | -           |
| onPressEnter     | 回车键回调             | `(value: string) => void`                                        | -           |
| onValidate       | 校验回调              | `(isValid: boolean, errors: string[]) => void`                   | -           |
| className        | 自定义类名             | `string`                                                         | -           |
| style            | 自定义样式             | `CSSProperties`                                                  | -           |
| aria-label       | ARIA 标签           | `string`                                                         | -           |
| aria-describedby | ARIA 描述           | `string`                                                         | -           |

## 展示样式变体（displayVariant）

### text - 普通文本（默认）

最常用的文本展示方式。

- 字号：16px
- 字重：Medium (500)
- 颜色：#101828 (Gray/900)
- 行高：24px

```
<PisellSingleLineText mode="read" value="普通文本" />
```

### link - 超链接样式

带双下划线的链接样式，可点击。

- 颜色：#7F56DA（项目链接色）
- 双下划线
- 鼠标悬停：颜色变深
- 支持键盘访问

```
<PisellSingleLineText
  mode="read"
  value="点击查看"
  displayVariant="link"
  onLinkClick={() => console.log('clicked')}
/>
```

### badge - 徽标样式

圆形红色徽标，适合显示通知数量或状态标识。

- 背景色：#D92D20（红色）
- 文字：白色
- 圆角：16px
- 适合：数字、短文本

```
<PisellSingleLineText
  mode="read"
  value="5"
  displayVariant="badge"
  badgeStatus="error"
/>
```

### tag - 标签样式

灰色边框标签，适合分类和标记。

- 背景色：#F9FAFB (Gray/50)
- 边框：#EAECF0 (Gray/200)
- 文字：#344054 (Gray/700)
- 圆角：16px
- 支持关闭功能

```
<PisellSingleLineText
  mode="read"
  value="标签"
  displayVariant="tag"
  tagClosable
  onTagClose={() => console.log('closed')}
/>
```

## 校验规则

### 校验优先级

按照以下优先级执行校验：

1. **必填校验**（required）
2. **最小长度校验**（minLength）
3. **最大长度校验**（maxLength）
4. **正则校验**（pattern）
5. **自定义校验**（validator）

### 校验触发时机

通过 `validateTrigger` 配置校验触发时机：

- **onChange**：输入时实时校验
- **onBlur**：失焦时校验（默认）
- **both**：同时支持两种时机

### 校验示例

```
<PisellSingleLineText
  required
  minLength={3}
  maxLength={10}
  pattern="^[a-zA-Z]+$"
  validator={(value) => {
    if (value === 'admin') {
      return '不能使用保留字';
    }
    return true;
  }}
  validateTrigger="both"
/>
```

## 常见问题

### 如何实现搜索框？

```
<PisellSingleLineText
  placeholder="搜索"
  prefix={<SearchOutlined />}
  allowClear
  onPressEnter={(value) => {
    console.log('搜索：', value);
  }}
/>
```

### 如何实现带单位的输入框？

```
<PisellSingleLineText
  placeholder="请输入价格"
  suffix="元"
  pattern="^[0-9]+(\\.[0-9]{1,2})?$"
  errorMessage="请输入有效的金额"
/>
```

### 如何实现 URL 输入框？

```
<PisellSingleLineText
  placeholder="www.example.com"
  addonBefore="https://"
  pattern="^[a-zA-Z0-9][-a-zA-Z0-9]{0,62}(\\.[a-zA-Z0-9][-a-zA-Z0-9]{0,62})+$"
  errorMessage="请输入有效的域名"
/>
```

### 如何只在失焦时校验？

```
<PisellSingleLineText
  required
  minLength={5}
  validateTrigger="onBlur"
/>
```

这样用户在输入过程中不会看到错误提示，只有失焦时才校验。

### 如何自定义错误提示？

```
<PisellSingleLineText
  required
  errorMessage="此字段不能为空"
/>
```

或者使用 `validator` 返回自定义错误信息：

```
<PisellSingleLineText
  validator={(value) => {
    if (!value) return '请输入内容';
    if (value.length < 3) return '至少3个字符';
    return true;
  }}
/>
```

### 如何控制只读态的样式？

```
<PisellSingleLineText
  mode="read"
  value="自定义样式文本"
  fontSize="18px"
  fontWeight="600"
  color="#1890ff"
  textAlign="center"
/>
```

### 受控模式 vs 非受控模式，如何选择？

**受控模式**（推荐）：

- 需要在外部管理值
- 需要做值的转换或格式化
- 需要与表单库集成

```
const [value, setValue] = useState('');
<PisellSingleLineText value={value} onChange={setValue} />
```

**非受控模式**：

- 简单场景，不需要外部管理
- 只需要获取最终值

```
<PisellSingleLineText defaultValue="初始值" />
```

## 注意事项

1. **受控模式下必须提供 onChange**：否则输入框无法修改
2. **maxLength 会自动限制输入**：Input 组件会阻止超出长度的输入
3. **校验不会阻止输入**：只是显示错误提示，不会阻止用户输入
4. **只读态的展示样式**：只在 `mode="read"` 时生效
5. **disabled 优先级最高**：当 `disabled=true` 时，无论 mode 是什么都显示禁用态

## 设计规范

### 编辑态（基于 Figma 设计）

- 高度：48px
- 圆角：8px
- 边框：1px solid #D0D5DD
- 内边距：12px 16px
- 字体：16px / 1.5
- 占位符颜色：#667085

### 只读态

- 字体：16px / Medium (500)
- 颜色：#101828
- 行高：24px

### 禁用态

- 背景色：#F9FAFB
- 文本颜色：#98A2B3
- 透明度：40%

## 相关组件

- [PisellLongText](./pisellLongText.md) - 长文本/多行文本组件
- [PisellPhone](./pisellPhone.md) - 电话号码组件
- [PisellEmail](./pisellEmail.md) - 邮箱地址组件
- [PisellUrl](./pisellUrl.md) - URL 链接组件
