x-next 1.13.0 → 1.14.0

package/AI_USAGE/components/time-picker-api.md

@@ -0,0 +1,137 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# TimePicker 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## TimePicker API
+
+公开声明：`dist/components/time-picker/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| type | 选择器类型 | undefined &#124; "time" &#124; "time-range" | 否 | "time" |
+| modelValue | 绑定值 | undefined &#124; string &#124; number &#124; Date &#124; TimePickerValue[] | 否 | 未声明 |
+| defaultValue | 默认值 | undefined &#124; string &#124; number &#124; Date &#124; TimePickerValue[] | 否 | 未声明 |
+| placeholder | 占位文案 | undefined &#124; string &#124; string[] | 否 | 未声明 |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false |
+| readonly | 是否只读 | undefined &#124; false &#124; true | 否 | false |
+| error | 是否错误态 | undefined &#124; false &#124; true | 否 | false |
+| allowClear | 是否允许清除 | undefined &#124; false &#124; true | 否 | true |
+| format | 展示和解析格式 | undefined &#124; string | 否 | 未声明 |
+| size | 输入框尺寸 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" | 否 | 未声明 |
+| popupVisible | 控制弹层显示 | undefined &#124; false &#124; true | 否 | undefined |
+| defaultPopupVisible | 默认弹层显示 | undefined &#124; false &#124; true | 否 | false |
+| position | 弹出位置 | undefined &#124; "top" &#124; "bottom" &#124; "tl" &#124; "tr" &#124; "bl" &#124; "br" | 否 | "bl" |
+| popupContainer | 弹层挂载容器 | undefined &#124; string &#124; HTMLElement | 否 | 未声明 |
+| triggerProps | 透传 Trigger 配置 | undefined &#124; { [x: string]: any; } | 否 | 未声明 |
+| unmountOnClose | 关闭后销毁面板 | undefined &#124; false &#124; true | 否 | false |
+| step | 时 / 分 / 秒步长 | undefined &#124; TimePickerStep | 否 | 未声明 |
+| disabledHours | 禁用小时 | undefined &#124; () => number[] | 否 | 未声明 |
+| disabledMinutes | 禁用分钟 | undefined &#124; (selectedHour?: number) => number[] | 否 | 未声明 |
+| disabledSeconds | 禁用秒 | undefined &#124; (selectedHour?: number, selectedMinute?: number) => number[] | 否 | 未声明 |
+| hideDisabledOptions | 隐藏禁用项 | undefined &#124; false &#124; true | 否 | false |
+| disableConfirm | 点击时间后立即提交 | undefined &#124; false &#124; true | 否 | false |
+| use12Hours | 12 小时制 | undefined &#124; false &#124; true | 否 | false |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:modelValue | 值更新 | undefined &#124; (_value: TimePickerModelValue) => any |
+| update:popupVisible | 受控弹层更新 | undefined &#124; (_visible: boolean) => any |
+| change | 确认值变化 | undefined &#124; (_timeString: string &#124; (string &#124; undefined)[] &#124; undefined, _time: unknown) => any |
+| select | 面板选择但未必提交 | undefined &#124; (_timeString: string &#124; (string &#124; undefined)[], _time: unknown) => any |
+| clear | 点击清除 | undefined &#124; (_ev: MouseEvent) => any |
+| popup-visible-change | 见场景用法与类型 | undefined &#124; (_visible: boolean) => any |
+| focus | 输入框聚焦 | undefined &#124; (_ev: FocusEvent) => any |
+| blur | 输入框失焦 | undefined &#124; (_ev: FocusEvent) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| prefix | 输入框前缀 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| suffix-icon | 输入框后缀图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| extra | 面板页脚额外内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type TimePickerType = 'time' | 'time-range';
+
+type TimePickerValue = string | number | Date;
+
+type TimePickerRangeValue = [TimePickerValue | undefined, TimePickerValue | undefined];
+
+type TimePickerModelValue = TimePickerValue | TimePickerValue[] | undefined;
+
+type TimePickerPosition = 'top' | 'tl' | 'tr' | 'bottom' | 'bl' | 'br';
+
+type TimePickerSize = 'mini' | 'small' | 'medium' | 'large';
+
+type TimePickerColumnType = 'hour' | 'minute' | 'second' | 'meridiem';
+
+type TimePickerMeridiem = 'AM' | 'PM';
+
+interface TimePickerStep {
+    hour?: number;
+    minute?: number;
+    second?: number;
+}
+
+interface TimePickerColumnItem {
+    value: number | TimePickerMeridiem;
+    label: string;
+    disabled?: boolean;
+    selected?: boolean;
+}
+
+type TimePickerDisabledHours = () => number[];
+
+type TimePickerDisabledMinutes = (selectedHour?: number) => number[];
+
+type TimePickerDisabledSeconds = (selectedHour?: number, selectedMinute?: number) => number[];
+
+interface TimePickerProps {
+    type?: TimePickerType;
+    modelValue?: TimePickerModelValue;
+    defaultValue?: TimePickerModelValue;
+    placeholder?: string | string[];
+    disabled?: boolean;
+    readonly?: boolean;
+    error?: boolean;
+    allowClear?: boolean;
+    format?: string;
+    size?: TimePickerSize;
+    popupVisible?: boolean;
+    defaultPopupVisible?: boolean;
+    position?: TimePickerPosition;
+    popupContainer?: string | HTMLElement;
+    triggerProps?: Partial<TriggerProps>;
+    unmountOnClose?: boolean;
+    step?: TimePickerStep;
+    disabledHours?: TimePickerDisabledHours;
+    disabledMinutes?: TimePickerDisabledMinutes;
+    disabledSeconds?: TimePickerDisabledSeconds;
+    hideDisabledOptions?: boolean;
+    disableConfirm?: boolean;
+    use12Hours?: boolean;
+}
+
+type TimePickerPanelValue = Date | undefined;
+
+type TimePickerRangePanelValue = [Date | undefined, Date | undefined];
+```
+
+
+返回 [TimePicker 用法](./time-picker.md)。

package/AI_USAGE/components/time-picker.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # TimePicker AI 使用
 
-适用版本：x-next@1.13.0；来源指纹：`18e9b8eefa53b4bd91134fb4486778509ccf3a8d614a1bd387a6d469b623ddcf`。
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
 
-先读 [通用接入](../core.md)。公开导出：`TimePicker`；模型：v-model、v-model:popup-visible；已核对事件：change。
+先读 [通用接入](../core.md)。公开导出：`TimePicker`；主要模型：v-model、v-model:popup-visible。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./time-picker-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`x-next/style/time-picker`（包含 base.css、button.css、scrollbar-v2.css、time-picker.css、trigger.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
 
+## 已核验行为与示例
+
 [组件文档与 live demo](https://x-next.yjmf.com/components/time-picker)。默认 `type='time'`、`allowClear=true`、`disableConfirm=false`，默认格式为 `'HH:mm:ss'`。`format` 同时决定显示与输出；`step` 用 `{ hour, minute, second }`，各步长默认 `1`。
 
 `change(timeString, time)` 是确认值变化，`select` 是面板选择；字符串载荷为 `string | (string | undefined)[] | undefined`，第二参数为 `unknown`。清空发出 `update:modelValue(undefined)` 和 `change(undefined, undefined)`；本例的业务 `update()` 才归一化为 `''` 保持单值字符串受控。支持 `prefix` / `suffix-icon` / `extra` 插槽及 `disabledHours` 等限制。
@@ -31,4 +33,270 @@ function changed(value: string | (string | undefined)[] | undefined, _time: unkn
 </template>
 ```
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/time-picker.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./time-picker-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于在表单中输入或选择具体时间点，也可以选择开始和结束时间。需要拖拽配置一天内多个时间段时，请使用 [TimeRangeSelector 时间范围选择](./time-range-selector.md)。
+
+
+### 何时使用
+
+- 用户需要填写开始时间、截止时间、提醒时间、任务执行时间等具体时间点。
+- 用户需要在筛选表单中选择一个开始和结束时间。
+- 需要固定格式、步长或禁用某些时间项时。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { TimePicker } from 'x-next';
+import { ref } from 'vue';
+
+const time = ref('09:30:00');
+</script>
+<template>
+<TimePicker v-model="time" />
+</template>
+```
+
+### 受控值和事件
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { TimePicker } from 'x-next';
+import { ref } from 'vue';
+
+const time = ref('13:45:00');
+const popupVisible = ref(false);
+const handleSelect = (value: string | (string | undefined)[] | undefined) => console.log('select', value);
+const handleChange = (value: string | (string | undefined)[] | undefined) => console.log('change', value);
+const handleClear = () => console.log('clear');
+</script>
+<template>
+<TimePicker
+    v-model="time"
+    v-model:popup-visible="popupVisible"
+    allow-clear
+    @select="handleSelect"
+    @change="handleChange"
+    @clear="handleClear"
+  />
+</template>
+```
+
+### 默认值和范围
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { TimePicker } from 'x-next';
+import { ref } from 'vue';
+
+const range = ref(['09:00:00', '18:00:00']);
+</script>
+<template>
+<TimePicker default-value="18:24:23" />
+  <TimePicker v-model="range" type="time-range" />
+</template>
+```
+
+### 尺寸
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { TimePicker } from 'x-next';
+import { ref } from 'vue';
+const time = ref('09:30:00');
+</script>
+<template>
+<TimePicker v-model="time" size="mini" />
+  <TimePicker v-model="time" size="small" />
+  <TimePicker v-model="time" size="medium" />
+  <TimePicker v-model="time" size="large" />
+</template>
+```
+
+### 状态
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { TimePicker } from 'x-next';
+import { ref } from 'vue';
+const time = ref('09:30:00');
+</script>
+<template>
+<TimePicker v-model="time" allow-clear />
+  <TimePicker default-value="09:00:00" readonly />
+  <TimePicker default-value="09:00:00" disabled />
+  <TimePicker v-model="time" error />
+</template>
+```
+
+### 格式和步长
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { TimePicker } from 'x-next';
+import { ref } from 'vue';
+const shortTime = ref('09:30');
+const time = ref('09:30:00');
+</script>
+<template>
+<TimePicker v-model="shortTime" format="HH:mm" />
+  <TimePicker
+    v-model="time"
+    :step="{ hour: 2, minute: 15, second: 30 }"
+  />
+</template>
+```
+
+### 禁用时间
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { TimePicker } from 'x-next';
+import { ref } from 'vue';
+
+const time = ref('14:00:00');
+const disabledHours = () => [0, 1, 2, 3, 4, 5, 22, 23];
+const disabledMinutes = (hour?: number) => (hour === 12 ? [0, 15, 30, 45] : []);
+const disabledSeconds = () => Array.from({ length: 30 }, (_, index) => index);
+</script>
+<template>
+<TimePicker
+    v-model="time"
+    :disabled-hours="disabledHours"
+    :disabled-minutes="disabledMinutes"
+    :disabled-seconds="disabledSeconds"
+    hide-disabled-options
+  />
+</template>
+```
+
+### 12 小时制
+
+开启后时间为「时 / 分 / 秒 / 上午下午」四列，面板宽度会随可见列数自适应。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { TimePicker } from 'x-next';
+import { ref } from 'vue';
+
+const time = ref('9:15:00 AM');
+const range = ref(['9:00:00 AM', '6:30:00 PM']);
+</script>
+<template>
+<TimePicker v-model="time" use12-hours />
+  <TimePicker v-model="range" type="time-range" use12-hours />
+</template>
+```
+
+### 自定义内容
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { TimePicker } from 'x-next';
+import { ref } from 'vue';
+const time = ref('09:30:00');
+</script>
+<template>
+<TimePicker v-model="time">
+    <template #prefix>班次</template>
+    <template #suffix-icon>⌚</template>
+    <template #extra>选择值：{{ time || '未选择' }}</template>
+  </TimePicker>
+</template>
+```
+
+### 表单组合
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Form, FormItem, TimePicker, Space, Button } from 'x-next';
+import { reactive, ref } from 'vue';
+import type { FormInstance, FieldRule } from 'x-next';
+const formRef = ref<FormInstance>();
+const formModel = reactive({ startTime: '', workRange: ['09:00:00', '18:00:00'] });
+const formResult = ref('点击校验查看结果');
+const handleFormValidate = async () => {
+  const errors = await formRef.value!.validate();
+  formResult.value = errors
+    ? `校验失败：${Object.values(errors).map((error) => error.message).join('；')}`
+    : '校验通过';
+};
+const handleFormReset = () => {
+  formRef.value!.resetFields();
+  formResult.value = '已重置';
+};
+</script>
+<template>
+<Form ref="formRef" :model="formModel">
+    <FormItem field="startTime" label="开始时间" required feedback>
+      <TimePicker v-model="formModel.startTime" allow-clear />
+    </FormItem>
+    <FormItem field="workRange" label="工作时段">
+      <TimePicker v-model="formModel.workRange" type="time-range" />
+    </FormItem>
+    <FormItem>
+      <Space>
+        <Button type="primary" @click="handleFormValidate">校验</Button>
+        <Button @click="handleFormReset">重置</Button>
+      </Space>
+    </FormItem>
+  </Form>
+  <p role="status">{{ formResult }}</p>
+</template>
+```
+
+### 键盘操作与焦点
+
+每列只保留一个 Tab 停靠点，读屏通过 `aria-activedescendant` 获知当前选项；禁用项不可选择。方向键调整面板草稿，默认需要“确定”提交，Esc 关闭并保留原值。`disableConfirm` 开启后选项变化立即提交。确认或 Esc 后焦点返回输入；范围输入恢复原生 Tab，面板末端 Tab 可正常离开。
+
+原生 `id`、`name`、ARIA 和输入事件透传到真实输入；范围末端 ID 使用 `ID-end`。Form 自动关联标签和错误说明。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { TimePicker } from 'x-next';
+import { ref } from 'vue';
+const time = ref('10:30:00');
+const range = ref(['09:00:00', '18:00:00']);
+const log = ref('等待确认');
+const disabledHours = () => [0, 1, 2, 3, 4, 5, 22, 23];
+const onChange = (value: string | (string | undefined)[] | undefined) => { log.value = `change: ${value || '空'}`; };
+import type { HTMLAttributes } from 'vue';
+const nativeAttrs1 = { "aria-label": "预约时间" } satisfies HTMLAttributes;
+const nativeAttrs2 = { "aria-label": "预约时间范围" } satisfies HTMLAttributes;
+</script>
+<template>
+<TimePicker v-bind="nativeAttrs1" v-model="time"  :disabled-hours="disabledHours" @change="onChange" />
+  <TimePicker v-bind="nativeAttrs2" v-model="range" type="time-range"  />
+  <p>{{ log }}</p>
+</template>
+```
+
+### 交互说明
+
+- `TimePicker` 用于表单字段中的具体时间点或开始 / 结束时间。
+- `TimeRangeSelector` 用于拖拽配置一天内多个时间段，两者不是替代关系。
+- 非法手动输入不会提交新值；按 Enter 或失焦时会尝试按 `format` 解析。
+- `disableConfirm` 开启后，点击面板时间项会立即提交。
+- 范围模式会在同一个面板内并排展示开始时间和结束时间，左侧选择开始时间，右侧选择结束时间。
+- 面板底部的“此刻”会把当前列值设置为系统当前时间，范围模式下作用于最近操作的开始或结束时间。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./time-picker-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/time-range-selector-api.md

@@ -0,0 +1,44 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# TimeRangeSelector 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## TimeRangeSelector API
+
+公开声明：`dist/components/time-range-selector/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| modelValue | 时间范围数组 | [string, string][] | 否 | 未声明 |
+| color | 组件主色，会写入 --x-time-range-selector-color 并派生轨道、选中段和手柄颜色 | undefined &#124; string | 否 | 未声明 |
+| scene | 场景风格，适配常规筛选、排班预约、监控时段和紧凑筛选 | undefined &#124; "default" &#124; "compact" &#124; "monitor" &#124; "schedule" | 否 | "default" |
+| overlapAllowed | 是否允许时间段重叠 | undefined &#124; false &#124; true | 否 | false |
+| stepMinutes | 时间块步长，单位分钟；非法或不能整除 1440 时降级为 30 | undefined &#124; number | 否 | 30 |
+| disabledRanges | 禁用时间范围 | undefined &#124; [string, string][] | 否 | [] |
+| maxRanges | 最多可创建范围数量 | undefined &#124; number | 否 | Infinity |
+| showCursor | 是否显示下方 0-24 小时游标 | undefined &#124; false &#124; true | 否 | true |
+| disabled | 整体禁用，继承 Form / FormItem 禁用状态 | undefined &#124; false &#124; true | 否 | false |
+| readonly | 只读，允许聚焦但不允许修改 | undefined &#124; false &#124; true | 否 | false |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:modelValue | 时间范围提交或约束重新归一化后触发 | undefined &#124; (value: [string, string][]) => any |
+| change | 用户完成修改且值变化时触发，外部同步不触发 | undefined &#124; (value: [string, string][]) => any |
+| remove | 用户删除时间段时触发 | undefined &#124; (value: [string, string]) => any |
+
+### Slots
+
+公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+
+返回 [TimeRangeSelector 用法](./time-range-selector.md)。