---
nav:
  title: 组件
  order: 1
group:
  title: Display
  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。
