x-next 1.18.0 → 1.18.1

package/AI_USAGE.md

@@ -1,9 +1,9 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # x-next AI 使用手册
 
-适用版本：**x-next@1.18.0**。Vue：`^3.5.0`；Node：`>=20.19.0`。
+适用版本：**x-next@1.18.1**。Vue：`^3.5.0`；Node：`>=20.19.0`。
 
-来源指纹（AI 行为说明、docs 导入快照、映射、样式依赖、版本、公开类型和 API 参考）：`a0432ebab3728998205092a9a7e188702b81ff8c0550430bc02ff73b265af282`。
+来源指纹（AI 行为说明、docs 导入快照、映射、样式依赖、版本、公开类型和 API 参考）：`5a7a6ac6864f5c967d7414c6cb2bf7b0470f3208f35e8ece68ed34b3b2716d83`。
 
 覆盖 59 个组件族与 106 个公开组件/服务导出。优先通过 [本地按需索引](./AI_USAGE/index.md) 读取组件页和 API，不为查本包用法默认搜索网络。
 
@@ -534,6 +534,8 @@ function restore() { visible.value = true; feedback.value = '提示显示中'; }
 
 [组件文档与 live demo](https://x-next.yjmf.com/components/dialog)。从根入口导入 `DialogComponent as XDialog`，普通 `v-model` 为布尔值且默认 `false`。`renderTo='body'`、`mask=true`、`maskToClose=true`、`escToClose=true`、`destroyOnClosed=true`；`width` 支持数字或 CSS 长度。
 
+声明式组件默认 `center=false`、`top='100px'`，`top` 仅在非居中、非全屏时生效；命令式 `Dialog(options)` 保持默认居中，其服务默认 `top=0`。
+
 `title`、默认正文、`footer` 是公开插槽，默认不生成业务按钮。`close(action, event?)` 的 action 为 `'cancel' | 'ok'`，`closed` 表示关闭动画结束；直接改模型不会调用业务取消逻辑。根入口服务 `Dialog(options)` 返回 `close()` / `update(options)` 句柄。
 
 ```vue
@@ -680,6 +682,8 @@ function cancel(_event: Event) { feedback.value = '已取消删除'; }
 
 `popup-visible-change(visible)` 返回布尔值，`show` / `hide` 无参数。点击触发器或外部默认可以关闭；`popupContainer` 和 `renderToBody` 决定宿主，用于定位、滚动及裁剪。通过 ConfigProvider 配置的主题会由 Trigger 同步到浮层根，默认挂到 body 也生效；任意业务 CSS 变量或仅在局部 DOM 调用 applyThemeColor 不等于该注入协议，仍要核对实际继承。
 
+Escape 从触发器、内容或鼠标打开后的 body 焦点关闭当前最上层 Popover，并归还触发器焦点；组合输入期间保留浮层。关闭和卸载会清理键盘监听，focus 触发模式不会因焦点归还重新打开。
+
 ```vue
 <script setup lang="ts">
 import { ref } from 'vue';
@@ -730,7 +734,7 @@ function advance() { percent.value = Math.min(1, percent.value + 0.25); }
 
 [组件文档与 live demo](https://x-next.yjmf.com/components/dropdown)。使用 `v-model:popup-visible`，默认 `trigger='click'`、`position='bottom'`、`hideOnSelect=true`。根入口导出 `DropdownOption`、`DropdownGroup`、`DropdownSubmenu`；菜单内容放 `content` 插槽，另有 `empty` / `footer` 插槽。
 
-`select(value, event)` 返回 `string | number | Record<string, any> | undefined` 和 `Event`，`popup-visible-change` 返回布尔值。选项支持 `disabled`；字符搜索 typeahead、自定义控件的通用键盘代理及 Tab 自动关闭仍有边界，不能据方向键导航推断这些能力已实现。
+`select(value, event)` 返回 `string | number | Record<string, any> | undefined` 和 `Event`，`popup-visible-change` 返回布尔值。选项支持 `disabled`；Tab / Shift+Tab 从触发器、菜单项或子菜单退出根菜单，并从根触发器继续浏览器默认顺序导航。字符搜索 typeahead、自定义控件的通用键盘代理仍有边界，不能据方向键导航推断这些能力已实现。
 
 ```vue
 <script setup lang="ts">
@@ -1912,7 +1916,7 @@ const sizes = ['mini', 'small', 'medium', 'large', 'huge'] as const;
 
 ### 尺寸
 
-`mini`、`small`、`medium`、`large`、`huge` 的默认高度分别为 24、28、32、36、38px。
+`mini`、`small`、`medium`、`large`、`huge` 的默认高度分别为 24、28、32、36、38px，字号分别为 12、13、14、15、16px。
 
 以下为默认主题中的尺寸规格；链接和形状选项会按对应规则调整布局。
 
@@ -1921,8 +1925,8 @@ const sizes = ['mini', 'small', 'medium', 'large', 'huge'] as const;
 | `mini` | 24px | 12px | 500 | 8px | 4px |
 | `small` | 28px | 13px | 500 | 10px | 4px |
 | `medium` | 32px | 14px | 500 | 14px | 4px |
-| `large` | 36px | 14px | 500 | 20px | 6px |
-| `huge` | 38px | 16px | 500 | 28px | 6px |
+| `large` | 36px | 15px | 500 | 16px | 6px |
+| `huge` | 38px | 16px | 500 | 20px | 6px |
 
 ```vue
 <script setup lang="ts">
@@ -4869,6 +4873,10 @@ const range = ref(['2026-06-01', '2026-06-30']);
 
 ### 中国农历展示
 
+### 农历空辅助行和禁用状态
+
+只显示节日和节气时，部分日期没有辅助文案；数字、选中圆圈和范围色带仍共用同一日期区。周末禁用时，数字与农历文字一同弱化，包括绑定值已命中禁用日期的情况。
+
 ```vue
 <script setup lang="ts">
 import 'x-next/style.css';
@@ -4887,6 +4895,24 @@ const range = ref(['2026-06-19', '2026-09-25']);
 </template>
 ```
 
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { RangePicker, DatePicker } from 'x-next';
+import { ref } from 'vue';
+const range = ref(['2026-06-19', '2026-07-07']);
+const date = ref('2026-06-20');
+const disabledDate = (current: Date) => [0, 6].includes(current.getDay());
+import type { HTMLAttributes } from 'vue';
+const nativeAttrs1 = { "aria-label": "节日节气范围" } satisfies HTMLAttributes;
+const nativeAttrs2 = { "aria-label": "农历日期" } satisfies HTMLAttributes;
+</script>
+<template>
+<RangePicker v-bind="nativeAttrs1" v-model="range" :show-lunar="{ showLunarDate: false }"  />
+  <DatePicker v-bind="nativeAttrs2" v-model="date" show-lunar :disabled-date="disabledDate"  />
+</template>
+```
+
 ### 带时间的日期选择
 
 ```vue
@@ -4904,6 +4930,51 @@ const dateTimeRange = ref(['2026-06-02 00:00:00', '2026-07-29 09:09:06']);
 </template>
 ```
 
+### 手输与禁用规则
+
+第一项可输入 `2026-06-06`（禁用周末）或 `2026-02-31`（不存在的日期），按 Enter 后会恢复原值。第二项可输入 `2026-06-04 15:46:12`，提交后保留时分秒；0–8 时和每小时 30 分不可选，也不能通过手输提交。`disabledTime` 按字段覆盖 `timePickerProps` 中的时间禁用函数。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { DatePicker } from 'x-next';
+import { ref } from 'vue';
+const date = ref('2026-06-04');
+const dateTime = ref('2026-06-04 09:15:00');
+const log = ref('等待有效提交');
+const disabledDate = (current: Date) => [0, 6].includes(current.getDay());
+const timeProps = { disabledHours: () => [0, 1, 2, 3, 4, 5, 6, 7, 8] };
+const disabledTime = () => ({ disabledMinutes: () => [30] });
+import type { HTMLAttributes } from 'vue';
+const nativeAttrs1 = { "aria-label": "预约日期" } satisfies HTMLAttributes;
+const nativeAttrs2 = { "aria-label": "预约日期时间" } satisfies HTMLAttributes;
+</script>
+<template>
+<DatePicker v-bind="nativeAttrs1" v-model="date" :disabled-date="disabledDate"  />
+  <DatePicker v-bind="nativeAttrs2" v-model="dateTime" show-time :time-picker-props="timeProps" :disabled-time="disabledTime"  @change="log = `提交：${$event}`" />
+  <p>{{ date }}；{{ dateTime }}；{{ log }}</p>
+</template>
+```
+
+### 周一起始的周选择
+
+周选择的网格、点击、手输和提交保持相同的周起始日。下方可输入 `2026-40th`，或选择 2026 年 9 月 28 日到 10 月 4 日中的任一天，再重新打开确认高亮行。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { WeekPicker } from 'x-next';
+import { ref } from 'vue';
+const week = ref('2026-40th');
+import type { HTMLAttributes } from 'vue';
+const nativeAttrs1 = { "aria-label": "排期周" } satisfies HTMLAttributes;
+</script>
+<template>
+<WeekPicker v-bind="nativeAttrs1" v-model="week" :day-start-of-week="1"  />
+  <p>{{ week }}</p>
+</template>
+```
+
 ### 月范围和受控面板
 
 ```vue
@@ -4976,18 +5047,24 @@ const date = ref('2026-09-30');
 
 ### 状态
 
+范围仅禁用一端时，面板与手输只更新另一端，并保持原有起止顺序；为避免清掉锁定值，此时隐藏整体清空按钮。
+
 ```vue
 <script setup lang="ts">
 import 'x-next/style.css';
-import { DatePicker } from 'x-next';
+import { DatePicker, RangePicker } from 'x-next';
 import { ref } from 'vue';
 const date = ref('2026-09-30');
+const range = ref(['2026-06-01', '2026-06-30']);
+import type { HTMLAttributes } from 'vue';
+const nativeAttrs1 = { "aria-label": "开始日期已锁定" } satisfies HTMLAttributes;
 </script>
 <template>
 <DatePicker v-model="date" allow-clear />
   <DatePicker default-value="2026-06-04" readonly />
   <DatePicker default-value="2026-06-04" disabled />
   <DatePicker v-model="date" error />
+  <RangePicker v-bind="nativeAttrs1" v-model="range" :disabled="[true, false]"  />
 </template>
 ```
 
@@ -5141,7 +5218,9 @@ const nativeAttrs2 = { "aria-label": "预约日期范围" } satisfies HTMLAttrib
 
 - `showTime` 仅在日期和日期范围模式生效，默认格式为 `YYYY-MM-DD HH:mm:ss`，选择后需要点击“确定”提交。
 - `showLunar` 仅影响日期格辅助展示，不改变 `modelValue`、`format`、范围排序或禁用逻辑；内置数据来自香港天文台 1901-2100 年公历 / 农历对照表，超出范围时默认不展示。
-- 非法手动输入不会提交新值；按 Enter 或失焦时会尝试按 `format` 解析。
+- 合法手输按 Enter 或失焦提交，日期时间保留时分秒。不存在的日期、越界时间或命中禁用规则的输入会恢复已提交值；编辑空草稿期间不立即回填。
+- 今天、快捷项与确认提交同样遵守禁用规则；确认前规则变化导致草稿不可选时，“确定”按钮禁用。日期时间面板点选仍需点击“确定”提交。
+- 面板标题为年月文本，使用左右箭头翻页；当前不提供点击标题进行年月视图下钻。
 - 普通范围选择会在选择结束值后自动排序并提交；开启 `showTime` 后需要点击“确定”提交。
 - `valueFormat="timestamp"` 会让绑定值和事件值返回时间戳。
 
@@ -5720,6 +5799,8 @@ const beforeClose = async (action: 'cancel' | 'ok') => {
 
 ### 显示方式
 
+默认对话框距离顶部 `100px`，可通过 `top` 自定义；设置 `center` 后垂直居中，`fullscreen` 则占满容器。右上角关闭按钮悬停时显示背景，也支持键盘聚焦。
+
 ```vue
 <script setup lang="ts">
 import 'x-next/style.css';
@@ -20450,7 +20531,7 @@ type GridItemInstance = InstanceType<typeof _GridItem>;
 | pickerValue | 面板显示日期 | undefined &#124; string &#124; number &#124; Date &#124; (DatePickerValue &#124; undefined)[] | 否 | 未声明 |
 | defaultPickerValue | 默认面板显示日期 | undefined &#124; string &#124; number &#124; Date &#124; (DatePickerValue &#124; undefined)[] | 否 | 未声明 |
 | placeholder | 占位文案 | undefined &#124; string &#124; string[] | 否 | 未声明 |
-| disabled | 是否禁用 | undefined &#124; false &#124; true &#124; boolean[] | 否 | false |
+| disabled | 是否禁用；范围数组分别锁定两端，单端锁定时只更新另一端并隐藏整体清空 | undefined &#124; false &#124; true &#124; boolean[] | 否 | false |
 | readonly | 是否只读 | undefined &#124; false &#124; true | 否 | false |
 | disabledInput | 禁止输入框键盘输入但允许面板选择 | undefined &#124; false &#124; true | 否 | false |
 | inputReadOnly | 输入框只读，常用于移动端避免软键盘 | undefined &#124; false &#124; true | 否 | false |
@@ -20472,8 +20553,8 @@ type GridItemInstance = InstanceType<typeof _GridItem>;
 | showToday | 是否显示今天 / 本月 / 今年按钮 | undefined &#124; false &#124; true | 否 | true |
 | showConfirmBtn | 是否显示确认按钮 | undefined &#124; false &#124; true | 否 | false |
 | showTime | 是否开启日期时间选择，仅 date / date-range 生效 | undefined &#124; false &#124; true | 否 | false |
-| timePickerProps | 时间列配置，支持 format、step、use12Hours、disabledHours、disabledMinutes、disabledSeconds、hideDisabledOptions、defaultValue | undefined &#124; { [x: string]: any; } | 否 | 未声明 |
-| disabledTime | 禁用时间，需要配合 showTime 使用 | undefined &#124; (current?: Date, type?: DatePickerRange) => Record<string, any> &#124; undefined | 否 | 未声明 |
+| timePickerProps | 时间列配置，支持 format、step、use12Hours、disabledHours、disabledMinutes、disabledSeconds、hideDisabledOptions、defaultValue | undefined &#124; DatePickerTimePickerProps | 否 | 未声明 |
+| disabledTime | 禁用时间，需要配合 showTime 使用 | undefined &#124; (current?: Date, type?: DatePickerRange) => DatePickerDisabledTimeProps &#124; undefined | 否 | 未声明 |
 | showLunar | 是否展示中国农历辅助信息，支持控制农历日期、农历节日、节气和公历节日 | undefined &#124; false &#124; true &#124; { showLunarDate?: boolean; showLunarFestival?: boolean; showSolarTerm?: boolean; showSolarFestival?: boolean; fallbackText?: string; } | 否 | false |
 
 ### Events
@@ -20504,9 +20585,12 @@ type GridItemInstance = InstanceType<typeof _GridItem>;
 | cell | 自定义日期单元格 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
 | extra | 面板快捷区额外内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
 
-### 实例方法
+### 实例方法 / 暴露值
 
-没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+| 名称 | 公开类型 |
+| --- | --- |
+| focus | () => void |
+| blur | () => void |
 
 ### 关联类型定义
 
@@ -20709,7 +20793,7 @@ interface DialogCaller {
 | renderTo | 见场景用法与类型 | undefined &#124; string &#124; HTMLElement | 否 | "body" |
 | disabled | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false |
 | modelValue | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false |
-| top | 见场景用法与类型 | undefined &#124; string &#124; number | 否 | "3vh" |
+| top | 见场景用法与类型 | undefined &#124; string &#124; number | 否 | "100px" |
 | center | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false |
 | width | 见场景用法与类型 | undefined &#124; string &#124; number | 否 | 0 |
 | height | 见场景用法与类型 | undefined &#124; string &#124; number | 否 | 0 |
@@ -21060,6 +21144,7 @@ type DropdownOption = DOption | DGroup | DSubmenu;
 
 interface DropdownContext {
     popupMaxHeight: boolean | number;
+    onTabOut?: () => void;
     onOptionClick: (value: string | number | Record<string, unknown> | undefined, ev: Event) => void;
 }
 
@@ -21169,6 +21254,7 @@ type DropdownOption = DOption | DGroup | DSubmenu;
 
 interface DropdownContext {
     popupMaxHeight: boolean | number;
+    onTabOut?: () => void;
     onOptionClick: (value: string | number | Record<string, unknown> | undefined, ev: Event) => void;
 }
 
@@ -21263,6 +21349,7 @@ type DropdownOption = DOption | DGroup | DSubmenu;
 
 interface DropdownContext {
     popupMaxHeight: boolean | number;
+    onTabOut?: () => void;
     onOptionClick: (value: string | number | Record<string, unknown> | undefined, ev: Event) => void;
 }
 
@@ -21363,6 +21450,7 @@ type DropdownOption = DOption | DGroup | DSubmenu;
 
 interface DropdownContext {
     popupMaxHeight: boolean | number;
+    onTabOut?: () => void;
     onOptionClick: (value: string | number | Record<string, unknown> | undefined, ev: Event) => void;
 }
 
@@ -21469,6 +21557,7 @@ type DropdownOption = DOption | DGroup | DSubmenu;
 
 interface DropdownContext {
     popupMaxHeight: boolean | number;
+    onTabOut?: () => void;
     onOptionClick: (value: string | number | Record<string, unknown> | undefined, ev: Event) => void;
 }
 
@@ -29088,8 +29177,8 @@ interface IMessageItem extends Required<Pick<IMessageOptions, 'duration' | 'posi
 | showToday | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | 透传内层组件；默认值见对应组件 |
 | showConfirmBtn | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | 透传内层组件；默认值见对应组件 |
 | showTime | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | 透传内层组件；默认值见对应组件 |
-| timePickerProps | 见场景用法与类型 | undefined &#124; { [x: string]: any; } | 否 | 透传内层组件；默认值见对应组件 |
-| disabledTime | 见场景用法与类型 | undefined &#124; (current?: Date, type?: DatePickerRange) => Record<string, any> &#124; undefined | 否 | 透传内层组件；默认值见对应组件 |
+| timePickerProps | 见场景用法与类型 | undefined &#124; DatePickerTimePickerProps | 否 | 透传内层组件；默认值见对应组件 |
+| disabledTime | 见场景用法与类型 | undefined &#124; (current?: Date, type?: DatePickerRange) => DatePickerDisabledTimeProps &#124; undefined | 否 | 透传内层组件；默认值见对应组件 |
 | showLunar | 见场景用法与类型 | undefined &#124; false &#124; true &#124; { showLunarDate?: boolean; showLunarFestival?: boolean; showSolarTerm?: boolean; showSolarFestival?: boolean; fallbackText?: string; } | 否 | 透传内层组件；默认值见对应组件 |
 
 ### Events
@@ -29114,9 +29203,12 @@ interface IMessageItem extends Required<Pick<IMessageOptions, 'duration' | 'posi
 
 公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
 
-### 实例方法
+### 实例方法 / 暴露值
 
-没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+| 名称 | 公开类型 |
+| --- | --- |
+| focus | (() => void) & (() => void) |
+| blur | (() => void) & (() => void) |
 
 ### 关联类型定义
 
@@ -29974,8 +30066,8 @@ type PopconfirmTypes = 'primary' | 'success' | 'warning' | 'strong' | 'danger' |
 | showToday | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | 透传内层组件；默认值见对应组件 |
 | showConfirmBtn | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | 透传内层组件；默认值见对应组件 |
 | showTime | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | 透传内层组件；默认值见对应组件 |
-| timePickerProps | 见场景用法与类型 | undefined &#124; { [x: string]: any; } | 否 | 透传内层组件；默认值见对应组件 |
-| disabledTime | 见场景用法与类型 | undefined &#124; (current?: Date, type?: DatePickerRange) => Record<string, any> &#124; undefined | 否 | 透传内层组件；默认值见对应组件 |
+| timePickerProps | 见场景用法与类型 | undefined &#124; DatePickerTimePickerProps | 否 | 透传内层组件；默认值见对应组件 |
+| disabledTime | 见场景用法与类型 | undefined &#124; (current?: Date, type?: DatePickerRange) => DatePickerDisabledTimeProps &#124; undefined | 否 | 透传内层组件；默认值见对应组件 |
 | showLunar | 见场景用法与类型 | undefined &#124; false &#124; true &#124; { showLunarDate?: boolean; showLunarFestival?: boolean; showSolarTerm?: boolean; showSolarFestival?: boolean; fallbackText?: string; } | 否 | 透传内层组件；默认值见对应组件 |
 
 ### Events
@@ -30000,9 +30092,12 @@ type PopconfirmTypes = 'primary' | 'success' | 'warning' | 'strong' | 'danger' |
 
 公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
 
-### 实例方法
+### 实例方法 / 暴露值
 
-没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+| 名称 | 公开类型 |
+| --- | --- |
+| focus | (() => void) & (() => void) |
+| blur | (() => void) & (() => void) |
 
 ### 关联类型定义
 
@@ -30315,8 +30410,8 @@ interface RadioGroupContext {
 | showToday | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | 透传内层组件；默认值见对应组件 |
 | showConfirmBtn | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | 透传内层组件；默认值见对应组件 |
 | showTime | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | 透传内层组件；默认值见对应组件 |
-| timePickerProps | 见场景用法与类型 | undefined &#124; { [x: string]: any; } | 否 | 透传内层组件；默认值见对应组件 |
-| disabledTime | 见场景用法与类型 | undefined &#124; (current?: Date, type?: DatePickerRange) => Record<string, any> &#124; undefined | 否 | 透传内层组件；默认值见对应组件 |
+| timePickerProps | 见场景用法与类型 | undefined &#124; DatePickerTimePickerProps | 否 | 透传内层组件；默认值见对应组件 |
+| disabledTime | 见场景用法与类型 | undefined &#124; (current?: Date, type?: DatePickerRange) => DatePickerDisabledTimeProps &#124; undefined | 否 | 透传内层组件；默认值见对应组件 |
 | showLunar | 见场景用法与类型 | undefined &#124; false &#124; true &#124; { showLunarDate?: boolean; showLunarFestival?: boolean; showSolarTerm?: boolean; showSolarFestival?: boolean; fallbackText?: string; } | 否 | 透传内层组件；默认值见对应组件 |
 
 ### Events
@@ -30341,9 +30436,12 @@ interface RadioGroupContext {
 
 公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
 
-### 实例方法
+### 实例方法 / 暴露值
 
-没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+| 名称 | 公开类型 |
+| --- | --- |
+| focus | (() => void) & (() => void) |
+| blur | (() => void) & (() => void) |
 
 ### 关联类型定义
 
@@ -36542,8 +36640,8 @@ type WatermarkGap = [number, number];
 | showToday | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | 透传内层组件；默认值见对应组件 |
 | showConfirmBtn | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | 透传内层组件；默认值见对应组件 |
 | showTime | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | 透传内层组件；默认值见对应组件 |
-| timePickerProps | 见场景用法与类型 | undefined &#124; { [x: string]: any; } | 否 | 透传内层组件；默认值见对应组件 |
-| disabledTime | 见场景用法与类型 | undefined &#124; (current?: Date, type?: DatePickerRange) => Record<string, any> &#124; undefined | 否 | 透传内层组件；默认值见对应组件 |
+| timePickerProps | 见场景用法与类型 | undefined &#124; DatePickerTimePickerProps | 否 | 透传内层组件；默认值见对应组件 |
+| disabledTime | 见场景用法与类型 | undefined &#124; (current?: Date, type?: DatePickerRange) => DatePickerDisabledTimeProps &#124; undefined | 否 | 透传内层组件；默认值见对应组件 |
 | showLunar | 见场景用法与类型 | undefined &#124; false &#124; true &#124; { showLunarDate?: boolean; showLunarFestival?: boolean; showSolarTerm?: boolean; showSolarFestival?: boolean; fallbackText?: string; } | 否 | 透传内层组件；默认值见对应组件 |
 
 ### Events
@@ -36568,9 +36666,12 @@ type WatermarkGap = [number, number];
 
 公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
 
-### 实例方法
+### 实例方法 / 暴露值
 
-没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+| 名称 | 公开类型 |
+| --- | --- |
+| focus | (() => void) & (() => void) |
+| blur | (() => void) & (() => void) |
 
 ### 关联类型定义
 
@@ -36725,8 +36826,8 @@ interface DatePickerProps {
 | showToday | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | 透传内层组件；默认值见对应组件 |
 | showConfirmBtn | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | 透传内层组件；默认值见对应组件 |
 | showTime | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | 透传内层组件；默认值见对应组件 |
-| timePickerProps | 见场景用法与类型 | undefined &#124; { [x: string]: any; } | 否 | 透传内层组件；默认值见对应组件 |
-| disabledTime | 见场景用法与类型 | undefined &#124; (current?: Date, type?: DatePickerRange) => Record<string, any> &#124; undefined | 否 | 透传内层组件；默认值见对应组件 |
+| timePickerProps | 见场景用法与类型 | undefined &#124; DatePickerTimePickerProps | 否 | 透传内层组件；默认值见对应组件 |
+| disabledTime | 见场景用法与类型 | undefined &#124; (current?: Date, type?: DatePickerRange) => DatePickerDisabledTimeProps &#124; undefined | 否 | 透传内层组件；默认值见对应组件 |
 | showLunar | 见场景用法与类型 | undefined &#124; false &#124; true &#124; { showLunarDate?: boolean; showLunarFestival?: boolean; showSolarTerm?: boolean; showSolarFestival?: boolean; fallbackText?: string; } | 否 | 透传内层组件；默认值见对应组件 |
 
 ### Events
@@ -36751,9 +36852,12 @@ interface DatePickerProps {
 
 公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
 
-### 实例方法
+### 实例方法 / 暴露值
 
-没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+| 名称 | 公开类型 |
+| --- | --- |
+| focus | (() => void) & (() => void) |
+| blur | (() => void) & (() => void) |
 
 ### 关联类型定义
 

package/CHANGELOG.md

@@ -4,6 +4,22 @@
 
 ## [Unreleased]
 
+## [1.18.1] - 2026-10-15
+
+### 修复
+
+- DatePicker 农历数字、选中圆圈和范围色带共用固定日期区，修复垂直错位、选中日期悬停变白、禁用文字及今天标记；提高农历文字清晰度，保留普通日期布局。
+- 修复日期时间手输丢失时分秒、非法日期自动进位、禁用日期或时间可被手输绕过，以及范围键盘切换写错端点、连续编辑丢失草稿的问题。
+- 日期范围单端禁用时保留锁定端，周选择统一解析、网格和提交的周起始日；日期别名补齐 `focus()` / `blur()` 的运行时转发及公开类型，面板标题移除误导性的无效点击行为。
+- Button 收敛 large / huge 横向内边距，large 字号调整为 15px，huge 使用 24px 行高，改善五档尺寸层次与文字对齐。
+- Dialog 使用 18px 关闭图标和 24px 点击区域，与标题中心对齐；声明式默认顶部距离改为 `100px`，命令式居中默认值保持原状，同步 MessageBox 关闭按钮定位。
+- Dropdown 支持 Tab / Shift+Tab 退出根菜单；Popover 支持 Escape 关闭及归还焦点，保留组合输入行为；修正共享 RenderFunction 回调的子节点类型。
+
+### 文档与验证
+
+- 补充农历空辅助行、禁用、手输日期时间、单端锁定及周一起始的 live demo，同步独立 AI 手册和完整 API。
+- 增加 DatePicker 浏览器回归脚本；本批修改已通过全量 134 文件 / 2770 用例、35 组日期浏览器检查及完整源码和文档构建。发布按用户要求复用已有验证，不重复执行质量门禁或等待 npm 公共索引刷新。
+
 ## [1.18.0] - 2026-10-14
 
 ### 调整

package/dist/_container/render-function.d.ts

@@ -1,5 +1,5 @@
-import { PropType, VNodeTypes } from 'vue';
-export type RenderFunc = (props: Record<string, unknown>) => VNodeTypes;
+import { PropType, VNodeChild } from 'vue';
+export type RenderFunc = (props: Record<string, unknown>) => VNodeChild;
 declare const _default: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
     renderFunc: {
         type: PropType<RenderFunc>;

package/dist/components/_components/picker/input-range.vue.d.ts

@@ -72,7 +72,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
     displayValue1: import('vue').ComputedRef<string | undefined>;
     changeFocusedInput: (index: number) => void;
     onChange: (e: Event) => void;
-    onFocus: (e: Event) => void;
+    onFocus: (e: Event, index: number) => void;
     onBlur: (e: Event) => void;
     onPressEnter: () => void;
     onClear: (e: Event) => void;

package/dist/components/date-picker/DatePanel.vue.d.ts

@@ -56,6 +56,10 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         type: BooleanConstructor;
         default: boolean;
     };
+    confirmDisabled: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
 }>, {
     t: (key: import('../..').LocaleKey | (string & {}), params?: Record<string, string | number>) => string;
     className: {
@@ -72,9 +76,9 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
     handleCellKeydown: (event: KeyboardEvent, cell: DatePickerCell) => void;
     headerLabel: import('vue').ComputedRef<string>;
     todayLabel: import('vue').ComputedRef<string>;
+    todayDisabled: import('vue').ComputedRef<boolean>;
     weekdayLabels: import('vue').ComputedRef<string[]>;
     movePanel: (step: number, superMove?: boolean) => void;
-    zoomHeader: () => void;
     handleSelect: (cell: DatePickerCell) => void;
     handleCellMouseEnter: (cell: DatePickerCell) => void;
     handleCellMouseLeave: () => void;
@@ -141,6 +145,10 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         type: BooleanConstructor;
         default: boolean;
     };
+    confirmDisabled: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
 }>> & Readonly<{
     onSelect?: ((_value: Dayjs) => any) | undefined;
     onCancel?: (() => any) | undefined;
@@ -161,6 +169,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
     shortcuts: DatePickerShortcut[];
     showToday: boolean;
     showConfirmBtn: boolean;
+    confirmDisabled: boolean;
 }, {}, {
     IconLeft: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
         fillColor: {

package/dist/components/date-picker/DatePicker.vue.d.ts

@@ -1,6 +1,6 @@
 import { Dayjs } from 'dayjs';
 import { PropType } from 'vue';
-import { DatePickerDisabledDate, DatePickerMode, DatePickerModelValue, DatePickerPosition, DatePickerRange, DatePickerShortcut, DatePickerType, DatePickerValueFormat } from './interface';
+import { DatePickerDisabledDate, DatePickerDisabledTime, DatePickerDisabledTimeProps, DatePickerMode, DatePickerModelValue, DatePickerPosition, DatePickerRange, DatePickerShortcut, DatePickerType, DatePickerTimePickerProps, DatePickerValueFormat } from './interface';
 import { DatePickerLunar } from './lunar';
 declare const _default: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
     type: {
@@ -106,10 +106,10 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         default: boolean;
     };
     timePickerProps: {
-        type: PropType<Record<string, any>>;
+        type: PropType<DatePickerTimePickerProps>;
     };
     disabledTime: {
-        type: PropType<(current?: Date, type?: DatePickerRange) => Record<string, any> | undefined>;
+        type: PropType<DatePickerDisabledTime>;
     };
     showLunar: {
         type: PropType<DatePickerLunar>;
@@ -130,14 +130,17 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
     mode: import('vue').ComputedRef<DatePickerMode>;
     isDateTime: import('vue').ComputedRef<boolean>;
     needConfirm: import('vue').ComputedRef<boolean>;
-    timeFormat: import('vue').ComputedRef<any>;
-    timePickerProps: import('vue').ComputedRef<Record<string, any>>;
+    canConfirm: import('vue').ComputedRef<boolean>;
+    todayDisabled: import('vue').ComputedRef<boolean>;
+    timeFormat: import('vue').ComputedRef<string>;
+    timePickerProps: import('vue').ComputedRef<DatePickerTimePickerProps>;
     focused: import('vue').Ref<boolean, boolean>;
     focusedIndex: import('vue').Ref<number, number>;
     mergedSize: import('vue').ComputedRef<"mini" | "small" | "medium" | "large">;
     mergedError: import('vue').ComputedRef<boolean>;
     allDisabled: import('vue').ComputedRef<boolean>;
     rangeDisabled: import('vue').ComputedRef<boolean[]>;
+    hasDisabledRange: import('vue').ComputedRef<boolean>;
     mergedInputReadonly: import('vue').ComputedRef<boolean>;
     mergedPopupVisible: import('vue').ComputedRef<boolean>;
     computedFormat: import('vue').ComputedRef<string>;
@@ -243,7 +246,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
     rangePanelMode: import('vue').Ref<"time" | "date", "time" | "date">;
     viewDate: import('vue').Ref<Dayjs | undefined, Dayjs | undefined>;
     mergedDisabledDate: import('vue').ComputedRef<DatePickerDisabledDate | undefined>;
-    getDisabledTimeProps: (value?: Dayjs, range?: DatePickerRange) => Record<string, any>;
+    getDisabledTimeProps: (value?: Dayjs, range?: DatePickerRange) => DatePickerDisabledTimeProps;
     formatTimeDate: (value?: Dayjs) => string;
     formatTimeValue: (value?: Dayjs) => string;
     handlePanelSelect: (value: Dayjs) => void;
@@ -392,10 +395,10 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         default: boolean;
     };
     timePickerProps: {
-        type: PropType<Record<string, any>>;
+        type: PropType<DatePickerTimePickerProps>;
     };
     disabledTime: {
-        type: PropType<(current?: Date, type?: DatePickerRange) => Record<string, any> | undefined>;
+        type: PropType<DatePickerDisabledTime>;
     };
     showLunar: {
         type: PropType<DatePickerLunar>;
@@ -1677,7 +1680,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         displayValue1: import('vue').ComputedRef<string | undefined>;
         changeFocusedInput: (index: number) => void;
         onChange: (e: Event) => void;
-        onFocus: (e: Event) => void;
+        onFocus: (e: Event, index: number) => void;
         onBlur: (e: Event) => void;
         onPressEnter: () => void;
         onClear: (e: Event) => void;
@@ -2292,6 +2295,10 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             type: BooleanConstructor;
             default: boolean;
         };
+        confirmDisabled: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
     }>, {
         t: (key: import('../..').LocaleKey | (string & {}), params?: Record<string, string | number>) => string;
         className: {
@@ -2308,9 +2315,9 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         handleCellKeydown: (event: KeyboardEvent, cell: import('./interface').DatePickerCell) => void;
         headerLabel: import('vue').ComputedRef<string>;
         todayLabel: import('vue').ComputedRef<string>;
+        todayDisabled: import('vue').ComputedRef<boolean>;
         weekdayLabels: import('vue').ComputedRef<string[]>;
         movePanel: (step: number, superMove?: boolean) => void;
-        zoomHeader: () => void;
         handleSelect: (cell: import('./interface').DatePickerCell) => void;
         handleCellMouseEnter: (cell: import('./interface').DatePickerCell) => void;
         handleCellMouseLeave: () => void;
@@ -2377,6 +2384,10 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             type: BooleanConstructor;
             default: boolean;
         };
+        confirmDisabled: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
     }>> & Readonly<{
         onSelect?: ((_value: Dayjs) => any) | undefined;
         onCancel?: (() => any) | undefined;
@@ -2397,6 +2408,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         shortcuts: DatePickerShortcut[];
         showToday: boolean;
         showConfirmBtn: boolean;
+        confirmDisabled: boolean;
     }, {}, {
         IconLeft: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
             fillColor: {