---
nav:
  title: 组件
  order: 1
group:
  title: Data Entry
  order: 1
title: PisellTimeNavigator
order: 2
category: pro
---

# PisellTimeNavigator 时间导航轴

在指定时间范围内**拖动/点击**浏览与选择时刻的导航轴：渲染刻度、当前选中指示（气泡与竖线）、可选「Now」快捷入口，并通过
`onChange` 输出 `Dayjs`。不接入业务数据，可与 **PisellReservationScheduleBand**、**PisellRecordBoard** 等组合。

## 何时使用

- 预约、排班等场景需要在**一日内**连续选择时刻（支持跨日营业时段）
- 需要 **Realtime** 模式让选中时间跟随系统时钟，或 **userInteractionLocked** 只读跟随
- 需要横向或竖向布局、轴动/游标动两种交互模式

## 代码演示

### 基础用法（非受控）

`defaultValue` 支持可被 `dayjs` 解析的字符串（组件内部解析为当日锚定日上的时刻）。

```tsx
import React from 'react';
import { PisellTimeNavigator } from '@pisell/materials';

export default () => (
  <div style={{ height: 120 }}>
    <PisellTimeNavigator defaultValue="14:30" />
  </div>
);
```

### 受控用法

受控时传入 `value` 与 `onChange`；`value` 可为字符串或 `Dayjs` 实例。

```tsx
import React, { useState } from 'react';
import { PisellTimeNavigator } from '@pisell/materials';

export default () => {
  const [value, setValue] = useState<string>('12:00');
  return (
    <div style={{ height: 120 }}>
      <PisellTimeNavigator
        value={value}
        onChange={(d) => setValue(d.format('HH:mm'))}
      />
    </div>
  );
};
```

### 营业时间、跨日范围与禁用区间

`range` 定义轴上可选的时间窗（结束钟面小于等于开始时视为**次日**结束）。`businessHours` 用于视觉高亮；`disabledRanges`
禁止选入对应区间。

```tsx
import React from 'react';
import { PisellTimeNavigator } from '@pisell/materials';

export default () => (
  <div style={{ height: 120 }}>
    <PisellTimeNavigator
      defaultValue="10:00"
      range={{ start: '08:00', end: '22:00' }}
      businessHours={{ start: '09:00', end: '21:00' }}
      disabledRanges={[{ start: '12:00', end: '13:00' }]}
      stepMinutes={15}
    />
  </div>
);
```

### Realtime 与只读轴（锁定交互）

`realtime` 为 `true` 时选中时间随系统时间更新；与 **showNowButton** 互斥由业务侧约定（常见为 Realtime 时关闭 Now）。
`userInteractionLocked` 禁止拖动/点击改时间，仍随 `value` 对齐视口。

```tsx
import React from 'react';
import { PisellTimeNavigator } from '@pisell/materials';

export default () => (
  <div style={{ height: 120 }}>
    <PisellTimeNavigator
      realtime
      showNowButton={false}
      userInteractionLocked
    />
  </div>
);
```

### 竖向与 cursor-moves

```tsx
import React from 'react';
import { PisellTimeNavigator } from '@pisell/materials';

export default () => (
  <div style={{ width: 56, height: 400 }}>
    <PisellTimeNavigator
      orientation="vertical"
      cursorMode="cursor-moves"
      defaultValue="16:00"
    />
  </div>
);
```

## API

### PisellTimeNavigatorProps

| 属性                                                         | 说明                                          | 类型                         | 默认值            |
|------------------------------------------------------------|---------------------------------------------|----------------------------|----------------|
| value                                                      | 当前选中时间（受控），支持 `Dayjs`、可解析字符串或 `null`        | `TimeNavigatorValue`       | -              |
| onChange                                                   | 时间变更回调（受控时建议传入）                             | `(value: Dayjs) => void`   | -              |
| defaultValue                                               | 默认选中时间（非受控）                                 | `TimeNavigatorValue`       | -              |
| referenceDate                                              | 锚定日历日；`range` 的 HH:mm 均相对该日 0 点             | `TimeNavigatorValue`       | 不传则按「当天」0 点    |
| realtime                                                   | 是否跟随系统当前时间更新                                | `boolean`                  | `false`        |
| range                                                      | 时间轴范围（支持跨日营业）                               | `TimeRangeOption`          | 当日 00:00–24:00 |
| stepMinutes                                                | 吸附步长（分钟）                                    | `number`                   | `15`           |
| majorStepMinutes                                           | 大刻度间隔（分钟）                                   | `number`                   | `60`           |
| cursorMode                                                 | `axis-moves`：指示器居中轴动；`cursor-moves`：刻度固定游标动 | `CursorMode`               | `axis-moves`   |
| orientation                                                | 横向或竖向                                       | `horizontal` \| `vertical` | `horizontal`   |
| businessHours                                              | 营业时间（视觉高亮，可选限制选择）                           | `TimeRangeOption`          | -              |
| disabledRanges                                             | 禁用时间段                                       | `TimeRangeOption[]`        | -              |
| showNowButton                                              | 是否显示 Now 按钮                                 | `boolean`                  | `true`         |
| userInteractionLocked                                      | 禁止用户拖动/点击改时间                                | `boolean`                  | `false`        |
| snapToStep                                                 | 是否吸附到步长                                     | `boolean`                  | `false`        |
| inertia                                                    | 是否惯性滚动                                      | `boolean`                  | `false`        |
| pastTimeFade                                               | 过去时间区域淡化背景色                                 | `string`                   | -              |
| containerStyle / scaleStyle / cursorStyle / nowButtonStyle | 各层样式覆盖                                      | `CSSProperties`            | -              |
| className / style                                          | 根节点类名与样式                                    | `string` / `CSSProperties` | -              |
| locale                                                     | dayjs locale                                | `string`                   | 随引擎 `locale`   |
| timeFormat                                                 | 气泡时间格式（dayjs format）                        | `string`                   | `'HH:mm'`      |
| renderNowButton                                            | 自定义 Now 按钮                                  | `() => ReactNode`          | -              |

### 类型说明

- **TimeRangeOption**：`{ start: string; end: string }`，`start` / `end` 为 `HH:mm` 或 `HH:mm:ss`。
- **TimeNavigatorValue**：`Dayjs | string | null`。

## 行为说明

- **受控 / 非受控**：不要同时依赖 `value` 与 `defaultValue` 作为两套来源；受控时请提供 `onChange`。
- **referenceDate**：切换「营业日」时建议与上层日期对齐，避免跨自然日后刻度与业务日不一致。
- 多语言与文案通过 `@pisell/utils` 的 `locales` 与组件内置 `locales` 初始化，随低代码引擎 `locale` 变化。

## 相关文档

- [设计文档](./pisellTimeNavigator.$tab-design.md)
- [开发文档](./pisellTimeNavigator.$tab-dev.md)
- [测试文档](./pisellTimeNavigator.$tab-test.md)
- 组合使用：[PisellReservationScheduleBand](../../pisellReservationScheduleBand/docs/PisellReservationScheduleBand.md)
