# XTimeline

基于配置的时间轴组件，支持日期选择和日期范围导航，可通过配置动态调整显示方式和行为。

## 何时使用

当需要在界面中展示一个按日期排列的时间轴，并允许用户在日期之间进行选择和导航时使用。适用于日程安排、预约系统、历史记录查看等场景。

## 引用方式

```javascript
import XTimeline from '@vue2-client/base-client/components/common/XTimeline/XTimeline'

export default {
  components: {
    XTimeline
  }
}
```

## 代码演示

```html
<x-timeline
  v-model="selectedDate"
  :queryParamsName="timelineConfigName"
  @change="handleDateChange"
  @init="handleInit">
</x-timeline>
```

## API

| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|------|
| modelValue (v-model) | 当前选中的日期值 | String | '' |
| queryParamsName | 查询配置名称 | String | '' |

### 事件

| 事件名 | 说明 | 回调参数 |
|------|------|------|
| update:modelValue | 选中日期变化时触发，用于v-model绑定 | function(date: string) |
| change | 用户选择日期时触发 | function(date: string) |
| prev-week | 点击"前一周"按钮时触发 | function(date: string) |
| next-week | 点击"后一周"按钮时触发 | function(date: string) |
| prev-day | 点击"前一天"按钮时触发 | function(date: string) |
| next-day | 点击"后一天"按钮时触发 | function(date: string) |
| init | 组件初始化完成时触发 | function(date: string) |

## 配置说明

组件通过 `queryParamsName` 从后端获取配置，配置格式如下：

### 基本配置

```json
{
  "range": 7,
  "defaultValue": "",
  "dateFormat": "MM/DD",
  "weekFormat": "周dd",
  "prevWeekText": "前一周",
  "nextWeekText": "后一周",
  "prevDayText": "前一天",
  "nextDayText": "后一天",
  "minDate": "2024-01-01",
  "maxDate": "2099-12-31",
  "highlightWeekend": true,
  "logicName": "",
  "parameter": {}
}
```

### 指定默认日期的配置

```json
{
  "range": 7,
  "defaultValue": "2024-05-15",
  "dateFormat": "MM/DD",
  "weekFormat": "周dd",
  "prevWeekText": "前一周",
  "nextWeekText": "后一周",
  "prevDayText": "前一天",
  "nextDayText": "后一天",
  "minDate": "2024-01-01",
  "maxDate": "2024-12-31",
  "highlightWeekend": true
}
```

### 自定义日期格式的配置

```json
{
  "range": 7,
  "defaultValue": "",
  "dateFormat": "M月D日",
  "weekFormat": "ddd",
  "prevWeekText": "上周",
  "nextWeekText": "下周",
  "prevDayText": "前一天",
  "nextDayText": "后一天",
  "minDate": "2024-01-01",
  "maxDate": "2024-12-31",
  "highlightWeekend": true
}
```

## 注意事项

1. 时间轴固定显示周一到周日的七天日期，不可更改
2. 日期选择范围可通过 `minDate` 和 `maxDate` 进行限制
3. 如果配置中有 `defaultValue`，组件将默认选中该日期
4. 组件使用 dayjs 处理日期，支持其格式化语法
5. 周末日期可通过 `highlightWeekend` 配置是否高亮显示
6. 导航按钮文本可通过配置自定义
7. 点击"前一天"和"后一天"按钮会同时更新显示范围和选中的日期
8. 点击"前一周"和"后一周"按钮只会更新显示范围，不会改变选中的日期
9. 禁用的日期无法点击选择

## 常见问题解答（FAQ）

### 1. 如何设置默认选中的日期？

可以通过配置中的 `defaultValue` 字段设置：
```json
{
  "defaultValue": "2024-05-15"
}
```

或者通过 v-model 绑定：
```html
<x-timeline v-model="selectedDate"></x-timeline>
```

```javascript
export default {
  data() {
    return {
      selectedDate: "2024-05-15"
    }
  }
}
```

### 2. 如何限制可选日期范围？

通过配置中的 `minDate` 和 `maxDate` 字段设置：
```json
{
  "minDate": "2024-01-01",
  "maxDate": "2024-12-31"
}
```

### 3. 如何禁用特定日期？

可以通过配置中的 `logicName` 指定后端逻辑，返回包含 `disabledDates` 数组的结果：
```json
{
  "logicName": "getDisabledDates",
  "parameter": {
    "userId": "123"
  }
}
```

后端逻辑返回的结果格式为：
```json
{
  "disabledDates": ["2024-05-01", "2024-05-03", "2024-05-05"]
}
```

### 4. 如何自定义日期和星期的显示格式？

通过配置中的 `dateFormat` 和 `weekFormat` 字段设置：
```json
{
  "dateFormat": "YYYY年MM月DD日",
  "weekFormat": "ddd"
}
```

### 5. 点击导航按钮有什么区别？

- 点击"前一天"/"后一天"按钮：会更新显示范围并同时选中新的日期
- 点击"前一周"/"后一周"按钮：只更新显示范围，不会改变选中的日期
