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

# PisellDateTimeDisplay 时间展示组件

## 组件介绍

PisellDateTimeDisplay 是一个专注于展示**当前时间**的组件，用于在不同终端（PC / Mobile / Kiosk）和不同语言环境下，统一展示当前日期、时间与星期信息。

**核心特性**：

- ✅ 自动展示当前时间（自动刷新）
- ✅ 丰富的格式化配置（时间、日期、星期）
- ✅ 三种布局方式（水平、垂直、单行）
- ✅ 国际化支持（自动翻译月份和星期）
- ✅ 高度可配置的样式系统
- ✅ 自定义格式化字符串（类似 dayjs）

---

## 基础用法

### 简单示例

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

export default () => {
    return <PisellDateTimeDisplay/>;
};
```

### 基础配置

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            {/* 默认样式 */}
            <PisellDateTimeDisplay/>

            {/* 显示秒 */}
            <PisellDateTimeDisplay
                timeFormat={{showSeconds: true}}
            />

            {/* 12小时制 */}
            <PisellDateTimeDisplay
                timeFormat={{use12Hour: true}}
            />
        </div>
    );
};
```

---

## 布局配置

### 水平布局（默认）

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

export default () => {
    return (
        <PisellDateTimeDisplay
            layout="horizontal"
        />
    );
};
```

### 垂直布局

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

export default () => {
    return (
        <PisellDateTimeDisplay
            layout="vertical"
        />
    );
};
```

### 单行布局

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            {/* 默认分隔符 */}
            <PisellDateTimeDisplay
                layout="inline"
            />

            {/* 自定义分隔符 */}
            <PisellDateTimeDisplay
                layout="inline"
                inlineSeparator=" | "
            />

            {/* 空格分隔符 */}
            <PisellDateTimeDisplay
                layout="inline"
                inlineSeparator=" "
            />
        </div>
    );
};
```

### 对齐方式

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16, width: 300}}>
            {/* 左对齐 */}
            <div style={{border: '1px solid #d9d9d9', padding: 16}}>
                <PisellDateTimeDisplay textAlign="left"/>
            </div>

            {/* 居中对齐 */}
            <div style={{border: '1px solid #d9d9d9', padding: 16}}>
                <PisellDateTimeDisplay textAlign="center"/>
            </div>

            {/* 右对齐 */}
            <div style={{border: '1px solid #d9d9d9', padding: 16}}>
                <PisellDateTimeDisplay textAlign="right"/>
            </div>
        </div>
    );
};
```

---

## 时间格式

### 24小时制（默认）

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            {/* 默认格式：13:45 */}
            <PisellDateTimeDisplay
                timeFormat={{use12Hour: false}}
            />

            {/* 显示秒：13:45:30 */}
            <PisellDateTimeDisplay
                timeFormat={{use12Hour: false, showSeconds: true}}
            />

            {/* 小时补零：01:45 */}
            <PisellDateTimeDisplay
                timeFormat={{use12Hour: false, padHour: true}}
            />

            {/* 只显示小时：13 */}
            <PisellDateTimeDisplay
                timeFormat={{onlyShowHour: true}}
            />
        </div>
    );
};
```

### 12小时制

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            {/* 12小时制：1:45 PM */}
            <PisellDateTimeDisplay
                timeFormat={{use12Hour: true}}
            />

            {/* 显示秒：1:45:30 PM */}
            <PisellDateTimeDisplay
                timeFormat={{use12Hour: true, showSeconds: true}}
            />

            {/* 小时补零：01:45 PM */}
            <PisellDateTimeDisplay
                timeFormat={{use12Hour: true, padHour: true}}
            />
        </div>
    );
};
```

---

## 日期格式

### 日期顺序

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            {/* 年-月-日 */}
            <PisellDateTimeDisplay
                dateFormat={{order: 'YMD', showYear: true}}
            />

            {/* 月-日-年 */}
            <PisellDateTimeDisplay
                dateFormat={{order: 'MDY', showYear: true}}
            />

            {/* 日-月-年 */}
            <PisellDateTimeDisplay
                dateFormat={{order: 'DMY', showYear: true}}
            />
        </div>
    );
};
```

### 字段显隐

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            {/* 完整日期 */}
            <PisellDateTimeDisplay
                dateFormat={{showYear: true, showMonth: true, showDay: true}}
            />

            {/* 只显示月日 */}
            <PisellDateTimeDisplay
                dateFormat={{showYear: false, showMonth: true, showDay: true}}
            />

            {/* 只显示年月 */}
            <PisellDateTimeDisplay
                dateFormat={{showYear: true, showMonth: true, showDay: false}}
            />
        </div>
    );
};
```

### 英文月份格式

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            {/* 简写月份：Mar */}
            <PisellDateTimeDisplay
                locale="en"
                dateFormat={{shortMonth: true}}
            />

            {/* 完整月份：March */}
            <PisellDateTimeDisplay
                locale="en"
                dateFormat={{shortMonth: false}}
            />

            {/* 数字月份：03 */}
            <PisellDateTimeDisplay
                locale="en"
                dateFormat={{numericMonth: true}}
            />
        </div>
    );
};
```

### 中文日期格式

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            {/* 不带单位：3-21 */}
            <PisellDateTimeDisplay
                locale="zh-cn"
                dateFormat={{showChineseUnit: false}}
            />

            {/* 带单位：3月21日 */}
            <PisellDateTimeDisplay
                locale="zh-cn"
                dateFormat={{showChineseUnit: true}}
            />

            {/* 完整日期：2026年3月21日 */}
            <PisellDateTimeDisplay
                locale="zh-cn"
                dateFormat={{showYear: true, showChineseUnit: true}}
            />
        </div>
    );
};
```

### 自定义分隔符

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            {/* 短横线 */}
            <PisellDateTimeDisplay
                dateFormat={{showYear: true, separator: '-'}}
            />

            {/* 斜杠 */}
            <PisellDateTimeDisplay
                dateFormat={{showYear: true, separator: '/'}}
            />

            {/* 点 */}
            <PisellDateTimeDisplay
                dateFormat={{showYear: true, separator: '.'}}
            />
        </div>
    );
};
```

---

## 星期格式

### 英文星期

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            {/* 默认（缩写）：Sat */}
            <PisellDateTimeDisplay
                locale="en"
                weekdayFormat={{full: false, singleLetter: false}}
            />

            {/* 完整：Saturday */}
            <PisellDateTimeDisplay
                locale="en"
                weekdayFormat={{full: true}}
            />

            {/* 单字母：S */}
            <PisellDateTimeDisplay
                locale="en"
                weekdayFormat={{singleLetter: true}}
            />
        </div>
    );
};
```

### 中文星期

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            {/* 默认（缩写）：周六 */}
            <PisellDateTimeDisplay
                locale="zh-cn"
                weekdayFormat={{full: false, singleLetter: false}}
            />

            {/* 完整：星期六 */}
            <PisellDateTimeDisplay
                locale="zh-cn"
                weekdayFormat={{full: true}}
            />

            {/* 单字母：六 */}
            <PisellDateTimeDisplay
                locale="zh-cn"
                weekdayFormat={{singleLetter: true}}
            />
        </div>
    );
};
```

---

## 字段控制

### 字段显隐

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            {/* 只显示时间 */}
            <PisellDateTimeDisplay
                fields={{showTime: true, showDate: false, showWeekday: false}}
            />

            {/* 只显示日期 */}
            <PisellDateTimeDisplay
                fields={{showTime: false, showDate: true, showWeekday: false}}
            />

            {/* 只显示星期 */}
            <PisellDateTimeDisplay
                fields={{showTime: false, showDate: false, showWeekday: true}}
            />

            {/* 显示时间和日期 */}
            <PisellDateTimeDisplay
                fields={{showTime: true, showDate: true, showWeekday: false}}
            />
        </div>
    );
};
```

### 字段排序

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            {/* 默认顺序：时间、日期、星期 */}
            <PisellDateTimeDisplay
                fields={{fieldOrder: ['time', 'date', 'weekday']}}
            />

            {/* 日期在前 */}
            <PisellDateTimeDisplay
                fields={{fieldOrder: ['date', 'time', 'weekday']}}
            />

            {/* 星期在前 */}
            <PisellDateTimeDisplay
                fields={{fieldOrder: ['weekday', 'date', 'time']}}
            />
        </div>
    );
};
```

---

## 自定义格式化

### 标准格式

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            {/* ISO 格式 */}
            <PisellDateTimeDisplay
                customFormat="YYYY-MM-DD HH:mm:ss"
            />

            {/* 简短格式 */}
            <PisellDateTimeDisplay
                customFormat="MM/DD HH:mm"
            />

            {/* 中文格式 */}
            <PisellDateTimeDisplay
                customFormat="YYYY年MM月DD日 HH:mm"
            />

            {/* 包含星期 */}
            <PisellDateTimeDisplay
                customFormat="YYYY-MM-DD dddd HH:mm"
            />
        </div>
    );
};
```

---

## 刷新配置

### 自动刷新

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            {/* 默认刷新（60秒） */}
            <PisellDateTimeDisplay/>

            {/* 显示秒（1秒刷新） */}
            <PisellDateTimeDisplay
                timeFormat={{showSeconds: true}}
            />

            {/* 自定义刷新间隔（5秒） */}
            <PisellDateTimeDisplay
                refreshInterval={5000}
            />

            {/* 禁用自动刷新 */}
            <PisellDateTimeDisplay
                disableAutoRefresh={true}
            />
        </div>
    );
};
```

---

## 国际化

### 语言切换

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            {/* 中文 */}
            <PisellDateTimeDisplay
                locale="zh-cn"
                dateFormat={{showYear: true, showChineseUnit: true}}
            />

            {/* 英文 */}
            <PisellDateTimeDisplay
                locale="en"
                dateFormat={{showYear: true}}
            />

            {/* 日文 */}
            <PisellDateTimeDisplay
                locale="ja"
                dateFormat={{showYear: true}}
            />
        </div>
    );
};
```

---

## 样式配置

### 容器样式

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

export default () => {
    return (
        <div style={{display: 'flex', gap: 16}}>
            {/* 默认样式 */}
            <PisellDateTimeDisplay/>

            {/* 自定义容器样式 */}
            <PisellDateTimeDisplay
                containerStyle={{
                    background: '#f5f5f5',
                    borderRadius: 8,
                    border: '1px solid #d9d9d9',
                    padding: 16,
                }}
            />
        </div>
    );
};
```

### 文本样式

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

export default () => {
    return (
        <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
            {/* 自定义时间样式 */}
            <PisellDateTimeDisplay
                timeStyle={{
                    fontSize: 32,
                    fontWeight: 700,
                    color: '#1890ff',
                }}
            />

            {/* 自定义所有样式 */}
            <PisellDateTimeDisplay
                timeStyle={{
                    fontSize: 28,
                    fontWeight: 600,
                    color: '#000',
                }}
                dateStyle={{
                    fontSize: 16,
                    fontWeight: 400,
                    color: '#666',
                }}
                weekdayStyle={{
                    fontSize: 14,
                    fontWeight: 400,
                    color: '#999',
                }}
            />
        </div>
    );
};
```

---

## 应用场景

### 后台首页

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

export default () => {
    return (
        <div style={{padding: 24, background: '#fff', borderRadius: 8}}>
            <PisellDateTimeDisplay
                layout="horizontal"
                timeFormat={{showSeconds: false}}
                dateFormat={{showYear: true, showChineseUnit: true}}
                locale="zh-cn"
                timeStyle={{fontSize: 32, fontWeight: 700}}
                dateStyle={{fontSize: 18, fontWeight: 400, color: '#666'}}
                weekdayStyle={{fontSize: 18, fontWeight: 400, color: '#666'}}
            />
        </div>
    );
};
```

### 欢迎页

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

export default () => {
    return (
        <div
            style={{
                height: 300,
                display: 'flex',
                alignItems: 'center',
                justifyContent: 'center',
                background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
                borderRadius: 8,
            }}
        >
            <PisellDateTimeDisplay
                layout="vertical"
                textAlign="center"
                timeFormat={{use12Hour: true, showSeconds: true}}
                dateFormat={{showYear: true}}
                locale="en"
                containerStyle={{
                    background: 'rgba(255, 255, 255, 0.2)',
                    borderRadius: 16,
                    padding: 32,
                }}
                timeStyle={{
                    fontSize: 48,
                    fontWeight: 700,
                    color: '#fff',
                }}
                dateStyle={{
                    fontSize: 20,
                    fontWeight: 400,
                    color: 'rgba(255, 255, 255, 0.9)',
                }}
                weekdayStyle={{
                    fontSize: 18,
                    fontWeight: 400,
                    color: 'rgba(255, 255, 255, 0.8)',
                }}
            />
        </div>
    );
};
```

### 大屏展示

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

export default () => {
    return (
        <div
            style={{
                height: 200,
                display: 'flex',
                alignItems: 'center',
                justifyContent: 'center',
                background: '#000',
                borderRadius: 8,
            }}
        >
            <PisellDateTimeDisplay
                layout="inline"
                inlineSeparator=" "
                timeFormat={{showSeconds: true}}
                dateFormat={{showYear: true}}
                customFormat="YYYY-MM-DD HH:mm:ss"
                containerStyle={{
                    padding: 24,
                }}
                style={{
                    fontSize: 48,
                    fontWeight: 700,
                    color: '#0f0',
                    fontFamily: 'monospace',
                }}
            />
        </div>
    );
};
```

### 状态栏

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

export default () => {
    return (
        <div
            style={{
                display: 'flex',
                justifyContent: 'space-between',
                alignItems: 'center',
                padding: '12px 24px',
                background: '#001529',
                color: '#fff',
            }}
        >
            <div style={{fontSize: 18, fontWeight: 600}}>
                系统管理后台
            </div>

            <PisellDateTimeDisplay
                layout="inline"
                inlineSeparator=" | "
                timeFormat={{showSeconds: false}}
                dateFormat={{showYear: false}}
                locale="zh-cn"
                style={{color: 'rgba(255, 255, 255, 0.8)'}}
            />
        </div>
    );
};
```

---

## 事件回调

### 时间更新回调

```tsx
import {PisellDateTimeDisplay} from '@pisell/materials';
import {message} from 'antd';
import type {Dayjs} from 'dayjs';

export default () => {
    const handleTimeUpdate = (currentTime: Dayjs) => {
        console.log('当前时间:', currentTime.format('YYYY-MM-DD HH:mm:ss'));
    };

    return (
        <PisellDateTimeDisplay
            timeFormat={{showSeconds: true}}
            onTimeUpdate={handleTimeUpdate}
        />
    );
};
```

### 点击事件

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

export default () => {
    const handleClick = () => {
        message.info('时间组件被点击了！');
    };

    return (
        <PisellDateTimeDisplay
            onClick={handleClick}
            style={{cursor: 'pointer'}}
        />
    );
};
```

---

## API

### PisellDateTimeDisplayProps

#### 布局配置

| 参数              | 说明      | 类型                                       | 默认值            |
|-----------------|---------|------------------------------------------|----------------|
| layout          | 布局方向    | `'horizontal' \| 'vertical' \| 'inline'` | `'horizontal'` |
| textAlign       | 文本对齐方式  | `'left' \| 'center' \| 'right'`          | `'left'`       |
| inlineSeparator | 单行模式分隔符 | `string`                                 | `' · '`        |

#### 字段配置

| 参数                 | 说明       | 类型            | 默认值                           |
|--------------------|----------|---------------|-------------------------------|
| fields.showTime    | 是否显示时间字段 | `boolean`     | `true`                        |
| fields.showDate    | 是否显示日期字段 | `boolean`     | `true`                        |
| fields.showWeekday | 是否显示星期字段 | `boolean`     | `true`                        |
| fields.fieldOrder  | 字段顺序     | `FieldType[]` | `['time', 'date', 'weekday']` |

#### 时间格式配置

| 参数                      | 说明        | 类型        | 默认值     |
|-------------------------|-----------|-----------|---------|
| timeFormat.use12Hour    | 是否使用12小时制 | `boolean` | `false` |
| timeFormat.showSeconds  | 是否显示秒     | `boolean` | `false` |
| timeFormat.padHour      | 小时是否补零    | `boolean` | `false` |
| timeFormat.onlyShowHour | 是否只显示小时   | `boolean` | `false` |

#### 日期格式配置

| 参数                         | 说明          | 类型                        | 默认值     |
|----------------------------|-------------|---------------------------|---------|
| dateFormat.order           | 日期顺序        | `'YMD' \| 'MDY' \| 'DMY'` | `'YMD'` |
| dateFormat.shortMonth      | 英文月份是否简写    | `boolean`                 | `true`  |
| dateFormat.numericMonth    | 英文月份是否数字展示  | `boolean`                 | `false` |
| dateFormat.showChineseUnit | 中文是否显示"年月日" | `boolean`                 | `false` |
| dateFormat.separator       | 分隔符         | `string`                  | `'-'`   |
| dateFormat.showYear        | 是否显示年       | `boolean`                 | `false` |
| dateFormat.showMonth       | 是否显示月       | `boolean`                 | `true`  |
| dateFormat.showDay         | 是否显示日       | `boolean`                 | `true`  |

#### 星期格式配置

| 参数                         | 说明      | 类型        | 默认值     |
|----------------------------|---------|-----------|---------|
| weekdayFormat.full         | 是否完整展示  | `boolean` | `false` |
| weekdayFormat.singleLetter | 是否单字母展示 | `boolean` | `false` |

#### 高级配置

| 参数                 | 说明           | 类型        | 默认值     |
|--------------------|--------------|-----------|---------|
| customFormat       | 自定义格式化字符串    | `string`  | -       |
| refreshInterval    | 刷新间隔（毫秒）     | `number`  | 自动计算    |
| disableAutoRefresh | 是否禁用自动刷新     | `boolean` | `false` |
| locale             | dayjs locale | `string`  | 系统语言    |

#### 样式配置

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

#### 事件回调

| 参数           | 说明     | 类型                             |
|--------------|--------|--------------------------------|
| onTimeUpdate | 时间更新回调 | `(currentTime: Dayjs) => void` |
| onClick      | 点击回调   | `() => void`                   |

---

## 常见问题

### 1. 为什么组件不刷新？

确保没有设置 `disableAutoRefresh={true}`：

```
<PisellDateTimeDisplay disableAutoRefresh={false} />
```

### 2. 如何修改刷新间隔？

```
// 默认：不显示秒时60秒刷新，显示秒时1秒刷新
// 自定义：5秒刷新一次
<PisellDateTimeDisplay refreshInterval={5000} />
```

### 3. 如何使用自定义格式？

使用 `customFormat` 属性（优先级最高）：

```
<PisellDateTimeDisplay customFormat="YYYY-MM-DD HH:mm:ss" />
```

支持的格式化标记（dayjs）：

- `YYYY` - 4位年份（2026）
- `MM` - 2位月份（03）
- `DD` - 2位日期（21）
- `HH` - 24小时制小时（13）
- `hh` - 12小时制小时（01）
- `mm` - 2位分钟（45）
- `ss` - 2位秒（30）
- `A` - 上午/下午（AM/PM）
- `dddd` - 星期全称（Saturday）
- `ddd` - 星期缩写（Sat）

### 4. 如何切换语言？

```
// 中文
<PisellDateTimeDisplay locale="zh-cn" />

// 英文
<PisellDateTimeDisplay locale="en" />

// 日文
<PisellDateTimeDisplay locale="ja" />
```

### 5. 如何隐藏某个字段？

```
<PisellDateTimeDisplay
  fields={{
    showTime: true,
    showDate: true,
    showWeekday: false  // 隐藏星期
  }}
/>
```

### 6. 定时器会自动清理吗？

会的。组件卸载时会自动清除定时器，不会造成内存泄漏。

---

## 最佳实践

### 1. 根据场景选择布局

- **后台首页**：使用水平布局，显示完整信息
- **状态栏**：使用单行布局，节省空间
- **欢迎页**：使用垂直布局，视觉效果更好
- **大屏**：使用单行布局或自定义格式

### 2. 合理设置刷新间隔

- **一般场景**：不显示秒，60秒刷新（省资源）
- **精确场景**：显示秒，1秒刷新
- **静态展示**：禁用自动刷新

### 3. 国际化配置

- 根据用户语言动态设置 `locale`
- 中文用户使用 `showChineseUnit: true`
- 英文用户根据习惯选择日期顺序（MDY 或 DMY）

### 4. 样式一致性

- 保持同一页面中时间展示的样式一致
- 使用主题色系统，避免硬编码颜色
- 根据背景色调整文本颜色对比度

### 5. 性能优化

- 避免在列表中大量使用（会创建多个定时器）
- 如需在列表中使用，考虑使用 `disableAutoRefresh={true}`
- 使用相同刷新间隔的组件会更高效

---

## 注意事项

1. **时区**：组件使用客户端本地时区，不支持时区切换
2. **定时器**：组件卸载时会自动清除定时器
3. **格式化优先级**：`customFormat` > 其他格式配置
4. **字段全隐藏**：如果所有字段都隐藏，组件返回 null
5. **国际化**：确保 dayjs 已加载对应的 locale

---

## 更新日志

### v1.0.0 (2026-01-29)

- ✨ 首次发布
- ✅ 支持当前时间展示（自动刷新）
- ✅ 三种布局方式
- ✅ 丰富的格式化配置
- ✅ 国际化支持
- ✅ 高度可配置的样式系统
- ✅ 自定义格式化字符串
