@ticatec/uniface-element 0.2.3 → 0.3.0

package/dist/date-picker/README_CN.md

@@ -0,0 +1,316 @@
+# 日期选择器 & 日期时间选择器组件
+
+一个基于 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 时，清除按钮被隐藏

package/dist/date-picker/ScrollBar.svelte

@@ -5,7 +5,7 @@
     export let value: number;
     export let mode: 24 | 60 = 60;
     export let enable: boolean = true;
-    export let onChange: OnChangeHandler<number> = null as unknown as OnChangeHandler<number>;
+    export let onchange: OnChangeHandler<number> = null as unknown as OnChangeHandler<number>;
 
     let list: Array<any> = [];
 
@@ -25,7 +25,7 @@
 
     const resetList = () => {
         list = [];
-        onChange?.(value);
+        onchange?.(value);
         for (let i=0; i<7; i++) {
             list.push((value + i - 3 + mode) % mode);
         }
@@ -66,25 +66,35 @@
         resetList();
     }
 
+    const handleKeyDown = (handler: () => void) => (e: KeyboardEvent) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            handler();
+        }
+    }
+
     let timer: any;
 
     $:resetList();
 
 </script>
-<div class="scroll-bar" tabindex="-1" aria-hidden="true" on:wheel={handleMouseWheel}>
+<div class="scroll-bar" on:wheel={handleMouseWheel}>
     <div class="action-bar">
         <div class="arrow-up" class:disabled={!enable}>
-            <i class="icon_google_keyboard_arrow_up" aria-hidden="true" on:click={decValue} on:dragstart={(e)=>{e.preventDefault()}}
-                 on:mousedown={handleMouseDown(-1)} on:mouseup={handleMouseUp} on:mouseleave={handleMouseUp}></i>
+            <i class="icon_google_keyboard_arrow_up" on:click={decValue} on:keydown={handleKeyDown(decValue)} on:dragstart={(e)=>{e.preventDefault()}}
+                 on:mousedown={handleMouseDown(-1)} on:mouseup={handleMouseUp} on:mouseleave={handleMouseUp}
+                 role="button" tabindex="0" aria-label="Decrease value"></i>
         </div>
     </div>
     {#each list as v}
-        <div style={!enable && v!= value ? "visibility: hidden; " : ""} class="digital-block" aria-hidden="true" on:click={()=>{handleDigitalClick(v)}} class:inactive={v!=value}><span>{v}</span></div>
+        <div style={!enable && v!= value ? "visibility: hidden; " : ""} class="digital-block" on:click={()=>{handleDigitalClick(v)}} on:keydown={handleKeyDown(() => handleDigitalClick(v))} class:inactive={v!=value}
+             role="button" tabindex="0" aria-label="Select {v}"><span>{v}</span></div>
     {/each}
     <div class="action-bar">
         <div class="arrow-down" class:disabled={!enable}>
-            <i class="icon_google_keyboard_arrow_downn" aria-hidden="true" on:click={incValue} on:dragstart={(e)=>{e.preventDefault()}}
-                 on:mousedown={handleMouseDown(1)} on:mouseup={handleMouseUp} on:mouseleave={handleMouseUp}></i>
+            <i class="icon_google_keyboard_arrow_downn" on:click={incValue} on:keydown={handleKeyDown(incValue)} on:dragstart={(e)=>{e.preventDefault()}}
+                 on:mousedown={handleMouseDown(1)} on:mouseup={handleMouseUp} on:mouseleave={handleMouseUp}
+                 role="button" tabindex="0" aria-label="Increase value"></i>
         </div>
     </div>
 </div>

package/dist/date-picker/ScrollBar.svelte.d.ts

@@ -16,7 +16,7 @@ declare const ScrollBar: $$__sveltets_2_IsomorphicComponent<{
     value: number;
     mode?: 24 | 60;
     enable?: boolean;
-    onChange?: OnChangeHandler<number>;
+    onchange?: OnChangeHandler<number>;
 }, {
     [evt: string]: CustomEvent<any>;
 }, {}, {}, string>;

package/dist/date-picker/TimePanel.svelte

@@ -9,7 +9,7 @@
     export let value: UniDate;
     export let style: string = '';
     export let precision: "H" | "M" | "S" = "M";
-    export let onChange: OnChangeHandler<dayjs.Dayjs> = null as unknown as OnChangeHandler<dayjs.Dayjs>;
+    export let onchange: OnChangeHandler<dayjs.Dayjs> = null as unknown as OnChangeHandler<dayjs.Dayjs>;
 
     let hour: number, minute: number, second: number;
     let time: dayjs.Dayjs = dateUtils.toDayjs(value);
@@ -22,17 +22,17 @@
 
     const resetTime = (unit: dayjs.UnitType) => (v: number) => {
         time = time.set(unit, v);
-        onChange(time);
+        onchange(time);
     }
 
 </script>
 <div class="time-picker-panel" {style}>
     <div class="scroll-panel" style="flex: 1 1 auto">
-        <ScrollBar bind:value={hour} mode={24} onChange={resetTime('hour')}/>
+        <ScrollBar bind:value={hour} mode={24} onchange={resetTime('hour')}/>
         {#if precision === "M" || precision === "S"}
-            <ScrollBar bind:value={minute} onChange={resetTime('minute')}/>
+            <ScrollBar bind:value={minute} onchange={resetTime('minute')}/>
             {#if precision === "S"}
-                <ScrollBar bind:value={second} onChange={resetTime('second')}/>
+                <ScrollBar bind:value={second} onchange={resetTime('second')}/>
             {/if}
         {/if}
     </div>

package/dist/date-picker/TimePanel.svelte.d.ts

@@ -18,7 +18,7 @@ declare const TimePanel: $$__sveltets_2_IsomorphicComponent<{
     value: UniDate;
     style?: string;
     precision?: "H" | "M" | "S";
-    onChange?: OnChangeHandler<dayjs.Dayjs>;
+    onchange?: OnChangeHandler<dayjs.Dayjs>;
 }, {
     [evt: string]: CustomEvent<any>;
 }, {}, {}, string>;