# 日期选择器 & 日期时间选择器组件

一个基于 Svelte 构建的全面日期和时间选择组件库，提供灵活的日期和日期时间选择功能，支持多种显示模式和配置。

## 功能

- **日期选择器**：带日历弹窗的简单日期选择
- **日期时间选择器**：包含日历和时间面板的日期时间选择
- 多种视觉变体（普通、轮廓、填充）
- 支持键盘导航
- 最小/最大日期限制
- 支持必填字段
- 只读和禁用状态
- 仅显示模式，用于只读展示
- 国际化日期格式
- 支持 ARIA 的可访问性设计

## 安装

```typescript
import DatePicker from '@ticatec/uniface-element/DatePicker';
import DateTimePicker from '@ticatec/uniface-element/DateTimePicker';
```

## 日期选择器

### 基本用法

```svelte
<script>
  import DatePicker from '@ticatec/uniface-element/DatePicker;
  
  let selectedDate = null;
</script>

<DatePicker bind:value={selectedDate} placeholder="选择日期" />
```

### 属性

| 属性 | 类型 | 默认值 | 描述 |
|------|------|---------|-------------|
| `value` | `Date \| null` | `null` | 选中的日期值 |
| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | 视觉样式变体 |
| `disabled` | `boolean` | `false` | 禁用选择器 |
| `readonly` | `boolean` | `false` | 使选择器只读 |
| `compact` | `boolean` | `false` | 紧凑显示模式 |
| `mandatory` | `boolean` | `false` | 必填字段（隐藏清除按钮） |
| `style` | `string` | `''` | 自定义 CSS 样式 |
| `placeholder` | `string` | `""` | 输入占位符文本 |
| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | 显示模式（编辑/查看） |
| `min` | `UniDate` | `null` | 可选择的最小日期 |
| `max` | `UniDate` | `null` | 可选择的最大日期 |
| `onchange` | `OnChangeHandler<Date>` | `null` | 更改事件处理程序 |
| `onfocus` | `() => void` | `null` | 聚焦事件处理程序 |
| `onblur` | `() => void` | `null` | 失焦事件处理程序 |

### 方法

| 方法 | 描述 |
|--------|-------------|
| `setFocus()` | 以编程方式聚焦选择器 |

### 示例

#### 基本日期选择器
```svelte
<DatePicker bind:value={enrolmentDate} placeholder="选择注册日期" />
```

#### 轮廓必填日期选择器
```svelte
<DatePicker 
  variant="outlined" 
  mandatory 
  bind:value={birthday} 
  placeholder="出生日期（必填）" 
/>
```

#### 填充日期选择器
```svelte
<DatePicker 
  variant="filled" 
  bind:value={admissionDate} 
  placeholder="入学日期" 
/>
```

#### 带最小/最大日期限制的日期选择器
```svelte
<!-- 仅允许选择截至今天的日期 -->
<DatePicker 
  variant="filled" 
  max={new Date()} 
  bind:value={completedDate} 
  placeholder="完成日期" 
/>

<!-- 仅允许选择明天及以后的日期 -->
<DatePicker 
  variant="filled" 
  min={new Date()} 
  bind:value={bookFrom} 
  placeholder="预订开始日期" 
/>
```

#### 禁用和只读状态
```svelte
<!-- 禁用 -->
<DatePicker variant="filled" disabled bind:value={admissionDate} />

<!-- 只读 -->
<DatePicker variant="filled" readonly bind:value={admissionDate} />

<!-- 仅显示模式 -->
<DatePicker 
  displayMode={DisplayMode.View} 
  variant="filled" 
  readonly 
  bind:value={admissionDate} 
/>
```

## 日期时间选择器

### 基本用法

```svelte
<script>
  import DateTimePicker from '@ticatec/uniface-element/DateTimePicker';
  
  let selectedDateTime = null;
</script>

<DateTimePicker bind:value={selectedDateTime} placeholder="选择日期和时间" />
```

### 属性

| 属性 | 类型 | 默认值 | 描述 |
|------|------|---------|-------------|
| `value` | `UniDate` | `null` | 选中的日期时间值 |
| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | 视觉样式变体 |
| `disabled` | `boolean` | `false` | 禁用选择器 |
| `readonly` | `boolean` | `false` | 使选择器只读 |
| `compact` | `boolean` | `false` | 紧凑显示模式 |
| `mandatory` | `boolean` | `false` | 必填字段（隐藏清除按钮） |
| `style` | `string` | `''` | 自定义 CSS 样式 |
| `placeholder` | `string` | `""` | 输入占位符文本 |
| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | 显示模式（编辑/查看） |
| `min` | `UniDate` | `null` | 可选择的最小日期 |
| `max` | `UniDate` | `null` | 可选择的最大日期 |
| `precision` | `"H" \| "M" \| "S"` | `"M"` | 时间精度（小时/分钟/秒） |
| `onchange` | `OnChangeHandler<Date>` | `null` | 更改事件处理程序 |
| `onfocus` | `() => void` | `null` | 聚焦事件处理程序 |
| `onblur` | `() => void` | `null` | 失焦事件处理程序 |

### 方法

| 方法 | 描述 |
|--------|-------------|
| `setFocus()` | 以编程方式聚焦选择器 |

### 示例

#### 基本日期时间选择器
```svelte
<DateTimePicker bind:value={cutoffTime} placeholder="选择截止时间" />
```

#### 秒精度日期时间选择器
```svelte
<DateTimePicker 
  variant="outlined" 
  precision="S" 
  mandatory 
  bind:value={releaseDate} 
  placeholder="发布日期时间（精确到秒）" 
/>
```

#### 小时精度日期时间选择器
```svelte
<DateTimePicker 
  variant="filled" 
  precision="H" 
  bind:value={appointmentTime} 
  placeholder="预约时间（小时精度）" 
/>
```

## 时间精度

`DateTimePicker` 的 `precision` 属性控制时间粒度：

- **"H"**：小时精度（YYYY-MM-DD HH:00）
- **"M"**：分钟精度（YYYY-MM-DD HH:mm） - 默认
- **"S"**：秒精度（YYYY-MM-DD HH:mm:ss）

## 显示模式

两种组件均通过 `displayMode` 属性支持不同的显示模式：

- **`DisplayMode.Edit`**：完整编辑功能（默认）
- **`DisplayMode.View`**：只读显示模式

## 视觉变体

两种组件支持多种视觉样式：

- **默认**（`''`）：基本样式
- **`plain`**：极简样式
- **`outlined`**：轮廓边框样式
- **`filled`**：填充背景样式

## 键盘导航

两种组件均支持键盘导航：

- **Backspace/Delete**：清除选中的日期/时间
- **Escape**：关闭弹窗
- **Tab**：在界面中导航
- **Enter**：确认选择（在日期时间选择器中）

## 可访问性

- 全面支持屏幕阅读器的 ARIA
- 键盘导航
- 焦点管理
- 适当的标签和描述

## 日期格式

- **日期选择器**：YYYY-MM-DD
- **日期时间选择器**：
    - 小时精度：YYYY-MM-DD HH:mm
    - 分钟精度：YYYY-MM-DD HH:mm
    - 秒精度：YYYY-MM-DD HH:mm:ss

## 事件处理

```svelte
<script>
  function handleDateChange(date) {
    console.log('选择日期：', date);
  }
  
  function handleFocus() {
    console.log('选择器聚焦');
  }
  
  function handleBlur() {
    console.log('选择器失焦');
  }
</script>

<DatePicker 
  bind:value={selectedDate}
  onchange={handleDateChange}
  onfocus={handleFocus}
  onblur={handleBlur}
/>
```

## 样式

两种组件继承自 Uniface 设计系统的样式，并可通过 CSS 变量自定义：

```css
.uniface-date-time-editor {
  --uniface-inside-border-color: #f0f0f0;
  /* 添加自定义样式 */
}
```

## 表单集成

两种组件与 FormField 无缝协作：

```svelte
<script>
  import FormField from '$lib/form-field';
  import DatePicker, { DateTimePicker } from '$lib/date-picker';
</script>

<FormField label="出生日期">
  <DatePicker variant="outlined" mandatory bind:value={dateOfBirth} />
</FormField>

<FormField label="预约时间">
  <DateTimePicker variant="filled" precision="M" bind:value={appointmentTime} />
</FormField>
```

## 类型定义

```typescript
type UniDate = Date | dayjs.Dayjs | string | null;
type OnChangeHandler<T> = (value: T | null) => void;

enum DisplayMode {
  Edit = 'edit',
  View = 'view'
}
```

## 注意事项

- 组件内部使用 Day.js 进行日期操作
- 值始终以原生 JavaScript Date 对象返回
- 日历弹窗在选择日期后自动关闭
- 日期时间选择器在应用选择前需要确认
- 最小/最大日期限制在日历视图中强制执行
- 当 `mandatory` 为 true 时，清除按钮被隐藏