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

# PisellReservationScheduleBand 预约顶栏时间轴

将 **PisellReservationSchedule**（营业日条）与 **PisellTimeNavigator**（横向时间轴）纵向组合为一块顶栏：统一受控值为
`{ date, at }` —— `date` 为日历日（按日对齐），`at` 为在该日上的时刻（与时轴选中一致）。适合作为 `PisellRecordBoard` 等容器的
`toolBar.tabs` 区域。

## 何时使用

- 需要先选「哪一天」，再在同一日内拖动/选择「哪个时刻」的预约视图
- 希望日历切换时保留「当天内的时分」，自动将时刻归并到新选中日（与日条联动）

## 代码演示

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

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

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

### 受控用法

首屏非受控（`defaultValue` 为空对象，由组件内部用当前日初始化）；用户操作后 `onChange` 得到带 `Dayjs` 的 `next` 再写入
state，之后转为受控。**不在示例中 import dayjs**。

```tsx
import { useState } from 'react';
import { PisellReservationScheduleBand } from '@pisell/materials';
import type { ReservationScheduleBandValue } from '@pisell/materials';

export default () => {
  const [value, setValue] = useState<ReservationScheduleBandValue>();

  return (
    <PisellReservationScheduleBand
      {...(value
        ? { value, onChange: setValue }
        : {
            defaultValue: {},
            onChange: (next) => setValue(next),
          })}
    />
  );
};
```

### 透传日程条与时间轴配置

`scheduleProps.minDate` / `maxDate` 使用可解析日期字符串；`defaultValue.date` 传字符串即可（组件内会转为 `Dayjs`）。

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

export default () => {
  return (
    <PisellReservationScheduleBand
      scheduleProps={{
        minDate: '2024-06-01',
        maxDate: '2024-06-30',
      }}
      timeNavigatorProps={{
        stepMinutes: 30,
        majorStepMinutes: 120,
        showNowButton: true,
      }}
      defaultValue={{ date: '2024-06-15' }}
    />
  );
};
```

## API

### PisellReservationScheduleBandProps

| 属性                 | 说明                                                                    | 类型                                             | 默认值 |
|--------------------|-----------------------------------------------------------------------|------------------------------------------------|-----|
| value              | 受控：`{ date, at }`                                                     | `ReservationScheduleBandValue`                 | -   |
| onChange           | `date` 或 `at` 变化时触发                                                   | `(next: ReservationScheduleBandValue) => void` | -   |
| defaultValue       | 非受控初始值，可只传部分字段                                                        | `Partial<ReservationScheduleBandValue>`        | -   |
| scheduleProps      | 透传 `PisellReservationSchedule`（无 value/onChange/defaultValue）         | 见类型定义                                          | -   |
| timeNavigatorProps | 透传 `PisellTimeNavigator`（无 value/onChange/referenceDate/defaultValue） | 见类型定义                                          | -   |
| className          | 根节点类名                                                                 | `string`                                       | -   |
| style              | 根节点样式                                                                 | `CSSProperties`                                | -   |

### ReservationScheduleBandValue

| 字段   | 说明                                      |
|------|-----------------------------------------|
| date | 当前日历日，`Dayjs`，内部使用 `startOf('day')`     |
| at   | 该日上的时刻，`Dayjs`；日切换时会将原时刻的时分秒合并到新 `date` |

## 行为说明

- **日变更**：`PisellReservationSchedule` `onChange` 时，`at` 的时分会保留并映射到新 `date` 的同一时刻（秒、毫秒归零按实现约定）。
- **时刻变更**：`PisellTimeNavigator` `onChange` 时，`date` 保持为当日，`at` 更新。
- **TimeNavigator.referenceDate**：始终为当前的 `effective.date`，无需在外部传入。
