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

# PisellUrl URL 地址组件

URL 地址输入/展示组件，支持 URL 格式校验、协议自动补全、链接跳转和协议/路径显示控制功能。

## 何时使用

- 需要输入 URL 地址的场景
- 需要 URL 格式校验
- 需要协议自动补全
- 需要链接跳转功能
- 需要灵活控制协议/路径显示
- 需要限制特定协议（如仅 HTTPS）

## 代码演示

### 基础用法

默认为编辑态，带链接图标前缀。

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

export default () => {
  return <PisellUrl placeholder="请输入网址" />;
};
```

### 协议自动补全

失焦时自动补全 https:// 协议。

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

export default () => {
  return (
    <PisellUrl
      autoCompleteProtocol
      defaultProtocol="https://"
      placeholder="输入网址，失焦后自动补全协议"
      onProtocolComplete={(url) => {
        console.log('协议补全:', url);
      }}
    />
  );
};
```

### 自定义默认协议

设置默认补全的协议为 http://。

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

export default () => {
  return (
    <PisellUrl
      autoCompleteProtocol
      defaultProtocol="http://"
      placeholder="失焦后补全 http://"
    />
  );
};
```

### 只读态 - 可跳转

展示 URL 地址，点击可在新窗口打开。

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

export default () => {
  return (
    <PisellUrl
      mode="read"
      value="https://www.example.com"
      enableLinkClick
      openInNewWindow
    />
  );
};
```

### 链接跳转配置

控制链接打开方式和回调。

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

export default () => {
  return (
    <PisellUrl
      mode="read"
      value="https://www.example.com"
      enableLinkClick
      openInNewWindow={false}  // 当前窗口打开
      showLinkIcon
      onLinkClick={(url) => {
        console.log('准备打开:', url);
        // 可以在这里做统计、埋点等
      }}
    />
  );
};
```

### 协议/路径显示控制

灵活控制 URL 的显示内容。

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

export default () => {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
      {/* 完整 URL */}
      <PisellUrl
        mode="read"
        value="https://www.example.com/path/to/page"
        showProtocol={true}
      />

      {/* 隐藏协议 */}
      <PisellUrl
        mode="read"
        value="https://www.example.com/path/to/page"
        showProtocol={false}
      />

      {/* 隐藏路径（显示协议+域名） */}
      <PisellUrl
        mode="read"
        value="https://www.example.com/path/to/page"
        showProtocol={true}
        showPathname={false}
      />

      {/* 仅域名 */}
      <PisellUrl
        mode="read"
        value="https://www.example.com/path/to/page"
        displayFormat="domain"
      />
    </div>
  );
};
```

### 协议白名单限制

仅允许指定的协议（如仅 HTTPS）。

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

export default () => {
  return (
    <PisellUrl
      placeholder="仅支持 HTTPS 协议"
      allowedProtocols={['https']}
      errorMessage="只允许使用 HTTPS 协议"
      validateTrigger="onBlur"
    />
  );
};
```

### 协议必需校验

要求用户必须输入协议。

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

export default () => {
  return (
    <PisellUrl
      requireProtocol
      autoCompleteProtocol={false}
      placeholder="必须输入完整 URL（含协议）"
      validateTrigger="onBlur"
    />
  );
};
```

### 必填校验

设置必填项。

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

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

### 格式校验（实时）

输入时即时校验 URL 格式。

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

export default () => {
  return (
    <PisellUrl
      placeholder="请输入网址"
      validateTrigger="onChange"
    />
  );
};
```

### 自定义校验

添加自定义校验逻辑。

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

export default () => {
  return (
    <PisellUrl
      placeholder="请输入网址"
      customValidator={(url) => {
        if (!url.includes('.com')) {
          return '必须是 .com 域名';
        }
        return true;
      }}
      validateTrigger="onChange"
    />
  );
};
```

### 自定义格式化

自定义只读态的显示格式。

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

export default () => {
  return (
    <PisellUrl
      mode="read"
      value="https://www.example.com/path"
      displayFormat="custom"
      customFormat={(url) => {
        // 自定义显示：只显示域名，并加前缀
        const domain = new URL(url).hostname;
        return `访问 ${domain}`;
      }}
    />
  );
};
```

### 完整功能示例

展示编辑态、只读态、显示控制等多种状态。

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

export default () => {
  const [url, setUrl] = useState('');

  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '24px' }}>
      {/* 编辑态 - 协议补全 + 格式校验 */}
      <div>
        <h3>编辑态</h3>
        <PisellUrl
          value={url}
          onChange={setUrl}
          placeholder="试试输入 example.com 然后失焦"
          autoCompleteProtocol
          defaultProtocol="https://"
          required
          validateTrigger="both"
          allowClear
          onProtocolComplete={(val) => {
            console.log('协议补全:', val);
          }}
          onValidate={(isValid, errors) => {
            console.log('校验结果:', isValid, errors);
          }}
        />
      </div>

      {/* 只读态 - 可跳转 */}
      <div>
        <h3>只读态 - 可跳转</h3>
        <PisellUrl
          mode="read"
          value={url || 'https://www.example.com'}
          enableLinkClick
          openInNewWindow
          showLinkIcon
          onLinkClick={(val) => {
            console.log('点击链接:', val);
          }}
        />
      </div>

      {/* 只读态 - 显示控制 */}
      <div>
        <h3>只读态 - 显示控制</h3>
        <div>
          <p>完整 URL:</p>
          <PisellUrl
            mode="read"
            value={url || 'https://www.example.com/path'}
            showProtocol={true}
          />
        </div>
        <div>
          <p>隐藏协议:</p>
          <PisellUrl
            mode="read"
            value={url || 'https://www.example.com/path'}
            showProtocol={false}
          />
        </div>
        <div>
          <p>仅域名:</p>
          <PisellUrl
            mode="read"
            value={url || 'https://www.example.com/path'}
            displayFormat="domain"
          />
        </div>
      </div>
    </div>
  );
};
```

## API

### Props

| 参数                   | 说明          | 类型                                             | 默认值                 |
|----------------------|-------------|------------------------------------------------|---------------------|
| mode                 | 状态模式        | `'read' \| 'edit'`                             | `'edit'`            |
| disabled             | 是否禁用        | `boolean`                                      | `false`             |
| value                | URL 地址      | `string`                                       | -                   |
| defaultValue         | 默认值         | `string`                                       | -                   |
| placeholder          | 占位文本        | `string`                                       | `'请输入 URL 地址'`      |
| maxLength            | 最大长度        | `number`                                       | `2048`              |
| allowClear           | 显示清空按钮      | `boolean`                                      | `false`             |
| autoFocus            | 自动聚焦        | `boolean`                                      | `false`             |
| strictValidation     | 严格校验        | `boolean`                                      | `true`              |
| allowedProtocols     | 允许的协议列表     | `string[]`                                     | `['http', 'https']` |
| requireProtocol      | 是否要求必须有协议   | `boolean`                                      | `false`             |
| autoCompleteProtocol | 自动补全协议      | `boolean`                                      | `true`              |
| defaultProtocol      | 默认协议        | `'http://' \| 'https://'`                      | `'https://'`        |
| onProtocolComplete   | 协议补全回调      | `(url: string) => void`                        | -                   |
| enableLinkClick      | 启用链接跳转（只读态） | `boolean`                                      | `true`              |
| openInNewWindow      | 新窗口打开       | `boolean`                                      | `true`              |
| showLinkIcon         | 显示链接图标      | `boolean`                                      | `true`              |
| onLinkClick          | 链接点击回调      | `(url: string) => void`                        | -                   |
| showProtocol         | 显示协议（只读态）   | `boolean`                                      | `false`             |
| showWww              | 显示 www（只读态） | `boolean`                                      | `false`             |
| showPathname         | 显示路径（只读态）   | `boolean`                                      | `true`              |
| displayFormat        | 显示格式（只读态）   | `'full' \| 'domain' \| 'custom'`               | `'full'`            |
| customFormat         | 自定义格式化函数    | `(url: string) => string`                      | -                   |
| fontSize             | 字号（只读态）     | `string \| number`                             | `16`                |
| fontWeight           | 字重（只读态）     | `string \| number`                             | `500`               |
| color                | 文本颜色（只读态）   | `string`                                       | `'#101828'`         |
| linkColor            | 链接颜色（只读态）   | `string`                                       | `'#7F56DA'`         |
| required             | 是否必填        | `boolean`                                      | `false`             |
| customValidator      | 自定义校验函数     | `(url: 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` | -                   |

## 核心功能说明

### URL 格式校验

**使用原生 URL 构造函数**：更可靠的校验方式

- https://example.com ✅
- http://localhost:3000 ✅
- https://example.com/path ✅
- https://example.com?key=value ✅
- https://example.com#section ✅
- http://192.168.1.1 ✅

**校验方法**：

- 优先使用 `new URL()` 构造函数
- 自动支持端口、路径、查询参数、锚点
- 支持 localhost 和 IP 地址

### 协议自动补全

**失焦时自动补全**：

- 输入 `example.com` → 失焦后 → `https://example.com`
- 输入 `localhost:3000` → 失焦后 → `https://localhost:3000`
- 输入 `http://example.com` → 失焦后 → 保持不变（已有协议）

**智能识别（可扩展）**：

- localhost 和本地 IP 可以自动使用 http
- 其他域名使用 https

### 链接跳转

**新窗口打开（默认）**：

```
<PisellUrl 
  mode="read" 
  value="https://example.com" 
  enableLinkClick
  openInNewWindow
/>
```

点击后在新窗口打开，自动添加 `noopener,noreferrer` 安全性保障

**当前窗口打开**：

```
<PisellUrl 
  mode="read" 
  value="https://example.com" 
  openInNewWindow={false}
/>
```

点击后在当前窗口打开

### 协议/路径显示控制

**4 种显示模式**：

1. **完整 URL**（showProtocol=true）
   ```
   <PisellUrl mode="read" value="https://www.example.com/path" showProtocol={true} />
   ```
   显示：`https://www.example.com/path`

2. **隐藏协议**（showProtocol=false，默认）
   ```
   <PisellUrl mode="read" value="https://www.example.com/path" showProtocol={false} />
   ```
   显示：`www.example.com/path`

3. **协议+域名**（showPathname=false）
   ```
   <PisellUrl mode="read" value="https://www.example.com/path" showProtocol={true} showPathname={false} />
   ```
   显示：`https://www.example.com`

4. **仅域名**（displayFormat='domain'）
   ```
   <PisellUrl mode="read" value="https://www.example.com/path" displayFormat="domain" />
   ```
   显示：`www.example.com`

### 协议白名单

**仅允许 HTTPS**：

```
<PisellUrl 
  allowedProtocols={['https']}
  errorMessage="仅支持 HTTPS 协议"
/>
```

只允许 https:// 协议

**允许多个协议**：

```
<PisellUrl 
  allowedProtocols={['http', 'https', 'ftp']}
/>
```

允许 http://、https:// 和 ftp://

## 常见问题

### 如何限制只能使用 HTTPS？

```
<PisellUrl
  allowedProtocols={['https']}
  errorMessage="仅支持 HTTPS 协议"
/>
```

### 如何禁用协议自动补全？

```
<PisellUrl autoCompleteProtocol={false} />
```

### 如何要求用户必须输入协议？

```
<PisellUrl 
  requireProtocol
  autoCompleteProtocol={false}
  errorMessage="请输入完整 URL（含 http:// 或 https://）"
/>
```

### 如何实时校验 URL 格式？

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

### 如何监听协议补全？

```
<PisellUrl
  onProtocolComplete={(url) => {
    console.log('协议已补全为:', url);
  }}
/>
```

### 如何让只读态不可点击跳转？

```
<PisellUrl 
  mode="read" 
  value="https://example.com"
  enableLinkClick={false}
/>
```

### 如何监听链接点击？

```
<PisellUrl
  mode="read"
  value="https://example.com"
  onLinkClick={(url) => {
    // 可以在这里做统计、埋点等
    console.log('用户准备访问:', url);
  }}
/>
```

### 如何在当前窗口打开链接？

```
<PisellUrl 
  mode="read" 
  value="https://example.com"
  openInNewWindow={false}
/>
```

### 如何只显示域名不显示路径？

```
<PisellUrl 
  mode="read" 
  value="https://www.example.com/path"
  displayFormat="domain"
/>
```

或者：

```
<PisellUrl 
  mode="read" 
  value="https://www.example.com/path"
  showPathname={false}
/>
```

### 如何完全自定义显示格式？

```
<PisellUrl 
  mode="read" 
  value="https://www.example.com/path"
  displayFormat="custom"
  customFormat={(url) => {
    const domain = new URL(url).hostname;
    return `🔗 ${domain}`;
  }}
/>
```

## 注意事项

1. **协议补全时机**：失焦时自动补全，避免干扰用户输入
2. **最大长度**：默认 2048 字符（浏览器 URL 长度限制）
3. **安全性保障**：新窗口打开时自动添加 `noopener,noreferrer`
4. **URL 构造函数**：使用原生 URL 构造函数校验，更可靠
5. **协议默认值**：默认补全 `https://`，可配置为 `http://`
6. **显示优先级**：`displayFormat` > `showProtocol/showPathname` 配置
7. **校验优先级**：格式校验 > 协议必需校验 > 协议白名单校验 > 自定义校验

## 设计规范

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

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

## 相关组件

- [PisellSingleLineText](../pisellSingleLineText/pisellSingleLineText.md) - 单行文本组件
- [PisellLongText](../pisellLongText/pisellLongText.md) - 长文本组件
- [PisellPhone](../pisellPhone/pisellPhone.md) - 电话号码组件
- [PisellEmail](../pisellEmail/pisellEmail.md) - 邮箱地址组件
