来源：https://ui.docs.xihanfun.com/changelog # 更新日志 · XiHan.UI 本文件记录 XiHan.UI 各版本的变更。每条标注 **新增 / 修复 / 优化 / 调整 / 移除** 类别。只收录使用者可感知的变更，仓库自身的配置、CI、测试与门禁不列入。组件以 npm 包形式发布，升级前请留意「调整」类中的破坏性变更。 ## v2.1.0 (2026-09-24) 本版补齐集合类组件的条目契约：逐条语气、说明、快捷键与首尾两格的逐条钩子，菜单的 `collection` 可以直接铺出分组；选中标记统一为行尾对号。本版包含少量破坏性变更（Tree、Listbox、TagGroup 的选中外观与相关部件、槽名），按次版本发布，升级前请看下方升级须知。 ::: warning 升级须知 **Tree** - `expandOnClick` 缺省由 `true` 改为 `false`，与 TreeSelect 一致：点行与确认键只选中，展开交给展开箭头（`branch-trigger`）与左右方向键。需要「点目录即展开」的，显式打开 `expandOnClick`（Web Components 写 `expand-on-click`）；分支行只放了不可点的 `branch-indicator` 的树，缺省下只能用方向键展开，请在分支行补一枚 `branch-trigger` - 勾选框部件删除：`item-checkbox` / `branch-checkbox`，三端的 `XhTreeItemCheckbox` / `XhTreeBranchCheckbox`（React 另有 `XhTreeItemCheckboxProps` / `XhTreeBranchCheckboxProps`），以及 connect 上的 `getItemCheckboxProps` / `getBranchCheckboxProps`。单选、多选与级联都改为在行尾画对号：把勾选框换成 `XhTreeItemIndicator`，分支行同样放一枚；Web Components 把 `data-xh-part="item-checkbox"` / `"branch-checkbox"` 换成 `data-xh-part="item-indicator"` - 删除组件槽 `--xh-tree-checkbox-*`（8 个）与 `--xh-tree-row-bg-selected`；行的 `data-xh-collection-context` 由 `page` 改为 `overlay` **Listbox** - 选中行不再铺品牌淡底、不换字色，只在行尾亮对号；删除组件槽 `--xh-listbox-item-bg-selected`，`--xh-listbox-item-fg-selected` 保留但缺省回到条目自己的字色；条目的 `data-xh-collection-context` 由 `page` 改为 `overlay` **TagGroup** - 选中的标签不再换面、换字色与描边，只在文字后亮一枚对号；删除组件槽 `--xh-tag-group-item-bg-selected`、`--xh-tag-group-item-bg-selected-hover`、`--xh-tag-group-item-bg-selected-pressed`、`--xh-tag-group-item-fg-selected`、`--xh-tag-group-item-border-selected`；实心标签选中时不再描出字色描边 **Menu** - 由 `collection` 代铺的条目，文字从 `item` 里的裸文本改放进 `item-text`（与 ContextMenu、Menubar 一致）。直接对条目文本节点写样式的自定义皮肤，请改为选中 `item-text` ::: - **新增** 集合条目逐条语气：条目数据写 `tone`（`MenuNode` 与另外十二个集合组件的节点）即按该语气族着色，静息只换字色，悬停、键盘高亮与按下换语气淡底；选中与当前压过语气，禁用压过一切，强制颜色模式下退回系统色 - **新增** 条目说明与快捷键：`MenuNode` 补上 `indicator` / `description` / `shortcut`，Menu 新增 `item-shortcut` 部件；ContextMenu、Menubar 补上 `item-shortcut` 与 `shortcut`；另外九个集合组件补上 `item-description` 与 `description`；Command 补上快捷键提示。快捷键以次级字号显示且不换行，不进入读屏可及名与连打检索 - **新增** 首尾两格的逐条钩子：Menu、ContextMenu、Menubar 新增 `item-suffix` 部件与 `item-prefix` / `item-suffix` 插槽（React 为 `renderItemPrefix` / `renderItemSuffix`），给条目加图标或徽标不必再用 `item` 插槽整条重写；Listbox、Select、Combobox、Mention、Command 补上 `item-prefix` / `item-suffix`；Tree、TreeSelect、Cascader、Transfer 补上行尾一格 - **新增** `MenuNode` 的 `group` 与 `groupLabel`：`collection` 按相邻同值收成分组并输出分组标题 - **新增** 组件文档补充「React 适配器 props」表与条目数据表，插槽表写明 `item` / `item-prefix` / `item-suffix` 的分工 - **修复** 浮层打开后不再常驻 `will-change`：此前入场动画中途的栅格会被沿用，动画结束后文字与 1px 分隔线仍然发虚；浮层文字也与页面其余文字一样使用亚像素抗锯齿 - **修复** Vue 的 `XhKbd` 在平台探测之后不再丢失全局配置 - **优化** 三端状态机读取 props 不再按 prop 个数重复展开：Vue 200 个按钮的挂载由 29.5ms 降至 16.0ms，Web Components 100 个分页的挂载约由 112ms 降至 24ms - **优化** Portal 视觉桥不再按「浮层数 × 自定义属性数」重读计算样式；焦点域的 Tab 判定不再按「候选数 × 容器层数」查询计算样式 - **调整** 选中标记统一为行尾对号：Collection Item 家族 page 语境的对号从行首移到行尾，与浮层内的列表同列；Listbox、Tree、TagGroup 的选中外观随之统一（见升级须知） ## v2.0.0 (2026-09-22) 本版为主版本升级。主要变化：`@xihan-ui/kernel`、`@xihan-ui/machine`、`@xihan-ui/behavior` 合并为 `@xihan-ui/core`；新增 React 19 适配器 `@xihan-ui/react`；组件由 121 个增至 134 个（新增 20 个，删除 3 个，合并 4 个，更名 5 个）。所有更名与删除均不保留别名、转发或兼容层，引用旧名会直接报错。 ::: warning 升级须知 以下按包、组件、部件与属性、行为四类列出破坏性变更的范围与去向。完整对照表（旧名 → 新名，逐部件、逐槽名）见各包随 npm 发布的 `CHANGELOG.md`。 **包与依赖** - `@xihan-ui/kernel`、`@xihan-ui/machine`、`@xihan-ui/behavior` 合并为 `@xihan-ui/core`，旧包不再发布，无转发包。导出名称不变，子入口按原名平移：`kernel/metadata` → `core/metadata`、`kernel/skin-check` → `core/skin-check`、`kernel/vite` → `core/vite`、`machine/vanilla` → `core/vanilla`、`behavior/presence` → `core/presence`。诊断 `core.version-mismatch` 的 `detail.kernelVersion` 更名为 `coreVersion`。仅安装适配器的项目无需改动 - `@xihan-ui/code-highlight` 由适配器的直接依赖改为可选 peer 依赖，使用代码着色的项目需自行安装；包由 `engine` 组移至 `features` 组，包名不变 - 新增 `@xihan-ui/react`。公开包由 18 个变为 17 个 **组件的增删与更名** - 删除 `thread`、`composer`、`code-block`，分别由 `message-feed`（配合 `log`）、`prompt-input`、`code-view` 替代 - `result` 并入 `empty-state`（`live` 默认为 `polite`，默认尺寸档比原来小一号；保持原样需写 `live="off"` 与 `size="lg"`）；`space` 并入 `flex`（`XhSpace` 未写 `gap` 时默认有间距，`XhFlex` 默认为 0，迁移时需显式写 `gap="md"`）；`countdown` 并入 `timer`；`popselect` 退役，随表单提交的场景改用 `select`，仅切换视图参数的场景改用 `popover` 组合 `listbox` - 更名：`ellipsis` → `truncate`、`dynamic-input` → `field-array`、`time` → `timestamp`、`qr-code` → `matrix-code`（新增 `format` 选择码制）、`calendar` → `calendar-picker`（区间选择拆为新组件 `calendar-range-picker`；`date-picker` 只保留单选与多选，区间改用新组件 `date-range-picker`） - `color-picker` 重组为组合组件：色相与透明度滑块为内嵌的 `color-slider`，预设色板为内嵌的 `color-swatch-picker`；非法或越界的文本输入不再静默复原，改为保留状态并抛出错误 - `select`、`tags-input`、`tag-group` 的标签统一改用 `tag` 组件渲染：`item-delete-trigger`、`item-preview`、`item-text` 不再是这三个组件的部件，对应节点为 `tag` 的 `root` / `label` / `close-trigger`；`select` 多选未指定 `maxTagCount` 时最多显示 3 枚标签，其余折叠为 `+N` **部件、属性与槽名** - 32 个部件更名、1 个部件并入他处；10 处同一角色在不同组件中命名不一致的部件统一命名 - 14 组 prop 更名、2 组事件更名。例如 `resizable` / `floating-panel` 的像素尺寸 `size` 更名为 `dimensions`；`password-input` 的 `visible` / `defaultVisible` / `onVisibilityChange` 更名为 `revealed` / `defaultRevealed` / `onRevealedChange`；`virtualizer` 的 `onChange` 更名为 `onRangeChange` - 13 个 `data-*` 属性名删除，每组只保留一个（如 `data-affixed` → `data-fixed`；`data-borderless` → `data-bordered`，取值反转）；`data-type` 拆分为 `data-value-type`、`data-severity`、`data-select-mode`、`data-reveal-mode`、`data-format`；`data-phase` 与六个组件的生命周期 `data-status` 并入 `data-state`；`table` 的 `expanded-row`、`tree` 的 `branch-content`、`heatmap` 的 `tooltip` 收起态由 `hidden` 属性改为 `data-state`。CSS 选择器不会因属性名失配而报错，请在代码库中检索旧属性名 - `dialog` / `drawer` 新增 `header` / `body` / `footer` 三个部件，`body` 为面板内唯一的滚动区域；文本输入的两套控件盒槽名合并为一套，被替代的槽名删除 - 形态轴收敛：字段类组件未传 `variant` 时显式输出 `data-variant="outline"`，自定义皮肤若以「无 `data-variant`」判定默认态，需改为匹配 `outline`；`button` / `float-button` 移除 `shape`；`loading-bar` 移除 `color`；`card` 收敛为 `default` / `secondary` / `tertiary` / `transparent` 四种表面，移除 `size` / `hoverable` / `split` 属性与 `media` / `body` 部件 - 轻提示与通知的 `type` 更名为 `tone`，取值收敛为 `info | success | warning | danger`，加载态独立为布尔 `loading`；通知队列 `max` 默认值由不限改为 5；`toast` / `alert` 的 `content` 改为必需；`empty-state` 的 `status` 只接受 `'404' | '403' | '500'`，语义改由 `tone` 表达；`steps` 的 `StepStatus` 收敛为 `completed | current | incomplete`，出错与警示改由逐步 `tones` 表达 - 读屏文案只接受函数，不再接受字符串；`flex` 的 `direction` 别名与 `FlexDirection` 类型删除，只保留 `orientation`；`listbox` 的 `multiple` 删除，只保留 `selectionMode`；`kbd` 的单键与组合键统一为 `keys` 数组，默认仅展示，显式 `register` 后才注册监听；`grid` 的 `cols` / `span` / `offset` 增加运行时取值范围校验 **行为** - 部件上同名事件处理器的执行顺序统一为「使用者的处理器先执行，部件的处理器后执行」；此前是否使用 `asChild` 会导致顺序相反。依赖部件先更新状态再读取的代码需改为微任务或变更回调 - `pin-input` 改为按顺序录入，焦点落在第一个空格；`mention` 的输入框改为单行；`number-field` 的 `control` 部件改为必需 - `combobox`、`tree-select`、`cascader`、`transfer` 的原生表单提交改为每个选中值一个同名隐藏字段，不再以逗号拼接；`cascader` 的 `value` 对非数组、混合类型、空路径一律拒绝 - `FieldControl` 与 `asChild` 的组合宿主改为严格检查：Fragment 内唯一控件正常接线，零个或多个节点、非空文本混排时抛出错误，不再降级生成默认按钮 - `@xihan-ui/motion` 删除 `TweenEasing`、`tweenEasings`、`resolveTweenEasing`，统一使用 `EasingName`、`easing`、`resolveEasing` - 三端 `XhConfig.motion` 的隐式全局覆盖移除，视觉环境统一由 `createVisualEnvironmentController` 管理；表单字段标识统一为 `FormPath`，`XhFormFieldGroup` 的 `value` 更名为 `name` ::: - **新增** `@xihan-ui/react`：React 19 适配器，覆盖全部 134 个组件。组件名与 Vue 侧一致（`Xh*`），受控 / 非受控与变更载荷为同一份合同，带载荷的插槽以函数式 children 提供，无需安装 provider - **新增** 20 个组件。数据录入：`calendar-range-picker`、`date-range-picker`、`time-range-picker`、`color-field`、`color-slider`、`color-swatch-picker`、`input-group`、`tag-group`；数据展示：`bar-code`（一维码，七种码制）、`color-swatch`；浮层：`command`（命令面板）；AI 对话：`approval`（危险动作执行前的人工确认）、`code-view`、`diff-view`（单栏与并排）、`markdown-stream`、`message-feed`、`prompt-input`、`question-flow`（执行前的澄清问卷）、`reasoning`、`tool-call` - **新增** 七轴视觉环境 `createVisualEnvironmentController`：色彩模式、品牌、密度、书写方向、对比度、动效、透明材质统一解析、继承、持久化并投影到根元素，局部作用域只影响自身子树；Portal 按实例桥接来源处的局部视觉环境 - **新增** 按压通道：Space / Enter 与触屏按住时输出 `data-pressed`，与指针 `:active` 共用同一套按压样式，覆盖全库可按下的部件 - **新增** 浮层退场生命周期由 Presence 租约管理：逻辑关闭后 `content` 立即设为 `inert` 并退出可访问树，Layer、消解层与焦点域在退场动画结束后释放；`dialog` / `drawer` 新增 `onExitComplete` - **新增** 集合类组件补齐三种非条目状态：`empty`、`loading`、`load-more-trigger`；`tree-select` 新增懒加载分支合同（`hasChildren`、`loadChildren({ node, signal })`）及 loading / error / retry / loaded-empty 状态结构 - **新增** `tabs` 标签溢出时不再折行，改为沿主轴滚动：新增 `prev-trigger` / `next-trigger`，支持滚轮、焦点跟随与触屏拖动；segment 档的指示条改为滑动式 - **新增** `layout` 的 `siderPresentation`（`inline` / `sheet`），`sheet` 档下侧栏以覆盖方式展开 - **新增** `dialog` / `drawer` / `image-viewer` 的遮罩形态轴 `variant`；`scroll-area` 的边缘渐隐与到头状态；`scrollbar` 的 `anchor` - **新增** 浮层类与选择类组件的 Portal 部件支持实例级 `container` - **新增** 命令式对话框服务的 `actionError` / `onActionError({ cause })` 与可本地化的 `actionErrorText`；`popconfirm` 的 `onConfirm` 支持返回 `PromiseLike`；`form` 新增 `validationError` 状态与校验异常事件，字段状态轴接入 `text-field` 控件 - **新增** Web Components 侧补齐四个命令式反馈服务；轻提示与通知的队列合并为一套 - **新增** `@xihan-ui/tokens` 十二色相基础色板；`matrix-code` 新增 `data-matrix`、`gs1`、`pdf417`、`aztec` 码制；`tag` 新增 `ghost` 形态与 `readOnly`；`form` 的 `layout` 新增 `grid` 档 - **新增** `cascader`、`transfer` 支持 `name` / `form` 原生表单提交，含禁用排除与原生重置 - **新增** `RenderedBlock.source`：代码块与公式块在已消毒的 `html` 之外提供未转义的原文 - **修复** 四个浮层以指针打开后关闭时，焦点未按键盘规格返回触发器 - **修复** 皮肤自绘的状态字形（勾选、半选、分支箭头）统一按指示符档取尺，compact 密度下与标记盒尺寸不一致的问题：select、combobox、listbox、cascader、menubar、context-menu、steps、file-upload 等 - **修复** 几何类过渡按角色选择曲线档；集合条目的描边色不再参与过渡，切换标签页时不再闪烁 - **修复** 补齐 11 处缺失的读屏文案；补齐两个适配器未暴露的 headless 能力（七个浮层的 `dir`、五个元素的 `translations`、分页省略位浮层的四项） - **修复** Vue `date-picker` 挂载在 iframe 或其他 Document 时的运行时归属；`trackHoverIntent` 固定使用触发器所属的 Document - **修复** `pin-input` 受控模式下输入一位跳过一格；`tags-input` 就地编辑框宽度随内容变化，不再按原生 input 的 20 字符宽度展开；`carousel` 在减弱动效档下不再自动播放 - **修复** 粗指针热区平移在 RTL 下行内方向反向，热区中心偏离宿主 - **调整** 带边框的控件盒统一为浅边框不填底，与浮层面板、卡片使用同一条边线；字段类组件未传尺寸时统一宽度为 16rem - **调整** 侧栏导航当前项去掉起始侧 2px 竖线，只保留品牌淡底与字色；标签页 line / card 档的标签宽度随文字；导航菜单与锚点目录中指向当前页的链接绘制静态指示线 - **调整** `toggle-group` 默认外观改为浅色胶囊分段控件，选中项使用品牌淡底；`kbd` 收敛为固定 24px 键帽，新增 `default` / `light` 两种外观；徽标 sm 档收为 14px - **调整** 菜单类组件接入集合条目配方：条目按压面由 300 改为 200，展开中的触发器改为中性面，浮层滚动条走 4px 档并增加 overscroll 隔离 ## v1.1.0 (2026-08-31) - **新增** `sortable` 组件：列表 / 网格拖拽排序，拖动中其余条目实时让位，`sort` 事件直接给出重排好的 `ids`，键盘路径默认开着 - **新增** `resizable` 组件：八条边都能推的可调容器，带上下限、宽高比与吸附步进，指针与键盘两条路都通 - **新增** `@xihan-ui/pointer`：指针会话、多指会话与双指几何、拖放几何、尺寸调整几何四层，自研零依赖 - **新增** `table` 的列拖拽排序：新增部件 `column-drag-trigger` 与 `live-region`，把手自占一个 Tab 位，落点按列 id 认 - **新增** `table` 的行拖拽排序：`rowReorderable` 打开后整行可拖，树形行支持换父，搬完发 `onRowMove` - **新增** `table` 的列宽拖拽：标了 `resizable` 的列产出改宽把手，宽度落进列偏好可存可还原 - **新增** `tree` 的节点拖拽搬家：落点三档（前 / 后 / 落进去），`Alt` + 方向键改同层次序与缩进，搬完发 `onNodeMove` - **新增** `tabs` 的标签拖拽换位：`reorderable` 打开后整个标签可拖，`Alt` + 主轴方向键可挪，搬完发 `onTabMove` - **新增** 三个触屏拖动把手 `row-drag-trigger` / `node-drag-trigger` / `tab-drag-trigger`，不占 Tab 位 - **新增** 选中原语 `applySelection` / `toggleSelectAll` / `rangeBetween`；`table` / `tree` / `transfer` 接上 Shift 范围选，`table` 另加 `Ctrl` / `Cmd` + A 全选 - **新增** `image-viewer` 的双指缩放 - **新增** `@xihan-ui/kernel/vite` 子入口：开发服务器启动时在终端打一次横幅 - **调整** 浏览器控制台的启动摘要默认不打，要打显式 `setMetadataAutoPrint(true)` - **调整** `XIHAN_UI_LOGO` 与 `XIHAN_UI_SEND_WORD` 从 `XIHAN_UI_METADATA` 摘出来单独导出，`getMetadataSummary()` / `getMetadataDetails()` 不再带寄语 - **调整** `tree` 的拖拽播报报出落脚处，新增 `movedInto` / `droppedInto` / `canceledInto` / `rootLevel` 四个文案键 - **调整** `tree` 对禁用节点只拦 `inside` 落点，在它前后插不再拦 - **调整** `carousel` 的划动与 `image-viewer` 的平移改走多指会话，不再逐个捕获指针 - **修复** `dialog` / `drawer` / `image-viewer` 的 `closeOnEscape` 与 `closeOnInteractOutside` 改为交互当时现读——浮层开着时改这两个开关此前不算数 - **修复** 按住切换类的按键会来回翻转（按住 `Ctrl` / `Cmd` + A 在全选与全不选之间闪、按住空格反复拾起放下），12 处补上自动重复守卫 - **修复** 八个 Vue 组件收不到全局配置里的读屏文案：`combobox` / `popselect` / `resizable` / `sortable` / `table` / `tabs` / `text-field` / `tree` - **修复** `XhTableRoot` 丢掉作者写在它上面的 `class` / `aria-*` / 监听器 - **修复** `table` 与 `tree` 的键盘处理器吞掉落在可编辑单元格 / 节点内容里的按键 - **修复** 开着 `striped` 的表里，偶数行既不响应悬停也显不出选中 ## v1.0.0 (2026-08-26) ::: warning 版本与兼容性 首个正式版。从这一版起，[版本与兼容性政策](/guide/versioning)的全部条款生效。 ::: - **新增** 框架无关的无头内核：状态、交互与无障碍逻辑住在 `@xihan-ui/headless`，适配器只把 `connect()` 产出挂到宿主元素上；同一份内核在两端行为一致 - **新增** 119 个组件，每个同时产出无头内核、Vue 组件、自定义元素与默认皮肤——通用 15、布局 8、导航 16、数据录入 32、数据展示 30、反馈 9、浮层 7、AI 对话 2，逐个见[组件总览](./components/) - **新增** `@xihan-ui/vue` Vue 3 适配器，729 个部件：受控 / 非受控、`v-model`、带类型的作用域插槽；`behavior` 子入口出五个行为原语的组合式，另有四件命令式服务（轻提示、通知、对话框、顶部进度条） - **新增** `@xihan-ui/web-components` 适配器，121 个自定义元素：元素不生成结构，作者写带 `data-xh-part` 的 Light DOM 子节点；随包出 `custom-elements.json` - **新增** 引擎四包：`@xihan-ui/kernel` 结构原语、`@xihan-ui/machine` 状态机运行时、`@xihan-ui/behavior` 行为原语、`@xihan-ui/motion` 动效原语 - **新增** `@xihan-ui/position` 浮层定位：放置、翻转、贴边、箭头锚点、rtl，自研无第三方依赖 - **新增** 样式与逻辑解耦：皮肤只认 `data-scope` / `data-part` / `data-*`，不认框架也不认类名，整包换皮肤不用碰一行 JS - **新增** `@xihan-ui/tokens` 设计令牌：DTCG 源在构建期产出 CSS 变量（原语 95、语义 158，另有紧凑 49、浅色 41、深色 44、减弱动效 8 条覆盖），运行时不做 CSS-in-JS - **新增** `@xihan-ui/styles` 默认皮肤 125 份，按 `@layer` 分层（`xihan.reset` → `tokens` → `base` → `components` → `overrides`），使用者的覆盖恒排在最后 - **新增** 三条视觉轴：`variant` 管形态、`tone` 管语气（六族）、`size` 管尺寸；实心底上的前景与交互态由语气色按 WCAG 相对亮度现推 - **新增** 主题五个维度独立切换：明暗、品牌、密度、对比度、书写方向，带 `createThemeController` 与品牌色派生 - **新增** 浮层一律 Teleport 到单一落点 `#xh-portal-root`，层号不受宿主祖先影响；13 个滚动宿主自带自绘滚动条 - **新增** 兜底字形二十个 `--xh-glyph-mark-*` 令牌，构建期内联图标包 SVG，跨系统长相一致 - **新增** `@xihan-ui/icons` 首方图标集：`IconRecord` 结构化记录，运行期不解析 SVG 字符串，另有 SVG → `IconRecord` 的构建期转换器 - **新增** `@xihan-ui/animations` 可序列化动效配方、`@xihan-ui/sound` 程序化 UI 音效（三套主题，零音频文件）、`@xihan-ui/backgrounds` WebGL2 效果与粒子云 - **新增** `@xihan-ui/chat-stream` AI 协议内核：SSE 读取 → 协议归一 → parts 归约 → 会话 store，零 DOM 零框架 - **新增** `@xihan-ui/markdown` 流式 Markdown 渲染内核（CommonMark 子集一致率 489/652）与 `@xihan-ui/code-highlight` 自研词法着色 - **新增** 键盘交互依 W3C APG 落地，77 份机读键盘规格表共 463 行键位随包提供 - **新增** 焦点环、按下反馈、禁用态对比度与语气配色（2 档主题 × 6 族，158 组配对）逐条达标，无障碍扫描跑在真实 Chromium（axe） - **新增** 119 个组件都留了文案位并挂进覆盖表，全局 `ConfigProvider` 一处注入；rtl 下浮层放置、方向键语义与图形朝向一并对调 - **新增** 24 个表单字段组件认原生表单重置；`field` 提供标签、描述、错误与 `asChild` 逃生口 - **新增** 17 个公开包同版发布，运行时第三方依赖只有一个（`@internationalized/date`，仅日期族使用）；混装两个版本在 dev 下报 `core.version-mismatch` - **新增** 摇树是真的：只引一枚图标 149 B、整集合 7.37 kB，`XhButton` 1.38 kB、`XhDialogRoot` 15 kB（均 gzip） - **新增** ESM-only，子路径导出都带类型 - **调整** 元数据的宿主行只报宿主与版本，不再报版本一致性 ## v1.0.0-preview.0 (2026-08-26) 这一版的主线是**把 alpha 里遗留的形状问题一次改完**：两对做着同一件事的组件分家（toast / notification、badge / tag），三处与同族对不上的 prop 名归位，语气色从逐族写死改为按底色现推。 - **新增** `notification` 组件，与 `toast` 分家：前者是系统推来的卡片（左侧类型字形、右上角关闭钮、两列网格、九宫格落位），后者收窄成操作反馈（顶部居中、宽度包着内容、一行图标加一句话） - **新增** 分页的省略号能摊开：折进去的那几页有了入口，分页因此升级成浮层族（新增 `positioner` / `content`）；每页条数从只读 prop 升成真状态，配 `XhPaginationPageSizeSelect` 与 `pageSizeOptions` - **新增** 表格的前缀列（行号 / 勾选 / 展开，按给定顺序插在最前并占住列号）、树形子行，以及一份可序列化的列偏好（列序 / 隐藏列 / 列宽） - **新增** 树的 `multiple`、`leafOrientation`（末端全是叶子的那层横排）与节点级 `childrenOrientation` - **新增** json-viewer 的原文视图 `view="text"`：直接出缩进过的 JSON，可整段拷走，值不再受截断与折减 - **新增** 13 个宿主的滚动层自带自绘滚动条：12 个浮层族的 `content` 与 json-viewer 的两档，作者一个部件都不用写；滚动条同时新增 `scroll-hover` 档并定为缺省 - **新增** Vue 侧三条逃生口：`@xihan-ui/vue/behavior` 子入口（五个行为原语的组合式）、`useHotkeys`（只注册不渲染键帽）、`XhFieldControl` 的 `asChild` 与配套 `useFieldControl` - **新增** 命令式服务补齐三件：`createLoadingBarService`（句柄上是在途计数而不是布尔开关）、取值型 `prompt`、配置源可运行期换（应用切语言后服务子树跟着变） - **新增** `@xihan-ui/tokens` 导出颜色能力：相对亮度、对比度、择色、混色与深浅——这套数学此前在四处各写了一份，判据各走各的 - **新增** date-picker 的 `defaultFocusedValue`，决定展开时先落在哪一页 - **新增** thread 补 `provideThread` / `useThreadContext`，与孪生组件 log 对称 - **调整** **badge 收窄成「只做角标」**：删掉 `variant`，解剖从单层 `root` 拆成 `root`（锚点）+ `indicator`（角标），新增 `placement`，定位归组件自己管。**行内的状态药丸请改用 `tag`** - **调整** **生命周期相位改走 `data-state`**，`data-status` 退回「结果种类」一轴——此前一条 `[data-status='error']` 会同时命中「加载失败的头像」和「一整页 500 报错」 - **调整** 树的 `selectionMode` 转为 `multiple` 的旧写法，与同族七家对齐 - **调整** 实心底上的前景色与交互态挪动方向改由语气色现推（WCAG 相对亮度，白字黑字的交叉点 `0.179` 是解析解），换肤下配对自动成立；装饰档 `--xh-_tone-soft` 从 500 提到与控件边界同一档，六族十二组都够到 3:1 - **调整** 描边档的标签改用「可操作区边界」那一档语气色，边相对面的对比从 1.44–2.18 抬到 4.56–7.83（浅色） - **调整** 浮层里的条目之间加 2px 行距，新增语义令牌 `--xh-list-option-gap` 统一这把尺——此前库内自己就有 0 / 2 / 4px 三种方言 - **调整** select 的盒不再自带 320px 宽度上限，框宽交回布局 - **调整** 上一页 / 下一页默认就画两枚箭头，不再要每份示例手写「上一页 / 下一页」四个字 - **调整** 147 个注入键改用 `Symbol.for`：模块被加载成两份时不再整棵子树白屏 - **修复** 点字段的标题聚不到复合控件的焦点；套进字段的复合控件读屏**一个名字都没有**——标签的 `for` 指向 `div` 时什么也不会发生，而且不报错 - **修复** `useStickToBottom` 吞掉句柄，最常见的用法（两个 getter 读模板 ref）下根本没挂上 - **修复** `XhJsonViewerRoot` 的 `value` 在类型上被推成 `undefined`，任何跑 vue-tsc 的工程传真实数据都编译不过 - **修复** 命令式服务的宿主挂不起来时连累调用方：一条轻提示能让整次导航失败、整站白屏，现在退化成空操作并发一条说得清的诊断 - **修复** 日历的「大步翻」两颗钮被一条 `display: none` 无条件收掉，从来就没画出来过 - **修复** date-picker 展开态初值为真且铺了格子时抛 `SEND_BEFORE_MOUNT` - **修复** 条目之间一有缝，select / combobox / popselect 的高亮就一跨一闪，读屏跟着一路播报 - **修复** 四处被祖先 `overflow` 裁掉的聚焦环改成往内收 - **修复** 树上三个对读屏隐藏的把手不再被指针聚焦（浏览器告警「aria-hidden 的后代仍持有焦点」）；叶子行补上箭头那一格的缩进，层级关系读得出来了 - **修复** 菜单族两家（context-menu / menubar）的勾选标记没跟着语气走 - **优化** 不可关闭的标签走快路不建状态机：400 枚从 39.1ms 降到 18.3ms - **优化** 进度条服务的宿主自己渲染，不再经 provide/inject 拿 api - **移除** `toaster`：轻提示不再需要额外的容器组件 - **移除** `@xihan-ui/kernel` 的 `DATA_SCROLL_SHARD`：配套的分片机制从未实现，声明处之外全库零引用 ## v1.0.0-alpha.3 (2026-08-23) 这一版的主线是**一致性收口**：把「同一件事在不同组件里有几种做法」逐条查出来、裁一种、再钉住。 - **新增** `scrollbar` 组件：自绘滚动条可以挂在任意一个滚动容器上，不必是本组件的后代 - **新增** `date-picker` / `time-picker` 的快捷选项（`presets`）：给数据就在浮层里多排一列，自成一套 listbox 键盘 - **新增** 日历的多面板、按月 / 季度 / 年 / 周挑、快速翻年、周选整周预览；周序号成为一等部件 `week-number` - **新增** select 浮层的底部操作区，「新建」「全选」这类按钮有了位置 - **新增** 热力图的 `palette` 色板轴（六色），与语气轴各管各的 - **新增** number-field 的 `parse` / `format` 与可选 `control` 部件；pin-input 的 `pattern` - **新增** 全局配置做成真正的 ConfigProvider：全局默认 + 局部覆盖，两个适配器一份语义 - **调整** **浮层搬进单一落点**：19 个浮层的 positioner 一律 Teleport 到 `#xh-portal-root`。宿主祖先只要建了层叠上下文，原地渲染的浮层层号就退化成局部序号——这是库无法从自身约束的。**按 `wrapper.querySelector` 取浮层节点的代码要改从 `document` 取** - **调整** **盒的定义统一**：有 `control` 部件就是盒，`trigger` 退化成盒内的 `flex: 1` 按钮。此前 16 个输入 / 选择控件有三种盒，盒是 `