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

# PisellTimeRangeDisplay 时间区间展示组件

## 组件介绍

PisellTimeRangeDisplay 是一个专注于展示**时间区间 + 持续时间**
的纯展示型组件，用于在不同语言、时区与信息密度下，将开始时间（startAt）与结束时间（endAt）格式化为「时间区间 + 持续时间」的紧凑表达。

**核心特性**：

- ✅ 同一天：HH:mm-HH:mm，可选显示日期/星期
- ✅ 跨天：自动展开起止日期时间
- ✅ 持续时间：d h m s 格式（如 2h30m、1d2h30m23s）
- ✅ 字段顺序可配置（时间、日期、星期、持续时长可任意排序）
- ✅ 时间/日期/星期格式复用 PisellDateTimeDisplay
- ✅ 国际化支持（dayjs locale）
- ✅ 高度可配置的样式系统

---

## 基础用法

### 简单示例（同一天）

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

export default () => {
    return (
        <PisellTimeRangeDisplay
            startAt="2026-02-04 09:00"
            endAt="2026-02-04 18:00"
        />
    );
};
```

### 跨天示例

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

export default () => {
    return (
        <PisellTimeRangeDisplay
            startAt="2026-02-04 10:15"
            endAt="2026-02-05 11:30"
        />
    );
};
```

---

## 布局与对齐

### 文本对齐

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16, width: 320}}>
            <div style={{border: '1px solid #d9d9d9', padding: 16}}>
                <PisellTimeRangeDisplay startAt="2026-02-04 09:00" endAt="2026-02-04 18:00" textAlign="left"/>
            </div>
            <div style={{border: '1px solid #d9d9d9', padding: 16}}>
                <PisellTimeRangeDisplay startAt="2026-02-04 09:00" endAt="2026-02-04 18:00" textAlign="center"/>
            </div>
            <div style={{border: '1px solid #d9d9d9', padding: 16}}>
                <PisellTimeRangeDisplay startAt="2026-02-04 09:00" endAt="2026-02-04 18:00" textAlign="right"/>
            </div>
        </div>
    );
};
```

---

## 字段配置

### 字段显隐

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            {/* 只显示时间区间 + 持续时长 */}
            <PisellTimeRangeDisplay
                startAt="2026-02-04 09:00"
                endAt="2026-02-04 18:00"
                fields={{showTimeRange: true, showDate: false, showWeekday: false, showDuration: true}}
            />
            {/* 只显示时间区间 */}
            <PisellTimeRangeDisplay
                startAt="2026-02-04 09:00"
                endAt="2026-02-04 18:00"
                fields={{showTimeRange: true, showDate: false, showWeekday: false, showDuration: false}}
            />
        </div>
    );
};
```

### 字段排序（持续时间在前）

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            {/* 默认：星期、日期、时间、持续时长 */}
            <PisellTimeRangeDisplay
                startAt="2026-02-04 10:15"
                endAt="2026-02-04 10:45"
                showDateForSameDay
            />
            {/* 持续时间在前 */}
            <PisellTimeRangeDisplay
                startAt="2026-02-04 10:15"
                endAt="2026-02-04 10:45"
                fields={{fieldOrder: ['time', 'duration', 'date', 'weekday']}}
                showDateForSameDay
            />
        </div>
    );
};
```

### 同一天是否显示日期

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            {/* 显示具体日期（默认） */}
            <PisellTimeRangeDisplay
                startAt="2026-02-04 09:00"
                endAt="2026-02-04 18:00"
                showDateForSameDay
            />
            {/* 同一天不显示日期 */}
            <PisellTimeRangeDisplay
                startAt="2026-02-04 09:00"
                endAt="2026-02-04 18:00"
                showDateForSameDay={false}
            />
        </div>
    );
};
```

---

## 时间格式

### 24 小时制 / 显示秒

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            <PisellTimeRangeDisplay
                startAt="2026-02-04 09:00"
                endAt="2026-02-04 18:30"
                timeFormat={{use12Hour: false}}
            />
            <PisellTimeRangeDisplay
                startAt="2026-02-04 09:00:00"
                endAt="2026-02-04 18:30:45"
                timeFormat={{use12Hour: false, showSeconds: true}}
            />
        </div>
    );
};
```

### 12 小时制

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

export default () => {
    return (
        <PisellTimeRangeDisplay
            startAt="2026-02-04 09:00"
            endAt="2026-02-04 18:00"
            timeFormat={{use12Hour: true}}
            locale="en"
        />
    );
};
```

---

## 持续时长格式

### 是否显示秒

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            {/* 默认不显示秒：2h30m */}
            <PisellTimeRangeDisplay
                startAt="2026-02-04 09:00"
                endAt="2026-02-04 11:30"
            />
            {/* 显示秒：2h30m23s */}
            <PisellTimeRangeDisplay
                startAt="2026-02-04 09:00:00"
                endAt="2026-02-04 11:30:23"
                durationFormat={{showSeconds: true}}
            />
        </div>
    );
};
```

---

## 日期与星期格式

### 日期顺序与星期

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            <PisellTimeRangeDisplay
                startAt="2026-02-04 10:15"
                endAt="2026-02-04 10:45"
                showDateForSameDay
                dateFormat={{showRelativeDay: false, order: 'DMY', showYear: true}}
                weekdayFormat={{full: false}}
                locale="zh-cn"
            />
            <PisellTimeRangeDisplay
                startAt="2026-02-04 10:15"
                endAt="2026-02-04 10:45"
                showDateForSameDay
                dateFormat={{showRelativeDay: false, order: 'YMD', showYear: true}}
                locale="en"
            />
        </div>
    );
};
```

---

## 国际化

### 语言切换

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            <PisellTimeRangeDisplay
                startAt="2026-02-04 10:15"
                endAt="2026-02-04 10:45"
                locale="zh-cn"
                showDateForSameDay
            />
            <PisellTimeRangeDisplay
                startAt="2026-02-04 10:15"
                endAt="2026-02-04 10:45"
                locale="en"
                showDateForSameDay
            />
        </div>
    );
};
```

---

## 样式配置

### 容器样式

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

export default () => {
    return (
        <PisellTimeRangeDisplay
            startAt="2026-02-04 09:00"
            endAt="2026-02-04 18:00"
            containerStyle={{
                background: '#f5f5f5',
                borderRadius: 8,
                border: '1px solid #d9d9d9',
                padding: 16,
                gap: 8,
            }}
        />
    );
};
```

### 文本样式

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

export default () => {
    return (
        <PisellTimeRangeDisplay
            startAt="2026-02-04 09:00"
            endAt="2026-02-04 18:00"
            timeStyle={{fontSize: 18, fontWeight: 600, color: '#1890ff'}}
            dateStyle={{fontSize: 14, color: '#666'}}
            durationStyle={{fontSize: 14, color: '#999'}}
        />
    );
};
```

---

## 事件回调

### 点击事件

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

export default () => {
    return (
        <PisellTimeRangeDisplay
            startAt="2026-02-04 09:00"
            endAt="2026-02-04 18:00"
            onClick={() => message.info('时间区间被点击')}
            style={{cursor: 'pointer'}}
        />
    );
};
```

---

## API

### PisellTimeRangeDisplayProps

#### 数据

| 参数      | 说明             | 类型                          | 默认值 |
|---------|----------------|-----------------------------|-----|
| startAt | 开始时间（dayjs 兼容） | `Dayjs \| string \| number` | -   |
| endAt   | 结束时间（dayjs 兼容） | `Dayjs \| string \| number` | -   |

#### 布局配置

| 参数        | 说明   | 类型                              | 默认值        |
|-----------|------|---------------------------------|------------|
| textAlign | 文本对齐 | `'left' \| 'center' \| 'right'` | `'center'` |

#### 字段配置

| 参数                   | 说明           | 类型                     | 默认值                                       |
|----------------------|--------------|------------------------|-------------------------------------------|
| fields.showTimeRange | 是否显示时间区间     | `boolean`              | `true`                                    |
| fields.showDate      | 是否显示日期       | `boolean`              | `true`                                    |
| fields.showWeekday   | 是否显示星期       | `boolean`              | `true`                                    |
| fields.showDuration  | 是否显示持续时长     | `boolean`              | `true`                                    |
| fields.fieldOrder    | 字段顺序         | `TimeRangeFieldType[]` | `['weekday', 'date', 'time', 'duration']` |
| showDateForSameDay   | 同一天时是否显示具体日期 | `boolean`              | `true`                                    |

#### 格式化配置

| 参数                         | 说明                            | 类型                    |
|----------------------------|-------------------------------|-----------------------|
| timeFormat                 | 时间格式（同 PisellDateTimeDisplay） | `TimeFormatConfig`    |
| dateFormat                 | 日期格式                          | `DateFormatConfig`    |
| weekdayFormat              | 星期格式                          | `WeekdayFormatConfig` |
| durationFormat.showSeconds | 持续时长是否显示秒                     | `boolean`，默认 `false`  |

#### 样式配置

| 参数             | 说明     | 类型                     |
|----------------|--------|------------------------|
| containerStyle | 容器样式   | `ContainerStyleConfig` |
| timeStyle      | 时间文本样式 | `TextStyleConfig`      |
| dateStyle      | 日期文本样式 | `TextStyleConfig`      |
| weekdayStyle   | 星期文本样式 | `TextStyleConfig`      |
| durationStyle  | 持续时长样式 | `TextStyleConfig`      |
| className      | 自定义类名  | `string`               |
| style          | 自定义样式  | `CSSProperties`        |

#### 国际化与事件

| 参数      | 说明       | 类型           |
|---------|----------|--------------|
| locale  | dayjs 语言 | `string`     |
| onClick | 点击回调     | `() => void` |

---

## 注意事项

1. **时区**：组件使用客户端本地时区，同一天判定基于本地自然日。
2. **依赖**：时间/日期/星期格式化复用 PisellDateTimeDisplay 的类型与逻辑。
3. **字段全隐藏**：若 fields 下所有块均不显示，组件返回 null。
4. **持续时长**：locale 为 zh 时输出「天/时/分/秒」，否则为 d/h/m/s。
