---
nav:
  title: 组件
  order: 1
group:
  title: General
  order: 1
title: PisellEmail
order: 1
category: pro
---

﻿# PisellEmail 邮箱地址组件

邮箱地址输入/展示组件，支持邮箱格式校验、域名智能补全、mailto 邮件发送和域名隐藏功能。

## 何时使用

- 需要输入邮箱地址的场景
- 需要邮箱格式校验
- 需要域名自动补全
- 需要 mailto 邮件发送功能
- 需要域名脱敏显示
- 需要限制特定域名（企业邮箱）

## 代码演示

### 基础用法

默认为编辑态，带邮件图标前缀。

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

export default () => {
    return <PisellEmail placeholder="请输入邮箱地址"/>;
};
```

### 域名智能补全

输入 @ 后自动显示常用邮箱域名建议。

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

export default () => {
    return (
        <PisellEmail
            enableAutoComplete
            placeholder="试试输入 user@ 看看效果"
            onSelect={(email) => {
                console.log('选择了:', email);
            }}
        />
    );
};
```

### 自定义补全域名

只显示指定的邮箱域名。

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

export default () => {
    return (
        <PisellEmail
            enableAutoComplete
            autoCompleteDomains={['gmail.com', 'company.com', 'custom.com']}
            placeholder="输入@查看自定义域名"
        />
    );
};
```

### 只读态 - 可发邮件

展示邮箱地址，点击可唤起邮件客户端。

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

export default () => {
    return (
        <PisellEmail
            mode="read"
            value="support@example.com"
            enableMailto
            displayAsLink
        />
    );
};
```

### 只读态 - 带邮件图标

显示邮件图标，点击可发邮件。

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

export default () => {
    return (
        <PisellEmail
            mode="read"
            value="support@example.com"
            enableMailto
            showEmailIcon
            displayAsLink
        />
    );
};
```

### mailto 带参数

预设邮件主题和正文。

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

export default () => {
    return (
        <PisellEmail
            mode="read"
            value="sales@company.com"
            enableMailto
            showEmailIcon
            mailtoOptions={{
                subject: '产品咨询',
                body: '您好，我想咨询关于贵公司的产品...',
                cc: 'manager@company.com',
            }}
            onMailto={(email) => {
                console.log('发送邮件至:', email);
            }}
        />
    );
};
```

### 域名脱敏

隐私保护，隐藏部分或全部域名。

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: '16px'}}>
            {/* 部分隐藏：u***@gmail.com */}
            <PisellEmail
                mode="read"
                value="user@gmail.com"
                hideDomain
                maskPattern="partial"
            />

            {/* 完全隐藏：user@*** */}
            <PisellEmail
                mode="read"
                value="user@gmail.com"
                hideDomain
                maskPattern="full"
            />
        </div>
    );
};
```

### 白名单域名限制

仅允许指定的邮箱域名（企业邮箱场景）。

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

export default () => {
    return (
        <PisellEmail
            placeholder="请使用公司邮箱"
            allowedDomains={['company.com', 'partner.com']}
            errorMessage="只允许使用公司邮箱或合作伙伴邮箱"
            validateTrigger="onBlur"
        />
    );
};
```

### 黑名单域名限制

禁止使用某些邮箱域名（临时邮箱场景）。

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

export default () => {
    return (
        <PisellEmail
            placeholder="请输入邮箱地址"
            blockedDomains={['tempmail.com', '10minutemail.com']}
            errorMessage="不支持临时邮箱"
            validateTrigger="onBlur"
        />
    );
};
```

### 必填校验

设置必填项。

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

export default () => {
    return (
        <PisellEmail
            placeholder="请输入邮箱地址（必填）"
            required
            validateTrigger="onBlur"
        />
    );
};
```

### 格式校验（实时）

输入时即时校验邮箱格式。

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

export default () => {
    return (
        <PisellEmail
            placeholder="请输入邮箱地址"
            validateTrigger="onChange"
        />
    );
};
```

### 严格格式校验

使用 RFC 5322 标准校验。

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

export default () => {
    return (
        <PisellEmail
            placeholder="请输入邮箱地址"
            strictValidation
            validateTrigger="onBlur"
        />
    );
};
```

### 自定义校验

添加自定义校验逻辑。

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

export default () => {
    return (
        <PisellEmail
            placeholder="请输入邮箱地址"
            customValidator={(email) => {
                if (!email.endsWith('@company.com')) {
                    return '必须使用公司邮箱';
                }
                return true;
            }}
            validateTrigger="onChange"
        />
    );
};
```

### 完整功能示例

展示编辑态、只读态、域名隐藏等多种状态。

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

export default () => {
    const [email, setEmail] = useState('');

    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: '24px'}}>
            {/* 编辑态 - 域名补全 + 格式校验 */}
            <div>
                <h3>编辑态</h3>
                <PisellEmail
                    value={email}
                    onChange={setEmail}
                    placeholder="试试输入 user@ 看看域名补全"
                    enableAutoComplete
                    autoCompleteDomains={['gmail.com', 'qq.com', 'company.com']}
                    required
                    validateTrigger="both"
                    allowClear
                    onSelect={(val) => {
                        console.log('选择了:', val);
                    }}
                    onValidate={(isValid, errors) => {
                        console.log('校验结果:', isValid, errors);
                    }}
                />
            </div>

            {/* 只读态 - 可发邮件 */}
            <div>
                <h3>只读态 - 可发邮件</h3>
                <PisellEmail
                    mode="read"
                    value={email || 'support@example.com'}
                    enableMailto
                    displayAsLink
                    showEmailIcon
                    mailtoOptions={{
                        subject: '产品咨询',
                        body: '您好，我想咨询...',
                    }}
                    onMailto={(val) => {
                        console.log('发送邮件至:', val);
                    }}
                />
            </div>

            {/* 只读态 - 域名隐藏 */}
            <div>
                <h3>只读态 - 域名隐藏</h3>
                <PisellEmail
                    mode="read"
                    value={email || 'user@gmail.com'}
                    hideDomain
                    maskPattern="partial"
                    enableMailto
                />
            </div>
        </div>
    );
};
```

## API

### Props

| 参数                  | 说明             | 类型                                             | 默认值         |
|---------------------|----------------|------------------------------------------------|-------------|
| mode                | 状态模式           | `'read' \| 'edit'`                             | `'edit'`    |
| disabled            | 是否禁用           | `boolean`                                      | `false`     |
| value               | 邮箱地址           | `string`                                       | -           |
| defaultValue        | 默认值            | `string`                                       | -           |
| placeholder         | 占位文本           | `string`                                       | `'请输入邮箱地址'` |
| maxLength           | 最大长度           | `number`                                       | `254`       |
| allowClear          | 显示清空按钮         | `boolean`                                      | `false`     |
| autoFocus           | 自动聚焦           | `boolean`                                      | `false`     |
| strictValidation    | 严格校验（RFC 5322） | `boolean`                                      | `false`     |
| allowedDomains      | 白名单域名列表        | `string[]`                                     | -           |
| blockedDomains      | 黑名单域名列表        | `string[]`                                     | -           |
| enableAutoComplete  | 启用域名补全         | `boolean`                                      | `true`      |
| autoCompleteDomains | 自定义补全域名列表      | `string[]`                                     | 常用域名        |
| showAllSuggestions  | 显示所有建议（不过滤）    | `boolean`                                      | `false`     |
| onSelect            | 选择补全建议回调       | `(value: string) => void`                      | -           |
| enableMailto        | 启用 mailto（只读态） | `boolean`                                      | `true`      |
| showEmailIcon       | 显示邮件图标         | `boolean`                                      | `false`     |
| displayAsLink       | 显示为链接（只读态）     | `boolean`                                      | `true`      |
| mailtoOptions       | mailto 参数配置    | `MailtoOptions`                                | -           |
| onMailto            | 发送邮件回调         | `(email: string) => void`                      | -           |
| hideDomain          | 隐藏域名（只读态）      | `boolean`                                      | `false`     |
| maskPattern         | 脱敏模式           | `'partial' \| 'full'`                          | `'partial'` |
| fontSize            | 字号（只读态）        | `string \| number`                             | `16`        |
| fontWeight          | 字重（只读态）        | `string \| number`                             | `500`       |
| color               | 文本颜色（只读态）      | `string`                                       | `'#101828'` |
| linkColor           | 链接颜色（只读态）      | `string`                                       | `'#7F56DA'` |
| required            | 是否必填           | `boolean`                                      | `false`     |
| customValidator     | 自定义校验函数        | `(email: string) => boolean \| string`         | -           |
| validateTrigger     | 校验触发时机         | `'onChange' \| 'onBlur' \| 'both'`             | `'onBlur'`  |
| errorMessage        | 自定义错误提示        | `string`                                       | -           |
| onChange            | 值变化回调          | `(value: string) => void`                      | -           |
| onBlur              | 失焦回调           | `(value: string) => void`                      | -           |
| onFocus             | 聚焦回调           | `() => void`                                   | -           |
| onValidate          | 校验回调           | `(isValid: boolean, errors: string[]) => void` | -           |

### MailtoOptions 类型

```
interface MailtoOptions {
  subject?: string;  // 邮件主题
  body?: string;     // 邮件正文
  cc?: string;       // 抄送
  bcc?: string;      // 密送
}
```

## 核心功能说明

### 邮箱格式校验

**标准校验**：覆盖99%常见邮箱格式

- user@example.com ✅
- user.name@example.com ✅
- user+tag@example.com ✅
- user@sub.example.com ✅

**严格校验**：符合 RFC 5322 标准

- 支持更复杂的邮箱格式
- 适用于需要严格遵循标准的场景

### 域名智能补全

**常用域名列表**（18个）：

- 国内：qq.com、163.com、126.com、sina.com...
- 国际：gmail.com、outlook.com、hotmail.com、yahoo.com...
- 企业：company.com（可自定义）

**补全逻辑**：

1. 输入 `user@` → 显示所有域名建议
2. 输入 `user@g` → 只显示 `gmail.com`
3. 输入 `user@16` → 显示 `163.com`、`126.com`
4. 键盘上下键选择，回车确认

### mailto 邮件发送

**基础发送**：

```
<PisellEmail 
  mode="read" 
  value="support@example.com" 
  enableMailto 
/>
```

点击后唤起邮件客户端：`mailto:support@example.com`

**带参数发送**：

```
<PisellEmail 
  mode="read" 
  value="support@example.com" 
  mailtoOptions={{
    subject: '产品咨询',
    body: '您好，我想咨询...',
    cc: 'manager@example.com'
  }}
/>
```

点击后预填主题、正文和抄送

### 域名隐藏/脱敏

保护用户隐私：

- **部分隐藏**（partial）：`u***@gmail.com`
- **完全隐藏**（full）：`user@***`

### 白名单/黑名单

**白名单**：仅允许指定域名

```
<PisellEmail allowedDomains={['company.com', 'partner.com']} />
```

只允许公司邮箱和合作伙伴邮箱

**黑名单**：禁止某些域名

```
<PisellEmail blockedDomains={['tempmail.com', '10minutemail.com']} />
```

禁止使用临时邮箱

## 常见问题

### 如何限制只能使用公司邮箱？

```
<PisellEmail
  allowedDomains={['company.com']}
  errorMessage="请使用公司邮箱"
/>
```

### 如何禁用域名补全？

```
<PisellEmail enableAutoComplete={false} />
```

### 如何实时校验邮箱格式？

```
<PisellEmail validateTrigger="onChange" />
```

### 如何监听域名补全选择？

```
<PisellEmail
  onSelect={(email) => {
    console.log('用户选择了:', email);
  }}
/>
```

### 如何让只读态不可点击发邮件？

```
<PisellEmail 
  mode="read" 
  value="user@example.com"
  enableMailto={false}
/>
```

或者：

```
<PisellEmail 
  mode="read" 
  value="user@example.com"
  displayAsLink={false}
/>
```

### 如何监听 mailto 点击？

```
<PisellEmail
  mode="read"
  value="support@example.com"
  onMailto={(email) => {
    // 可以在这里做统计、埋点等
    console.log('用户准备发送邮件至:', email);
  }}
/>
```

### 如何使用严格校验？

```
<PisellEmail strictValidation />
```

严格校验遵循 RFC 5322 标准，支持更复杂的邮箱格式。

### 如何自定义脱敏规则？

目前仅支持 partial 和 full 两种模式。如需完全自定义，可以在只读态使用时，先手动处理 value：

```
const maskedEmail = customMaskFunction(originalEmail);

<PisellEmail 
  mode="read" 
  value={maskedEmail}
  enableMailto={false}
/>
```

## 注意事项

1. **邮箱规范化**：建议使用小写存储邮箱地址
2. **最大长度**：RFC 5321 标准规定邮箱最大长度为 254 字符
3. **域名补全触发**：必须输入 @ 符号后才会显示建议
4. **mailto 协议**：需要用户本地安装了邮件客户端才能正常工作
5. **域名脱敏**：仅在只读态生效，不影响实际值
6. **白名单优先**：同时设置白名单和黑名单时，白名单优先
7. **自定义校验优先级**：先执行格式校验，再执行域名校验，最后执行自定义校验

## 设计规范

继承 Input 组件的设计规范（基于 Figma）：

- 高度：48px
- 圆角：8px
- 边框：1px solid #D0D5DD
- 内边距：12px 16px
- 链接颜色（只读态）：#7F56DA

## 相关组件

- [PisellSingleLineText](../pisellSingleLineText/pisellSingleLineText.md) - 单行文本组件
- [PisellLongText](../pisellLongText/pisellLongText.md) - 长文本组件
- [PisellPhone](../pisellPhone/pisellPhone.md) - 电话号码组件
- [PisellUrl](../pisellUrl/pisellUrl.md) - URL 链接组件
