生态产品多个设计器现已发布正式版

查看生态总览
曦寒视图组件文档
取本页 Markdown

更新日志 · XiHan.UI ​

本文件记录 XiHan.UI 各版本的变更。每条标注 新增 / 修复 / 优化 / 调整 / 移除 类别。只收录使用者可感知的变更，仓库自身的配置、CI、测试与门禁不列入。组件以 npm 包形式发布，升级前请留意「调整」类中的破坏性变更。

v5.5.2 (2026-11-12) ​

本版修复 Web Components 按需注册在元素类被打包出两份时栈溢出。

  • 修复 同一版本的元素类被打包出两份时（如开发服务器预构建了一部分包、另一部分按源码引用），后一份经 defineXhElement 按需注册会无限递归到栈溢出：菜单这类在 static dependencies 里依赖自己的元素认不出已经走过的标签。现在一次注册里走过的标签不再走，标签仍归先注册的那份

v5.5.1 (2026-11-10) ​

本版修复纯图标按钮只改高度时被拉成横的。

  • 修复 纯图标按钮（iconOnly）只改 --xh-button-h 时被拉成横的：高按覆盖值缩了，最小宽仍按尺寸档撑回去（sm 档压到 20px 高的钮宽 28px）。现在最小宽跟着 --xh-button-h 走，仍是正方盒，与文档里这个槽同管块向与行内向一致

v5.5.0 (2026-11-10) ​

本版把全库组件的状态变化补齐了过渡：展开收起按实测高度补间，列表增删与换序有进退场和换位，换图、换页、换张交叉淡变，指示条、提示框与各类占位出没时淡入淡出，换色一律淡变；流式正文的光标挂到外壳上，贴着最后一个字走，写完原地淡出。

升级须知

  • MarkdownStream：块上不再发 data-caret，认生长块改用 data-live；外壳在流式期间一直带 data-caret（原先只在一块都没来时带），一块都没来时带 data-empty。自己写过光标样式的要跟着改选择器
  • 图表 API：各图表 API 的 tooltip（热力图为 tooltipCell）在提示框收起后留着上一回的内容供淡出，从没露过面时才是 null；判断提示框在不在场改看 getTooltipProps() 的 data-state
  • 快照与测试：大量部件新增了进退场、换位与高度补间，视觉快照和按 DOM 即时状态断言的测试需要等动画播完，或在减弱动效下运行
  • 新增 动效原语（@xihan-ui/core）：trackDisclosureMotion（密集展开按实测高度补间）、expandIn（刚露出的内容按实测高度展开）、tweenBlockSize / tweenBoxSize（换排法、换内容时从旧尺寸补到新尺寸）、markGhost（退场替身的公共标记）；trackListMotion 新增 enabled
  • 新增 trackMarkdownStreamCaret（@xihan-ui/headless）：把流式光标贴到正文最后一个字后面，收尾时原地淡出；三个适配器的外壳已接好
  • 新增 Heatmap 的 tooltipCell：详情条里该写的那一格，隐去时留着上一回露面的那一格
  • 修复 展开收起硬切：树、树选择、JSON 查看器、侧导航内联子层、表格详情行与树形表格子行、工具调用审批面、警示条重新露面与 Truncate 铺开收回，现在按实测高度补间，展开箭头同拍转向；侧导航宽度交给外层容器时，等容器的宽度过渡走完再换排布
  • 修复 列表增删与换序硬切：网格列表、条件编辑器、穿梭框、标签页与面包屑的条目增删有进退场，留下来的条目从旧位置滑到新位置；表格排序、筛选改了行序时行从旧位置滑过去
  • 修复 换装硬切：头像与图片换图交叉淡变；日历翻页、标签页与步骤条换面板、导航菜单换张时新的一面淡入；滑块点到轨道上补到落点；浮动面板收拢与还原补间；关系图按 + / - / 0 缩放补间过去，受控时一次按键只派发一次 view-change
  • 修复 出没硬切：锚点与导航菜单的指示条、审批卡的待决圆点、图表提示框、骨架屏、漫游引导换步的文字、各类清空钮与空态 / 加载 / 错误占位、日期字段的占位、大写锁定提示等，出现与消失时淡入淡出
  • 修复 换色硬切：一批部件换语气、校验失败、禁用、选中与拖动时的底色、描边、字色与压暗改为淡变
  • 修复 MarkdownStream 写完时光标当场消失：光标挂到外壳上，出字后贴在最后一个字后面，换到下一块时跟着走、不重播进场，写完在原处淡出；生长块不再为光标多占一行，收尾时正文不再往上跳
  • 修复 React 的树选择首帧就带着手写节点时，节点没算进去
  • 修复 Alert 在没有 Web Animations 的宿主（jsdom、旧引擎）里收起时状态机崩溃；JsonViewer 的 Vue 与 React 端的 id 不再随挂载次数变化，服务端与客户端一致

v5.4.1 (2026-11-09) ​

本版修复分格输入被外部改写后的焦点错位，组件里选中的文字回到系统高亮色。

升级须知

  • 快照：组件里有选中文字的视觉快照需要更新；宿主要统一选区色时自己写一条通配的 ::selection
  • 调整 基线层不再给库子树写 ::selection，组件里选中的文字回到浏览器 / 系统的高亮色，与页面上库外的文字一致；原先的品牌色 12% 淡底在悬停行、条纹行和深色面上几乎看不出选中了哪段
  • 修复 分格输入（PinInput）的值被外部整份改写（受控值被清空、setValue / clear、表单重置）后，焦点仍停在末格，接着敲的字符顺序错乱；现在焦点在组内时收回到第一个空格，焦点不在组内时不动

v5.4.0 (2026-11-07) ​

本版把「无滑块开关」一类的选中面统一成实心主色：分段控件的选中段、切换按钮组的选中段、切换按钮的按下态与工具栏的按下项都与实心按钮同一块面，字反白，在一排浅灰的段里一眼看得出哪个是当前。

升级须知

  • 外观缺省：--xh-bg-segment-selected / -hover / -disabled 与 --xh-fg-segment-selected / -disabled 的值改为实心主色一组（与 --xh-bg-brand / --xh-fg-on-brand 同值），覆盖过这几支令牌或工具栏按下项槽位的主题按新口径核一遍；要原来的淡底选中段，切换按钮组写 variant="subtle"
  • 快照：分段控件、切换按钮组、切换按钮与工具栏有选中 / 按下态的视觉快照需要更新
  • 调整 分段控件（RadioGroup variant="segmented"）的选中滑块改为实心主色、字反白，语气档取语气的实心面；选中段拿到键盘焦点时焦点环内侧衬一道底色间隔线，打印时字换回常规字色。墨色域里分段选中面与实心品牌面同口径（墨色实心 / 悬停 88% / 禁用 50%，字取域底色）
  • 调整 切换按钮组（ToggleGroup）不写 variant 时选中段与 solid 档同为实心主色，未选中段仍坐在中性淡底的壳上；语气档走语气的实心面
  • 调整 切换按钮（Toggle）四档形态按下时一律实心主色，变体只决定未按下时的样子；按下态带实心面的顶边内高光（solid 档原先把这条高光写进了渐变用的颜色槽，从未画出来，一并修正），键盘焦点环内侧衬底色间隔线，打印时字换回常规字色
  • 调整 工具栏（Toolbar）的 aria-pressed 项同为实心主色、字反白，描边同色，--xh-toolbar-item-bg-pressed / -pressed-hover / -pressed-active / --xh-toolbar-item-fg-pressed 的缺省值跟着换；禁用且按下的项底色掺一半中性面、字留反白，新增 --xh-toolbar-item-bg-pressed-disabled 可改它
  • 修复 useFieldControl() 交出的接线属性里带着字段的皮肤挂载类 xh-scope-field，绑到 Button 这类自带 data-part="root" 的组件上会被字段根的皮肤选中，按钮变成纵向排布、文字跑到上方；现在只交出 id、aria-* 与状态位，Vue 与 React 两端同步

v5.3.0 (2026-11-07) ​

本版理顺了浮层叠在一起时的层外按下：提示、悬停卡片、悬停展开的菜单这类悬停就出现的层压在下拉、菜单、弹出层上面时，不再挡住它们收起；按下带提示的按钮后，提示也不再被重新打开。Layer 新增可选成员 opensOnHover，按次版本发布，没有破坏性变更。

  • 新增 Layer 的可选成员 opensOnHover（@xihan-ui/core）：登记层时写 true，表示这一层悬停就出现、不经按下打开，挡层外交互时只护着开在它内容里的层；缺省内联层为 true，其余为 false。LayerRegistry 新增可选方法 nestedAbove(layer)；@xihan-ui/headless 新增 menuOpensOnHover(props)，自建适配器登记菜单的层时用它填 opensOnHover
  • 修复 下拉、菜单、弹出层开着时，后出现的提示（Tooltip）挡住它们的层外按下：按带提示的按钮、按空白处，或提示正在退场的那一小段里按空白处，下拉都收不回去；悬停展开的导航面板同理
  • 修复 悬停卡片、Citation 的悬停预览、悬停展开的菜单与浮动按钮、SideNav 图标栏的浮出面板压在下拉上面时同样挡住层外按下；现在按空白处时它们和下拉一并收起。连带的一处变化：悬停展开的菜单把焦点拿进自己的内容里，下面与它无关的下拉在菜单出现后随即因失焦收起
  • 修复 弹出层、对话框里一颗带提示的按钮，提示在场时按层外要按两次才收得掉外面那层；现在一并收起，外层等开在它里面的层退栈后再释放，Dialog / Drawer 的 onExitComplete 随之晚到，通常不超过一次退场的时长
  • 修复 按下带提示的按钮后，提示收起又被点击带来的聚焦重新打开，并一直挂到按钮失焦；SideNav 折叠成图标栏后点一行，名称提示同样不再重开。指针移开再回来、键盘聚焦时提示照常出现

v5.2.0 (2026-11-06) ​

本版统一了全库的设计细节：圆角改由一颗种子派生，聚焦环画在元素盒内，缺省品牌色换了色相，阴影收成三档，动效时长收成两档，Tooltip 改用与 Popover 相同的浮层面。功能上，表单控件放进字段组即可读写值，选择类组件的值可以是任意类型，表格有了数据驱动模式，对话框、抽屉、分页和树不写结构也能用，浮层机制改为第一次打开时才加载。本版有一批外观缺省值与令牌的破坏性调整，按次版本发布，升级前请看升级须知。

升级须知

  • 外观缺省：缺省品牌色由 OKLCH 色相 258 换为偏紫的 277，要保留原来的颜色写 data-brand="indigo"；字段静息改为白底；Card 等 raised 面带 sm 投影；浅色主题的模态遮罩降到 40%；Tooltip 不再反白，缺省停留改为 150 / 100ms；Alert 加语气淡边；手风琴缺省 variant 改为 ghost，指示器排在标题前
  • 令牌：圆角改由 --xh-radius-seed（8px）派生，--xh-radius-sm / md / lg 由 2 / 4 / 8px 变为 6 / 8 / 10px，删除 --xh-radius-xl；--xh-glyph-size-md / lg 改为 18 / 20px；Progress 轨道改为 4 / 8 / 12px；--xh-duration-fast 改为 150ms，--xh-motion-duration-nudge 改为 200ms，@xihan-ui/motion 的 durations.fast、motionDurations.nudge 同步
  • 语气：不再跨组件继承，放在带语气的容器里的组件取自己的缺省语气，需要染色的在子组件上显式写 tone；Portal 视觉桥不再带 data-tone；动作控件上 tone="neutral" 与不写等价
  • 动效：锚定列表与菜单改用与面板相同的 xh-overlay-pop-in / xh-pop-out，删除关键帧 xh-overlay-slide-in / xh-overlay-slide-out；勾选标记改为描线，覆盖过标记 scale 的主题改写 clip-path
  • 删除：液态粘连（trackLiquidGoo、LiquidGoo 类型、弹簧预设 merge、--xh-motion-spring-merge-* 令牌）；Slider、ColorSlider、ColorPicker 拇指的投影与缩放覆盖槽共 10 个；FloatButton 状态机的 merging、startMerge、endMerge 改名 exiting、startExit、endExit
  • 快照：圆角、图标尺寸、焦点环与动效时长都有变化，视觉快照和按时长等待的测试需要更新
  • 新增 表单：录入控件放进字段组即按字段名读写值表（已登记 37 个控件）；值类型由 defaultValues 推断，字段名写错编译即报错；schema 接收 Standard Schema
  • 新增 选择类组件（Select、Combobox、Listbox、RadioGroup、CheckboxGroup、ToggleGroup）的值可以是任意类型，对象值用 valueKey 指定键；Combobox 内置 filter
  • 新增 表格数据驱动模式：给 columns 与 data 即可排序、筛选、分页，行类型由 data 推断；Table 与 Select 的标准结构支持 virtual 虚拟化
  • 新增 标准结构：Dialog 与 Drawer（title、description、确认与取消按钮）、Pagination、Tree（含懒分支 loadChildren）不写子内容即可使用
  • 新增 接入方式：Nuxt 模块 @xihan-ui/vue/nuxt、按需解析器 @xihan-ui/vue/resolver 与全量插件 @xihan-ui/vue/plugin、按用到的组件注入皮肤的 @xihan-ui/styles/vite；React 产物带 'use client'；data-theme="system" 纯 CSS 跟随系统明暗；可选的字体入口 @xihan-ui/styles/global.css
  • 新增 Button 的 dashed 与 link 形态；菜单 translations.trigger；CLI 新增 xihan-ui migrate，跨大版本升级时改写源码
  • 优化 浮层机制第一次打开时才加载，只用 XhSelectRoot 时首屏由 53.5 kB 降到 33.1 kB（gzip）；发布的样式改为压缩产物，index.css 由 2.7 MB 降到 1.6 MB；undefined.css 改名 not-defined.css，旧路径在 5.x 保留
  • 修复 宿主带 [hidden]{display:none!important} 时浮层与面级披露的退场动画、字段项距；CSS zoom 下浮层偏离锚点；悬停浮层半路收起；手风琴与折叠区域的开合动画；表格详情行跨列宽度与冻结列上的焦点环等十余处

v5.1.0 (2026-10-22) ​

设计器外框加关闭钮；设计器零件与组件库在设计器里少做无用功，拖动、缩放、点选与改属性更跟手。

  • 新增 设计器外框 xh-designer-frame 加 closable：开着时菜单栏最右端显示一颗关闭钮，按下派发 close，怎么关、要不要先问未保存的修改由宿主定；窄屏菜单栏收成「菜单」钮时仍在右上角。外框文案新增 close（「关闭」），十种语言都已提供
  • 新增 trackOverflowLayout（@xihan-ui/core）的选项加 onDescribe：只有条目的声明变了时回调它，不给时照旧回调 onChange
  • 优化 设计器零件更新时少做无用功：属性面板刷新时没变的字段不再重新接线；变换覆盖层在视口变化与拖动途中不再当场量选中工具条、尺寸徽标与覆盖层自己的位置；小地图的尺寸由观察器记下，图形换了一份时只改变了的节点；外框只换了文字时只改那张卡片；问题面板换了一份内容相同的问题时不再重铺列表
  • 优化 Toolbar 溢出收纳：条目只改了可及名、按下态或禁用时不再重量排版，只重读收起的条目在「更多」菜单里的样子
  • 优化 TextField 多行自动增高（autoSize）：值、占位符、行数配置、样式表给的上限与排字样式都没变的更新不再重新量高；宽度变化由 ResizeObserver 盯着，网页字体加载完后的下一次更新照样重量；需要量高时一次排版读完
  • 优化 Web Components 接线后取消部件身上已经起播的过渡：一批部件只同步算一遍样式，不再逐个部件重算

v5.0.0 (2026-10-21) ​

本版为打印、流程、表单、报表四款设计器补齐组件能力：多数组件改用标准结构，不写结构就能用；库内表单控件统一命名与表单状态继承；新增条件编辑器、格式输入、表达式输入框，首发设计器内核、设计器界面零件、受限表达式与 xlsx 写出四个包。少数事件、属性、类型、语言包键与覆盖槽有改动，全部包同号升到 5.0.0，升级前请看升级须知。

升级须知

  • 日历族：周、月、季度、年视图改为按行渲染，面板与 buildPeriodGrid 的 cells 改为 rows，网格底下写 week-row、格子放进行里；自备格子列表用 calendarPeriodRows(periods, view) 切行
  • 热力图：cell-press / cell-active 改名 datum-press / datum-active（onCellPress / onCellActive → onDatumPress / onDatumActive），删除 cell-focus / onCellFocus；HeatmapCellDetails 改名 HeatmapDatumDetails，删除 HeatmapCellFocusDetails
  • 表格：删除 footer（WC footer），改写 footerRows: 1（WC footer-rows="1"）；getFooterRowProps() 改为 getFooterRowProps({ level })，多行表尾每行写 level
  • 颜色换算：colorParse、colorToString、colorRgbaToHex 等 15 个颜色函数与 ColorRgba、ColorHsva、ColorHsla、ColorOklch、ColorFormat 改从 @xihan-ui/core/color 引入，@xihan-ui/headless 不再导出；colorParse 改按 CSS Color 4 的语法，分隔符混写、逗号写法里数与百分数混用、十六进制不带 # 这类浏览器不认的写法返回 null
  • 令牌的颜色换算：@xihan-ui/tokens 不再导出下表左列的名字，改从 @xihan-ui/core/color 引入右列；colorParseOklch 解析不了时返回 null（原先抛错）；分量越界的颜色（如 oklch(120% 0.1 30)、透明度大于 1）不再夹回范围，令牌其余颜色函数遇到时抛错；白、灰、黑的色相写成 0
    4.x（@xihan-ui/tokens）5.0（@xihan-ui/core/color）
    srgbToLinearcolorSrgbToLinear
    linearToSrgbcolorLinearToSrgb
    linearRgbToOklchcolorLinearRgbToOklch
    oklchToLinearRgbcolorOklchToLinearRgb
    parseColorToOklchcolorParseOklch
    inSrgbGamutcolorInSrgbGamut
    clampChromacolorClampChroma
    formatOklchcolorFormatOklch
    Oklch（类型）ColorOklch（字段相同）
  • 快捷键：formatHotkey、matchesHotkey、detectKbdPlatform、resolveKbdPlatform 与 KbdPlatform、KbdResolvedPlatform、HotkeySegment 改从 @xihan-ui/core/hotkey 引入，@xihan-ui/headless 不再导出
  • 语言包：删除 Citation 的 openSource、source，覆盖过的直接去掉；FileUpload 的 dropzone 改作标准结构里投放区那句看得见的说明，手写结构的投放区改由标题接上投放区里看得见的说明命名
  • 覆盖槽：删除 --xh-command-list-busy-opacity
  • HoverCard：HoverCardRefs 删去 getTitleEl / getDescriptionEl，Vue 的 HoverCardContext 删去 titleRef / descriptionRef，React 的删去 setTitleEl / setDescriptionEl；自写标题、说明部件的改为经 parts 报告在场
  • 表单校验：只含空白的字符串与元素全为空的数组算空，required 会拦下；min / max 对字符串改按字素计数。依赖原行为的改在 validator 里自行判断
  • React Card：XhCardRoot 的 title、content 改为卡片的标题与正文，不再作为原生属性写到根上
  • Web Components FileUpload：条目改按 allFiles 对应（远程附件在前、本地文件在后）；用了 remoteFiles 的改按 allFiles 铺行
  • Web Components 布尔属性：全部改为三态（含 designer-shell 的零件），显式写 ="false" 为假、不写交给缺省；写过 disabled="false" 却想要真的改成 disabled，移除属性改为回到组件缺省
  • Web Components 对话框与抽屉：<xh-dialog>、<xh-drawer> 的语义角色改写 dialog-role（property dialogRole），role 不再当作配置；写过 role="alertdialog" 的改成 dialog-role="alertdialog"。role 写在宿主上，宿主本身就成了对话框，里面的触发钮也被读成在对话框里。Vue 与 React 的 role 不变
  • Web Components 通知条目：<xh-notification-item> 的标题文案改写 title-text（property 仍是 titleText），title 不再当作配置；写过 title="已保存" 的改成 title-text="已保存"。title 写在宿主上，悬停会出浏览器原生提示，读屏还会把标题当描述再念一遍。通知服务与 Vue、React 的 title 不用改
  • 缺省结构：根组件不写默认插槽 / 不给 children、Web Components 元素不写部件时，原先渲出空的根，现在铺出整套部件
  • 外观：渲染成 <button> 的部件清掉浏览器缺省样式，WC 作者自写的按钮部件接线后同样无壳，要按钮外观时把 Button 当作这个部件写进去
  • FileUpload：点标题改为把焦点交给投放区，不再直接弹出选择框
  • ColorPicker：单选给空数组改为未选（色块画斜线、值文字显示 placeholder、value 为空数组），不再按 #000000 显示；要黑色的改写 ['#000000']
  • 树：multiple 改为选择模式 selectionMode（Web Components 为 selection-mode），multiple: true 改写 selectionMode: 'multiple'（Vue 模板与 Web Components 写 selection-mode="multiple"）；TreeApi 的 multiple 改为 selectionMode，判断是否多选改读 selectionMode !== 'single'。TreeSelect 的 multiple 不变
  • 菜单族的选中事件：Menu、ContextMenu、Menubar、Command、Mention 的 select 改名 item-select，不再与原生 select（输入框里选中文字时冒泡上来）同名：Vue 的 <XhMenuRoot @select="run"> 改写 <XhMenuRoot @item-select="run">，React 的 onSelect={run} 改写 onItemSelect={run}，Web Components 的 menu.addEventListener('select', run) 改监听 'item-select'，event.detail 不变；headless 的 onSelect 改为 onItemSelect，详情类型 MenuSelectDetails、ContextMenuSelectDetails、MenubarSelectDetails、CommandSelectDetails、MentionSelectDetails 改为 MenuItemSelectDetails 等（字段不变）。React 的 Menubar、ContextMenu、Mention 根上不再拦原生 onSelect，写了就照原生事件透传到根节点。Command 的 select(value) 方法不变
  • Popconfirm 的取消事件：cancel 改名 cancel-press，不再与原生 cancel（文件输入框取消选择时冒泡上来）同名：Vue 的 <XhPopconfirmRoot @cancel="undo"> 改写 <XhPopconfirmRoot @cancel-press="undo">，React 的 onCancel={undo} 改写 onCancelPress={undo}，Web Components 的 popconfirm.addEventListener('cancel', undo) 改监听 cancel-press，headless 的 onCancel 改为 onCancelPress；确认事件 confirm、方法 cancel() 与部件 cancel-trigger 不变
  • 菜单族的对号与行首：Menu、ContextMenu、Menubar 的 item-indicator 只当对号，只在勾选与单选条目上出现，标准结构里挪到条目最后（正文、说明、快捷键与 item-suffix 之后），改落 Collection Item 的 indicator 列；行首内容全部归 item-icon，条目数据删去 indicator 文字。三种写法要改：item-prefix 插槽的内容现在落在 item-icon，给它写样式的改按 item-icon 选；手写 ItemIndicator 当行首图标的改用 ItemIcon（Web Components 写 data-xh-part="item-icon"）；给 item-indicator 写样式改图标颜色的改写到 item-icon（它本来就随条目字色走）。数据里写 indicator 文字的改写 icon，要表达选中改用勾选或单选条目；按位置选部件的（如 [data-part='item'] > :first-child）改按 data-part 选
  • designer-kit 与 designer-shell（首发）：5.0.0 是这两个包的第一版，没有已发布的写法要迁移，接法见文档站的「设计器内核」「设计器零件」两页。开发期按 link 接过 dev 的使用方对一下这几处：变换覆盖层去掉 formatMeasure，改给 measureOptions（如 { unit: 'mm' }），宽高的改动经 measure-change 交回设计器；历史栈的说明类型是 HistoryLabel（字符串，或换语言后现取的函数）；BUILTIN_CONTROL_KINDS 已含 options 与 treeOptions，产品自己登记的同名编辑方式要去掉；零件里的菜单命令改听 item-select，复选条目经 checkbox-value-change 回报；配无层皮肤 @xihan-ui/styles/index.unlayered.css 时改引 @xihan-ui/designer-shell/style.unlayered.css
  • 新增 Menu、ContextMenu、Menubar 按数据铺时，条目可写 keyshortcuts，落成条目的 aria-keyshortcuts，读屏念得出快捷键；看得见的快捷键提示照旧是装饰
  • 新增 Menu 的 fitAvailableHeight（Web Components 为 fit-available-height）：内容只按可用高度封顶，不叠 20rem 的固定上限；菜单栏的子菜单由菜单栏自动带上
  • 新增 @xihan-ui/web-components/authoring 导出 notifyXhConfigChange 与类型 XhConfigScope、XhConfig：自定义元素声明 xhConfig 即可当一层配置作用域（如设计器单独设语言），改了它就调 notifyXhConfigChange(this)，子树里已渲染的元素（含浮层内容）照新配置重画
  • 新增 Menu、ContextMenu、Menubar 按数据铺时，带 children 的条目可写子菜单那一层的勾选值与单选值（checkboxValue / radioValue），子层里的勾选与单选条目照它显示；Vue / React 的 XhMenubarSub、XhContextMenuSub 同 XhMenuSub 一样收这一层的勾选与单选并派发改动
  • 新增 标准结构：Select、Combobox、TreeSelect、Cascader、Menu、ContextMenu、Menubar、Accordion、Tabs、ToggleGroup、RadioGroup、CheckboxGroup、Checkbox、Switch、Slider、Rating、TextField、NumberField、PasswordInput、PinInput、DateField、DatePicker、DateRangePicker、TimePicker、TimeRangePicker、ColorField、ColorPicker、TagsInput、TagGroup、Listbox、Transfer、SignaturePad、Field、Fieldset、FieldArray、FileUpload、Mention、Command、ColorSwatchPicker、Breadcrumb、NavigationMenu、Card、Separator、Heatmap 等不写结构即可使用，Vue、React 与 Web Components 照同一个结构函数铺出同一棵树；Web Components 用 slot="<名>" / slot="<名>:<键>" 把作者内容放进对应部件
  • 新增 条件编辑器 FilterBuilder、格式输入 FormatInput、表达式输入框 ExpressionInput，三端同时可用
  • 新增 包 @xihan-ui/designer-kit（画布式设计器的公共内核：历史栈、视口、命中与变换、属性描述、扩展机制、表格与网格几何、剪贴板）、@xihan-ui/designer-shell（设计器界面零件：外框与面板布局（停靠、浮出、收成标题条，整份布局存进设置）、属性面板、物料面板、页面结构、历史面板、问题列表、小地图、变换覆盖层与它的上下文工具条和尺寸徽标、标尺、设置对话框（含帮助、快捷键与关于）、JSON 编辑框、导入字段对话框、新手引导、命令工具栏与状态栏项，附与 UI 内建语言包对应的十种语言文案；另有配无层皮肤用的 style.unlayered.css）、@xihan-ui/expression（受限表达式与格式化）、@xihan-ui/xlsx（零依赖的 xlsx 写出）
  • 新增 @xihan-ui/core 子入口 json、rich-text、rich-text-dom、url、template、hotkey（含与 aria-keyshortcuts 互转的 ariaKeyshortcut / parseAriaKeyshortcuts 与按平台显示的 formatHotkeyLabel）、color（颜色换算，按 CSS Color 4 的语法解析，另认 oklab()、color(srgb …) 与色相单位 grad、rad、turn；不取整的 OKLCH 换算与按色域收彩度）、svg-export（SVG 导出成能单独打开的一份，并可栅格化成 PNG）、clipboard（往系统剪贴板写文本的 writeToClipboard）、options（选项与选项树的结构校验 findOptionViolation）；core/json 新增出错时报行列的 parseJsonText 与按路径定位的 locateJsonPath；core/date 新增墙上时间与分桶键
  • 新增 库内表单控件统一新增 ariaLabel；ToggleGroup、Combobox、ColorPicker、Transfer、CheckboxGroup、Slider、TreeSelect、Cascader、FileUpload 补齐 required / readOnly / invalid，放进字段或表单时自动继承；字段标题点击聚焦库内控件，Web Components 的字段接线落到控件真正可聚焦的部件上
  • 新增 FileUpload 远程附件的文件名铺成链接（部件 item-link，打开方式 linkTarget），地址不安全时退回纯文字
  • 新增 ColorPicker 单选的未选状态（placeholder）与清空钮 clear-trigger（clear 事件）
  • 新增 FieldArray 表格排布 layout="table"、insert / move、value-change 带行变更；不写结构时只给每行内容即可；列的 minWidth 给出下限，放不下时表格区横向滚动，行号与把手钉在两侧，窄容器里可写 stickyActions: false 让把手随行滚动；开了 movable 每行多一颗拖动把手 item-drag-trigger，按住拖到别处换位，键盘与读屏照旧用上移、下移
  • 新增 Table 多行表尾 footerRows 与吸底 stickyFooter、行主操作 onAction、列的 rowHeader（也可按行给函数）、表尾单元格合并 footerCellSpan，Web Components 新增 visibleRows；Select 新增取数失败状态与重试，Combobox 新增在途占位；Heatmap 新增受控联动键 activeKey、pending、empty 与 format
  • 新增 TextField multiline、NumberField 与 TimePicker 的 placeholder、TimeRangePicker 的 startPlaceholder / endPlaceholder、Grid ruled、Accordion contentRole、TreeSelect 搜索框的占位文字 translations.searchPlaceholder；日历翻页钮带上按视图的缺省读屏名
  • 新增 Tree 分支行的说明部件 branch-description，带说明的分支与叶子一样折成两行，说明在名称下面
  • 新增 Menu、ContextMenu、Menubar 的条目图标（条目的 icon，部件 item-icon）；Toolbar 的 itemIcons，收进「更多」的条目带着各自的图标；Toolbar 的条目可声明只放图标（Vue / React 的 iconOnly，Web Components 写 data-icon-only），按方钮画；Web Components 的 <xh-icon> 一个部件都不写、或只写一个空的 root 时自己生成图形，只给 icon 即可
  • 新增 Splitter 双击分隔条折叠它一侧可折叠的面板，再双击回到折叠前的尺寸；Enter 与双击同一件事，前一块不可折叠时管到可折叠的后一块
  • 新增 Tree 节点数据的 draggable: false：这一个节点拖不起来，照常能选、能展开、能当落点
  • 新增 Tree 的选择模式 extended：照文件管理器，点击换成这一项，按住 Ctrl / Cmd 点击或按 Ctrl / Cmd + Space 加选与取消，按住 Shift 点击选一段；两种多选模式下 Ctrl / Cmd + Space 都只切换焦点节点；选中从外面换了（宿主另写了值、调了 setSelection、挂载时就带着选中），Shift 点击从新选中里多出来的最后一项连起
  • 新增 @xihan-ui/core 的页面级窗口叠放序 getWindowStack(doc)；浮动面板几个同时开着时，点到或聚焦哪个哪个到最上面，最上面的仍在模态层之下
  • 新增 @xihan-ui/core 的页面级礼貌播报器 announce(message)：整页一个播报区挂在 body 末尾，同一句话连播也会再读，模态浮层打开时照旧可读；不属于某一个组件的播报用它，设计器外框的 announce 改经它；视觉隐藏的内联样式 VISUALLY_HIDDEN_STYLE 也从 core 导出
  • 新增 Table 的 tree：声明这是一棵树，一行 parentId 都没有时也报 treegrid、Alt + 左右键改层级、任何一行都能接受「放进去」，叶子行不写 aria-expanded
  • 新增 FloatingPanel 的拖动起止事件 onDragStart / onDragEnd（Web Components 为 drag-start / drag-end），带指针位置与是否取消
  • 新增 Table 单元格级导航 navigation="cell"：照 WAI-ARIA treegrid，整张表只占一个 Tab 位，方向键在格子之间走，Enter 或 F2 进格内控件编辑、编辑中 Tab 只在这一格里走、Esc 退回格子，换位、改层级与拖动照常可用
  • 新增 Tooltip 的委托模式 delegate：一个提示管一整个容器里的锚点，文字取锚点的 data-xh-tooltip 或可及名，快捷键取 aria-keyshortcuts 并按平台显示；提示新增 translations.keyLabel
  • 新增 Menu 与 Popover 的 anchor：外部的一颗按钮可以当锚点，由它受控打开，浮层贴着它定位、收起时焦点还给它，展开期间它带上弹出关系；写了 anchor 时可以不写触发器
  • 新增 Virtualizer 的 estimateFromMeasured（Web Components 为 estimate-from-measured）：没量过的条目按已量条目的平均尺寸估算，行高随尺寸、密度与皮肤变化的列表不必写死 estimateSize
  • 新增 Tour 的 boundary：把引导限在一块区域里，遮罩与高亮框只盖这块区域、气泡以它为界避让，区域外照常可读可点；定位引擎与层栈各补了配套的 boundary、covers
  • 新增 令牌的预设品牌 BRAND_PRESETS（如 blue、green、orange、pink）与各档代表色 BRAND_PRESET_COLORS，data-brand 直接换一套品牌原语、不必 registerBrand，各档的对比度与缺省品牌同样达标
  • 新增 Web Components 子入口 authoring（编写同形 Light DOM 元素的基类、布尔属性的三态转换器 BOOLEAN_CONVERTER 与工具）与按需注册 defineXhElement
  • 新增 设计器画布与表格编辑命令用的一批图标（编辑、拖动、对齐与分布、层级、表格行列与合并等）
  • 新增 @xihan-ui/pointer 的 wheelPixels：把按行、按页计量的滚轮滚动量折成像素（缺省一行 16、一页 400），Tabs 的滚轮滚动与图表的滚轮缩放改用它，换算值不变
  • 新增 @xihan-ui/viz 有向图算法、分层布局与直角连线、折线工具、多样式折行 wrapRuns、表格数据处理与 pivotWider
  • 优化 按需注册一个元素的产物从约 160 kB 降到约 15 kB（gzip）；@xihan-ui/expression 可摇树
  • 调整 Web Components 的 <xh-dialog>、<xh-drawer> 语义角色改写 dialog-role，宿主上不再带 role（详见升级须知）
  • 调整 Web Components 的 <xh-notification-item> 标题文案改写 title-text，宿主上不再带 title（详见升级须知）
  • 调整 Menu、ContextMenu、Menubar、Command、Mention 的选中事件改名 item-select（onItemSelect），不再与原生 select 同名（详见升级须知）
  • 调整 Popconfirm 的取消事件改名 cancel-press（onCancelPress），不再与原生 cancel 同名（详见升级须知）
  • 调整 Menu、ContextMenu、Menubar 的勾选与单选对号排到行尾，与子菜单箭头同列、快捷键在它之前，与 Select、Tree 等集合的对号同位；item-indicator 只当对号、在标准结构里挪到条目最后，行首内容全部归 item-icon、随条目字色走（详见升级须知）。勾选条目的图标与普通条目左缘对齐，同一层有勾选条目时整张菜单的快捷键同列
  • 调整 Menubar 的下拉与它的子菜单只按可用高度封顶，和桌面应用的菜单栏一样，可用高度够时整张菜单一次铺开、不出滚动条；要收矮写 --xh-menubar-max-h。Menu 与 ContextMenu 照旧以 20rem 一档封顶
  • 调整 菜单族的下拉与子菜单、Listbox、Select、Combobox、Command、Mention：同一层里只要有一条带行首图标，所有条目都空出图标那一格，正文左缘对齐；整层都没有图标就不留
  • 修复 弹层、提示与图表族只引用实际渲染了的标题与说明（Dialog、Drawer、Popover、Popconfirm、Tour、Alert、Approval、Notification、FloatingPanel、Fieldset、Field、Table、图表），不再挂落空的 id
  • 修复 Tree、TreeSelect、JsonViewer、Citation、FileUpload 的可访问名包含看得见的字；危险色文字与刷新中的集合在所有表面上达到 4.5:1 对比度；Tabs 横线档的当前页悬停、键盘高亮与按下时字深一档，在页面底与面上同样达到 4.5:1，带语气时不再退回品牌色；条件编辑器的删除钮在高对比档里按所在的面取字形色，悬停与禁用都分得开
  • 修复 Tree 叶子行的说明落在名称下面一行，窄的时候截断；Listbox、TagGroup、SignaturePad、Transfer 放进表单字段时接上字段的标题与说明；日期、时间选择器有值时点字段标题焦点落在第一段，放进字段时日历钮不再带按钮不允许的 aria-readonly
  • 修复 Tree 的 Web Components 版：分支行里摆的 item-indicator 跟着分支的选中亮出对号，不再一直不亮，与叶子行、Vue 与 React 一致
  • 修复 FieldArray 表格排布横向放不下时表格本体进 Tab 序列，一行都没有也能用键盘横向滚动，放得下时不占 Tab 位
  • 修复 亮色下警告色文字加深一档，达到正文对比度：--xh-fg-warning 改指 --xh-color-warning-800（对白底 4.98:1，原来 3.75:1），表达式输入框的警告提示、日志 warn 级、字数到上限等小字都够得上 4.5:1；暗色不变
  • 修复 Menu、ContextMenu、Menubar 按数据铺时，子菜单入口（带 children 的条目）写了 icon 却不画图标：入口与普通条目一样铺 item-icon 与 item-text；子菜单组件与 <xh-menu submenu> 新增 icon
  • 修复 菜单族与 Listbox、Select、Combobox、Command、Mention 的行首图标与正文上下居中：菜单族的 item-icon 按图标尺取高、图标在里面居中，候选列表 item-prefix 里的图标居中，图标比行高矮时不再贴着上沿、比正文高出约 2px；Web Components 的 <xh-icon> 宿主改为只包住图标的行内块（行高归 0），放进弹性或网格容器时与 Vue / React 一样居中
  • 修复 Tour 开在模态对话框或抽屉里时，锚定步的高亮框与遮罩、气泡同在引导这一层，排在外层对话框之上，周围照常压暗、目标照常框出；原先高亮框落回模态层的基数，被外层对话框盖住
  • 修复 Form 与 Fieldset 里带说明的字段在说明下面照常留一段项距，与只给错误文案留了一行的字段、普通字段交替排时留白一致，说明文字不再贴着下一项的标签；Web Components 里字段直接放进表单或字段集时（直接子项是 <xh-field>），只留了错误行的字段不再多留一段项距
  • 修复 Approval 待决的呼吸点取图形色，不随警告文字色变深；写了语气时六族在亮暗两态对承载面都不低于 3:1（warning 语气原来在白底上只有 2.69:1）
  • 修复 Web Components 的 Menubar 按 collection 铺结构时，数据里写的 disabled 照样生效：入口与条目报不可用、方向键跳过，与 Vue / React 一致
  • 修复 Vue 的子菜单（XhMenuSub、XhMenubarSub、XhContextMenuSub）改了属性后子层跟着变，不再只认挂载时那一份；Vue / React 的子菜单入口不再同时挂着菜单的皮肤挂载类，也照旧带着子层的展开态（data-state）
  • 修复 对话框、抽屉、弹出层这类带焦点域的浮层落焦时，只整段选中单行文本类输入框；第一个可聚焦元素是多行文本框时只落焦、不再全选里面的字
  • 修复 Web Components 里用 XhConfigController 取配置的元素断开期间换了语言、或被挪到另一个 <xh-config> 下，重新连上时按新的配置重渲，不再停在旧的文案上
  • 修复 FieldArray 表格排布的格子里放 Field 时，文本框的原生宽不再把这一列撑出去压到相邻的格上；设计器属性面板里放不下的选项表改为横向滚动，不再裁掉行尾的把手
  • 修复 Table 树形表换位后的读屏播报说放进了哪一层，位次与总数按那一层的兄弟行算，不再拿层内位次配全部可见行的总数
  • 修复 Sortable 嵌套时（项里再放一个排序列表），指针按住里层条目或它的手柄不再连外层那一项一起拖起来
  • 修复 开着的下拉被外面的点击收起、同一次点击又打开抽屉或对话框时，控制台不再报 core.layer.dispose-not-top；这条诊断只在父层先于开在它里面的层释放时报，明细新增 nested
  • 修复 Table 接了虚拟滚动时表体画出行间线，与普通表体同一条线，滚动换批时每一行的高度不变；条目里的详情行也画
  • 修复 Table 键盘换位之后，宿主写回时挪动了持有焦点的行节点，焦点不再掉回页面，回到搬走的那一行，可以接着再挪
  • 修复 Table 表尾里的冻结格补上不透明底，横向滚动时压住的格子不再透出来；树形表里有子行的行不再写指向不存在详情行的 aria-controls；纵向合并格按行的内容盒铺开，行间线画在行下边框上时起点行不再被一次次撑高；ButtonGroup 里的分体按钮，Web Components 的下拉钮跟着组的形态与尺寸，与主按钮连成一条
  • 修复 FieldArray 表格排布里一行的格子按这一行字段的尺寸档占一条控件高并居中，复选框、开关与文本框落在同一条中线上；Web Components 的复选框与开关宿主不再占一层盒子，与 Vue / React 一样直接参与外层排布
  • 修复 滚动锁在同一页面里允许不同目标同时锁住：外层对话框锁着布局里的滚动容器、里层对话框锁页面时（两份配置的 scrollRoot 不同），里层不再初始化失败、被外层盖住或点开即收起
  • 修复 浮层层级栈的先后看嵌套：对话框和里面缺省展开的下拉、或一打开就弹出候选的输入框同一刻打开时，浮层排在对话框之上、Esc 先关浮层
  • 修复 浮层层级栈、Esc 与外部点击的派发、焦点域、滚动锁与 aria-hidden 计数改为页面级单例：页面上装了几份 @xihan-ui/core（应用与设计器各自打包）时，Vue、React 与 Web Components 的对话框、菜单、Popover 与提示仍在同一个栈里，后打开的在上面，焦点与 Esc 只作用在最上层
  • 修复 Web Components 的 <xh-config> 管到搬进 Portal 的浮层内容：对话框、抽屉与下拉面板里的元素照它们在原来位置取 locale、size 与文案，打开期间改配置跟着更新；浮层里的 <xh-config> 承接外层的主题，禁用的 Fieldset 压进组里开的浮层。@xihan-ui/core 新增穿过 Portal 实例壳走逻辑祖先链的 logicalParentElement 与 logicallyContains
  • 修复 Web Components 的元素插入后、或往已连接的元素里放进新部件后紧接着有代码读布局时，部件不再先露出浏览器缺省样式、再从那里播过渡到皮肤色（插进来先带一圈深色边框，过一会儿才恢复）；新建插入、移出再插回、往已连接的元素里追加或整批换掉部件都是如此
  • 修复 ContextMenu 的触发区里已有自带 Tab 位的内容（可聚焦的画布、列表）时，触发区不再另占一个 Tab 位；菜单键与 Shift+F10 在那个元素上照常展开，关闭后焦点回到它
  • 修复 工具条与标签页的「更多」菜单在收起的条目换上或去掉图标、条目之间拿掉分隔线时，不再报 NotFoundError、整轮更新失败
  • 修复 Menubar 持有焦点的入口随数据删掉时，React 与 Web Components 的菜单栏不再整条退出 Tab 序列，与 Vue 一样由根节点留住 Tab 位
  • 修复 列表删行时淡出的替身显示删除前的值；条目禁用随作者的修改来回切换；多行文本自动增高在无排版环境里安静跳过
  • 修复 Fieldset 整组禁用时组内 Field 的标题与说明一起变淡，Scrollbar 不再随之禁用；React 的 Tooltip、Popover、Menu、DownloadTrigger 放进禁用的 Fieldset 时一并禁用，Tooltip 跟随全局 size；Web Components 的 FloatButton 接上全局 size 与文案

v4.2.0 (2026-10-15) ​

JsonViewer 新增按需打开的工具条与原文着色，图表配色整体改为浅色调，并新增命令行与 MCP 服务端 @xihan-ui/cli。

  • 新增 JsonViewer 内建工具条 tools：展开 / 收起全部、树与原文切换、原文自动换行、复制原文，可铺出全部或只列几项；新增 source，原文档与复制按后端原文显示，超出安全整数的 ID 不再失真；view 补上 defaultView / onViewChange，新增 wrap / defaultWrap / onWrapChange
  • 新增 JsonViewer 原文档按类别着色，键名、字符串、数字、布尔、null 与标点与树档同一套颜色
  • 新增 @xihan-ui/cli：组件 API、文档、示例、令牌、design.md 与更新日志的离线知识库，附命令行与 stdio MCP 服务端；setup 为 Claude Code、Cursor、VS Code、Codex 写入钉住版本的配置与使用技能
  • 新增 文档站新增「AI 辅助开发」一册：For Agents、MCP Server、CLI、LLMs.txt、design.md
  • 新增 图标 list-tree；表格单元格行内内衬令牌 --xh-table-cell-px-sm / -md / -lg；顺序色阶两段的文字色令牌 --xh-chart-on-sequential-low / -high
  • 调整 图表缺省分类色板、配色方案、有序色阶、涨跌色与亮色下的顺序、发散色阶改为浅色调，色块内文字换成深色；validateCategoricalPalette、validateOrdinalRamp 新增 tone: 'light'
  • 调整 表格单元格与列头的行内内衬随尺寸档换档（sm 8 / md 12 / lg 16px），此前三档都是 16px
  • 调整 多行文本字段自增高的上限槽改名为 --xh-text-field-input-max-h，旧槽 --xh-text-field-control-max-h 仍兜底生效
  • 修复 Descriptions 描边档：标签在左时同一列的标签按最长的那个对齐；有跨列或最后一行不满时格线不再错位，也不再与外框叠成两道
  • 修复 树形表的父行收起之后能再展开
  • 修复 Separator 竖线在由内容撑高的横排里铺满行高，不再只剩 1em 贴在行顶
  • 修复 多行文本 autoSize 顶到上限后只剩一层滚动，行数界限超过 12rem 不再被截掉

v4.1.0 (2026-10-13) ​

看片工具条补齐复原钮图标，通知里的长串不再撑出滚动条。

  • 新增 图标集 undo（U 形回转箭头），令牌 --xh-glyph-mark-undo
  • 调整 ImageViewer 复原钮不写内容时由皮肤画回转箭头，与其余工具钮一致（此前 Vue / React 显示「1:1」文字）；Web Components 写空的 reset-trigger 按钮即可
  • 修复 Notification 标题与说明里没有断点的长串（凭证号、令牌、文件路径）就地折行，不再顶出卡片或撑出横向滚动条

v4.0.1 (2026-10-12) ​

修复 4.0.0 的几处回退。

  • 修复 字段标题指向弹出式触发钮（Select、DatePicker 等）时只聚焦、不开合，下拉展开时点标题（含标题右侧空白）能收起
  • 修复 字段直接放进 Form（不包 XhFormFieldGroup）时，辅助行同样算项距，行距不再翻倍
  • 修复 Web Components 字段族宿主的 display: contents 改由皮肤声明：写在样式表里的 display 生效，带 hidden 的宿主不再被掀开
  • 调整 菜单与候选列表限高 --xh-overlay-menu-max-h 恢复为 20rem（紧凑 17rem）

v4.0.0 (2026-10-12) ​

本版是一次全库视觉改版：控件高降一档、圆角收窄、字段改为淡底且聚焦不画环、浮层改为实体底，并新增图表配色方案、日期与时间选择器底栏和作用域禁用。多数变化只影响外观，少数缺省值、令牌与覆盖槽有改动，升级前请看升级须知。

升级须知

  • 缺省值：Accordion variant 改为 outline、Tree variant 改为 ghost、Badge tone 改为 danger，日历的 weekdayFormat 改为 narrow，LOADING_BAR_HEIGHT 改为 3px；要保持原样请显式传值
  • 行为：Fieldset 的禁用会压到整棵子树；NumberField 增减钮在精细指针下悬停或聚焦才显出；Web Components 的 20 个字段族宿主缺省 display: contents，写在宿主上的宽度与外边距请改写到 root 或用 --xh-control-w
  • 令牌：控件高 sm / md / lg 为 28 / 32 / 36px（compact 24 / 28 / 32px），圆角 2 / 4 / 8px，浮层圆角 4px，标题 24 / 20 / 16px，--xh-motion-scale-press 为 1（主题写回 0.97 可恢复按下回弹）
  • 覆盖槽：删除或改名 60 个，集中在字段聚焦环、Dialog、Slider 与日期时间面板；写过这些 --xh-<组件>-* 的项目请对照各包 CHANGELOG 迁移
  • 快照：部分按钮的 data-xh-action-size 与动效时长有变化，视觉快照和按时长等待的测试需要更新
  • 新增 图表配色方案：在祖先上写 data-xh-chart-palette，取 monochrome / brand / muted
  • 新增 DatePicker、DateRangePicker、TimePicker 的底栏部件 footer
  • 新增 全局配置的 disabled 键，经 provideXhConfig / XhConfigProvider / <xh-config> 禁用整棵子树
  • 新增 Spinner 的 orientation；Web Components 嵌套宿主可用 data-xh-part 担任外层部件（目前支持 xh-button）；React XhButton 补上 download
  • 修复 无层样式的排版、窄屏溢出、粗指针命中区与强制色下的显示，共二十余处
  • 优化 Notification 叠摞与退场、列表换位的动效；图表入场放慢到 960ms

v3.2.0 (2026-10-06) ​

本版新增十种常用语言的内建语言包（locale 子入口），组件不再自带英文，界面文字一律取语言包；Dialog 与 Drawer 新增 unmountOnExit，Select 新增 lazyMount，Carousel 与 ImageViewer 新增 size，浮动圆钮整体下移一档。另有一批面向大页面的性能优化：模态背景失活改为只打 aria-hidden，Portal 视觉桥只在浮层呈现期间存在，皮肤产物改以挂载类 xh-scope-<组件名> 领头。挂载类、浮动圆钮尺寸与模态背景的变化会影响自写标记、视觉快照与页内查找，升级前请看下方升级须知。

升级须知

  • 皮肤挂载类：每个角色节点多带一个类 xh-scope-<组件名>，与 data-scope 一一对应，皮肤产物改以它领头。经 Vue / React / Web Components 使用组件的项目无需改动；只用 @xihan-ui/styles、自己书写标记的页面，要给每个带 data-scope="x" 的节点补上 class="xh-scope-x"，否则皮肤不命中。对 DOM 做快照或精确比对 className 的测试需要随之更新。data-scope / data-part 仍是公开的样式契约，覆盖写法不变
  • 浮动圆钮尺寸：Action Control 的 floating 档 sm / md / lg 由 40 / 48 / 56px 改为 32 / 40 / 48px（compact 28 / 36 / 44px）。BackTop、FloatButton 缺省由 48px 变为 40px、size="lg" 由 56px 变为 48px，ImageViewer 翻页钮由 48px 变为 40px、关闭钮由 40px 变为 32px，Carousel 翻页与播放钮为 40px；要保持原尺寸，把 size 调高一档
  • 模态背景：模态浮层的背景改为只打 aria-hidden、不再打 inert。键盘仍由焦点域收在浮层里，指针由遮罩或新加的透明底板拦下；页内查找（Ctrl+F）与文本选择现在能落到模态下面的内容上

  • 新增 内建语言包 zhCN、zhTW、enUS、jaJP、koKR、frFR、deDE、esES、ptBR、ruRU，放在新的 locale 子入口（@xihan-ui/headless/locale、@xihan-ui/vue/locale、@xihan-ui/react/locale、@xihan-ui/web-components/locale），主入口体积不变，只打进用到的那几份。一份语言包即一份全局配置 { locale, translations }（类型 XhLocale），直接交给 provideXhConfig / XhConfigProvider / setXhConfig，日期时间类组件的 locale 一并切换；语言包覆盖组件的每一条文案，含图表摘要、拖拽播报等函数式文案，个别文案仍可在实例上覆盖

  • 新增 原先写死的界面文字收进 translations，十种语言同步补齐：Dialog 新增 ok / cancel / actionError，命令式对话框服务没传 okText / cancelText / actionErrorText 时取服务所在配置的语言包，新增导出 dialogServiceTranslations()；Form 新增 translations 属性收进校验报错模板，取值顺序为规则的 message → validateMessages → translations → 英文语言包；Kbd 的 keyName 有了按平台区分的缺省，新增键帽字 keyLabel，formatHotkey 新增可选的第三个参数；Citation 新增 previewLinkSource / previewLinkDocument，API 新增 previewLinkText(item) 与 sourceMetaText(source)；Mention 新增空态文字 empty 与 API emptyText；Carousel、Sortable、Table 的读屏角色说明（aria-roledescription）可经 translations 翻译

  • 新增 Dialog 与 Drawer 的 unmountOnExit（缺省 true，行为不变）：设为 false 时打开过之后收起只隐藏、不卸载，再打开不重挂，内容里的组件状态、输入与滚动位置都保留；Web Components 写进 content 里 <template> 的内容按同一规则挂卸，Headless connect 新增 isContentMounted(present)

  • 新增 Select 的 lazyMount（缺省 false，行为不变）：列表内容第一次展开时才挂载，之后常驻；打开前的选中文字与收起态连打改按 collection 计算。300 个各带 20 个条目的 Select 挂载由约 530ms 降到约 183ms。Web Components 把条目写进 list 里的 <template>，第一次展开才克隆

  • 新增 Carousel 与 ImageViewer 的 size（sm / md / lg，缺省 md），翻页与播放钮同档，ImageViewer 的关闭钮比它低一档；Log、MessageFeed 的回到底部钮随组件已有的 size 换档。新增的 size 接全局配置

  • 新增 Carousel 分页点组件槽 --xh-carousel-indicator-thickness：垂直于轨道的粗细单独可调，缺省与 --xh-carousel-indicator-size 同值；调小即成细横条，粗指针下 44px 命中区不变

  • 新增 core 导出 SCOPE_CLASS_PREFIX、scopeClass() 与 stripScopeClass()；诊断码 portal.unreadable-stylesheet：文档里有读不到规则的跨域样式表时点名报出，给它加 crossorigin 并让来源回 Access-Control-Allow-Origin 即可恢复浮层样式同步的增量判断；Web Components 的 onXhConfigChange 新增可选的第二个参数 host，只接收它所在子树的配置变化

  • 修复 CartesianChart、PieChart、FunnelChart、RadarChart、GraphChart、HierarchyChart、SankeyChart 在根末尾追加的视觉隐藏数据表不再撑出祖先的滚动条，图表放进 overflow: auto 的卡片、面板、对话框正文时不再多出一截空滚动；新增部件 table-region（getTableRegionProps()），table 部件不再带隐藏样式

  • 修复 HierarchyChart 的绘图区补上读屏角色说明，取 translations.chartRoleDescription，缺省为 tree chart，与其余六种图表一致

  • 修复 CartesianChart 数据表的列名先取轴标题，全局配置里的 translations.keyLabel / valueLabel 不再盖掉作者写的轴标题；Heatmap 发散色阶的对照条两端恒写数值，translations.legendLow / legendHigh 只换顺序色阶两端的词

  • 修复 Citation 来源副文字里没有媒体类型的文档不再写死 Document，改取 translations.document

  • 修复 自绘滚动条在 disabled 时容器暂缺不再报「找不到滚动容器」诊断

  • 优化 模态浮层的背景失活改为只打 aria-hidden：四千多个节点的页面上打开、关闭模态抽屉不再各多出 40–55 毫秒的长任务；实时区域照常播报；没有遮罩的模态层在定位层里垫一块透明底板（data-xh-modal-underlay）拦下背景点击；背景失活随宿主提交当场施加与撤下，关闭后焦点不再晚两帧回到触发器

  • 优化 Vue 与 React 的 Portal 视觉桥只在浮层呈现期间存在：Tooltip、Popover、Select、DatePicker 等 19 种带退场闸门的浮层，以及菜单栏、侧栏与引用悬停卡常驻的定位层，关着时不建桥，展开时建、退场播完即撤；视觉桥按真正变了的自定义属性判断是否重算，模态浮层开合不再让全页浮层整批重算；滚动锁没让出宽度时不再往文档根写 0px

  • 优化 皮肤规则改以挂载类领头，挂在运行期状态后面的后代与兄弟规则主体带上组件特征：3500 个组件节点的容器上翻一次 data-state 由 150ms 降到 4ms，data-current、data-disabled 同量级下降

  • 优化 自绘滚动条首次测量按批读布局，粗指针探测全窗口共用一个媒体查询；Timestamp 的可见性监听与视口观察器全页共用；液态面协调器只在有液态成员时挂文档级监听

  • 优化 Web Components 的 <xh-config> 只改视觉轴（mode、brand、density 等）时不再通知元素重新接线，改 locale / size / 文案时只叫醒它子树里的元素

  • 调整 组件不再自带英文：界面文字一律取语言包，没配语言包时取 enUS，英文输出与此前逐字相同；带英文缺省的公开常量（CHART_TRANSLATIONS、HEATMAP_LEGEND_TEXT、SPINNER_DEFAULT_LABEL 等）名字与签名不变，值改取自英文语言包

  • 调整 浮动圆钮整体下移一档、每个角色节点另带挂载类 xh-scope-<组件名>、模态背景不再 inert，详见升级须知

v3.1.0 (2026-10-03) ​

本版补齐选择器的多选与表单字段接线：DatePicker、TimePicker、ColorPicker 多选时选中值在输入行里排成标签，与 Select 多选同一套；FloatButton 支持拖动与贴边，Menu 数据驱动支持多级，Tree 的连接线改为完整的树形连线；带清空钮的 15 个组件统一新增清空事件，组类控件直接放进表单字段也接上字段的标题与说明，并新增字段边界 FieldBoundary。另修复 Web Components 下 FloatButton、Marquee、Truncate、Watermark 盖掉作者写在 root 上的内联样式等问题。本版包含 TimePicker 与 ColorPicker 值类型的破坏性变更，按次版本发布，升级前请看下方升级须知。

升级须知

TimePicker

  • 值改为恒为 ISO 时间串数组：onValueChange / value-change 的 value、Vue update:value、api.value 由字符串改为 string[]，单选至多一项，还没填全时为空数组（此前是空串）；setValue 接收数组。宿主写入的 value / defaultValue 仍可写裸串，按一项处理。迁移：读值处取 value[0] ?? ''，写值处包一层数组

ColorPicker

  • 值改为恒为颜色串数组：onValueChange / value-change 的 value、Vue update:value、api.value 由字符串改为 string[]，单选恒为一项；setValue 接收数组。宿主写入的 value / defaultValue 仍可写裸串，按一项处理。触发钮色块与值文字显示的工作色改由新增的 api.color 读出。迁移：读值处取 value[0]，写值处包一层数组

  • 新增 多选成标签：DatePicker、TimePicker、ColorPicker 在 selectionMode="multiple" 下把选中值排成输入行里的标签，与 Select 多选同一套库内标签。新增 tag-list 部件与 Tag / TagLabel / OverflowTag / ItemDeleteTrigger 一组组件；点标签上的叉、或在展开钮（DatePicker 为日历钮）上按退格摘掉，超过 maxTagCount（默认 3）折进 +N，translations 新增 deleteItem / overflowTag；表单一个选中值一份同名隐藏输入；多选时段位收起。此前 DatePicker 多选只显示、只提交第一个日期

  • 新增 TimePicker 与 ColorPicker 多选：面板里调出的是草稿，按新部件 confirm-trigger（文字由作者写）收进值、浮层不收；快捷选项与预设色板点一下切换选中，maxSelected 限制个数

  • 新增 FloatButton 拖动与贴边：draggable（Web Components 为 button-draggable）打开后按住触发器拖到别处，松手按 snap（inline 缺省、block、nearest、none）贴边，甩一下贴到甩去的那一边；position / defaultPosition / onPositionChange（Vue v-model:position、Web Components position-change）以贴边比例 { edge, ratio } 或像素坐标 { x, y } 记位置，展开组恒朝页面中间长

  • 新增 Menu、ContextMenu、Menubar 数据驱动支持多级：节点写 children 即为子菜单入口，Vue / React 的默认树按 children 递归铺出，深度不限；Vue 的 XhContextMenuSub 与两端的 XhMenubarSub 新增 collection

  • 新增 带清空钮的 15 个组件统一新增清空事件（Headless / React onClear、Vue @clear、Web Components clear）：用户按清空钮清掉值时，在值变化之后派发；程序化的 clear()、Escape 清空与本来就空时按清空钮都不派发

  • 新增 字段边界 XhFieldBoundary（Web Components 为 <xh-field-boundary>）：子树里的库内控件不再继承外层字段的标签、说明、状态与控件 id；Vue / React 的浮层内容经 Portal 搬走后自动断开；Vue 另导出 clearFieldContext()

  • 新增 组类控件直接放进表单字段也接上字段的标题与说明：RadioGroup、CheckboxGroup、ColorSwatchPicker、ToggleGroup、Rating、Slider、PinInput 把字段标题并进名字链，说明与错误文案进描述链；Vue / React 新增 useFieldGroupWiring

  • 新增 DateField / DatePicker 的 placeholder 可写成一句整条占位，未填且未聚焦时显示、聚焦段位即换回；DatePicker 转发 placeholder，DateRangePicker 新增 startPlaceholder / endPlaceholder；新增组件槽 --xh-date-picker-placeholder-fg / --xh-date-range-picker-placeholder-fg

  • 新增 Table 列的 align（'start' | 'center' | 'end'）；列的 minWidth / maxWidth 参与布局，与 width 写成同一个数即为定宽列

  • 新增 Notification 正文限高：缺省 16rem（--xh-viewport-h-md），长文在正文里滚动，卡片不再被撑到整屏高；新增覆盖槽 --xh-notification-description-max-h

  • 新增 语义令牌 --xh-overlay-toast-w（28.75rem），toast 预设的卡宽改从它取值，像素不变

  • 新增 Carousel 开发期核对张数：渲染出来的条目比 slideCount 多时，经诊断通道报 carousel.slide-count-mismatch；core 新增诊断码 DIAGNOSTIC_CODES.carouselSlideCountMismatch

  • 修复 Web Components 下 FloatButton、Marquee、Truncate、Watermark 接线时整串写回 style，作者写在 root 上的内联样式被覆盖；现只写、只撤各自的内联自定义属性。Vue 的 XhTruncate 上作者写的 style、class 与监听器也改为与连接层逐条合并

  • 修复 Dialog 与 Drawer 未给 initialFocus 时，初始焦点越过关闭钮、拖动把手与改尺把手，落在内容里第一个可聚焦的控件上

  • 修复 Popconfirm 补上文档已列出的 disabled 与 dir：禁用时触发器转原生 disabled、点按不展开，dir 写在定位层上

  • 修复 RadioGroup 的方向键只接条目与根自身的按键，组里行内编辑控件的方向键不再被当成切换选项；RadioGroup、CheckboxGroup、ColorSwatchPicker 只在 label 部件真渲染时才输出 aria-labelledby，Vue / React 的 label 属性在手写选项时同样铺出标题

  • 修复 日期选择器与日期范围选择器的浮层尺寸只按 px 结算：根字号不是 16px 时，时间列不再比日历网格短，带时刻的面板不再把确认钮挤进滚动里；浮层上限缺省改为定位引擎算出的可用高度

  • 修复 紧凑密度写在局部容器上时，引用收紧尺寸的派生令牌（--xh-overlay-calendar-column-h 等）在 compact 边界上重新声明，局部紧凑子树里日期浮层的时间列与网格对齐

  • 修复 ImageViewer 放大后快甩越过边界时，越界量有上限、半秒内落定，不再冲出约 110px 露出视口底色

  • 调整 字段族控件（文本框、下拉、日期 / 时间族等 21 份皮肤）放进表单字段（Field）即铺满字段宽；单独摆放仍是 16rem 缺省宽，单类槽 --xh-<组件>-control-w 照旧优先，横排一行流的表单仍取缺省宽

  • 调整 Tree 的 lines 由每层一道竖线改为完整连接线：子节点从竖线横出接到行首，最后一个子节点止于行中线并拐向行首，展开着的分支沿整棵子树接到下一个兄弟；顶层节点不画线，强制色下取 GrayText

v3.0.0 (2026-09-29) ​

本版为主版本升级。主要变化：首发零依赖图表引擎 @xihan-ui/viz，并新增图表家族——直角坐标图 CartesianChart、饼图 PieChart、漏斗图 FunnelChart、雷达图 RadarChart、桑基图 SankeyChart、关系图 GraphChart、层级图 HierarchyChart 与迷你图 Sparkline，Heatmap 一并归入新的「图表」分类；另新增网格列表 GridList 与 AI 引用来源 Citation。四组组件合并：Toast 并入 Notification（preset="toast"）、Segmented 并入 RadioGroup（variant="segmented"）、IconWrapper 并入 Icon（frame）、GradientText 并入 Typography（variant="gradient"）。组件由 134 个增至 140 个（新增 10 个，并入删除 4 个），公开包由 17 个增至 18 个；日期族改用自研的 @xihan-ui/core/date，库包不再有运行时第三方依赖。视觉上新增墨色域、视觉环境的材质轴（liquid 导航层材质）以及加载环、选择卡片、标签行等家族配方；全库动效按角色取令牌，初始内容不播进场，减弱动效改为去掉位移、保留淡变。所有删除与更名均不保留别名、转发或兼容层，升级前请逐项看下方升级须知。

升级须知

以下按组件与包列出本版全部破坏性变更。引用已删除或改名的导出、组件会直接报错；CSS 选择器、组件槽与关键帧名失配不会报错，请在代码库中检索旧名。只经 Vue / React / Web Components 使用组件、不直接调用 Headless 的项目，可跳过「Headless」一组。完整的逐项对照表见各包随 npm 发布的 CHANGELOG.md。

Notification（Toast 并入）

  • Toast 整个组件删除，同一种「到期自行消失的消息」只保留 Notification，用 preset 区分：card（缺省）为两层卡片，toast 为一行操作结果；两种预设的缺省落位、条数、间距、时长、叠放与闲置暂停由 Headless 的 NOTIFICATION_PRESETS 统一给出，服务创建时均可改写
  • 服务：createToastService(options) 改为 createNotificationService({ preset: 'toast', ...options })（Vue、React 与 @xihan-ui/web-components/services 同样改法），句柄方法不变；ToastService / ToastServiceOptions / ToastCreateOptions / ToastMessageOptions / ToastPromiseOptions 改为对应的 Notification*，服务选项 toastTranslations 改为 translations
  • 组件：XhToastRoot 改为 XhNotificationItem 并写 preset="toast"，XhToastIndicator / Content / Title / Description / ActionTrigger / Progress / CloseTrigger 改为 XhNotificationItemIndicator 等同名后缀（React 的 XhToast*Props 同步），useToast / ToastContext 改为 useNotificationItem / NotificationItemContext（React useToastContext 改为 useNotificationItemContext），ToastRootSlotProps 改为 NotificationItemSlotProps；Web Components 的 <xh-toast> 改为 <xh-notification-item preset="toast">，作者节点的 data-xh-part 由 indicator / content / title / description / action-trigger / progress / close-trigger 改为加 item- 前缀；全局配置文案桶 translations.toast 改为 translations.notification。Vue 的 action 事件改为与另两端一样带 { id }；单独使用的轻提示条目缺省在页面转入后台时暂停计时，要回到旧行为写 pauseOnPageIdle={false}（Web Components pause-on-page-idle="false"）
  • 退场：Toast 与 Notification 删除固定退场窗口 removeDelay（Web Components 的 remove-delay、三端服务选项与 TOAST_REMOVE_DELAY），改为等退场动画播完再卸载；要调退场时长，覆盖 --xh-motion-duration-exit，或在 xihan.overrides 层改写卡片的 animation-duration
  • 样式：删除子路径 @xihan-ui/styles/toast.css，轻提示皮肤在 notification.css 的 [data-preset='toast'] 分支；[data-scope='toast'][data-part='root'] 改认 [data-scope='notification'][data-part='item'][data-preset='toast']，其余部件改认 item-<部件>；组件槽 --xh-toast-* 改为 --xh-notification-item-* / --xh-notification-*（如 --xh-toast-inline-size → --xh-notification-item-w、--xh-toast-icon-fg → --xh-notification-indicator-fg、--xh-toast-scale-collapsed → --xh-notification-stack-scale），叠放测量槽（--xh-toast-offset-collapsed、--xh-toast-height、--xh-toast-y 等）不再公开；叠放收拢比例改由新令牌 --xh-motion-scale-stack（缺省 0.95，减弱动效下为 1）逐层计算；关键帧 xh-toast-in / xh-toast-out 改为 xh-notification-stack-in / xh-notification-stack-out
  • Headless：toastMachine / ToastSchema / ToastApi / connectToast 改为 notificationItemMachine / NotificationItemSchema / NotificationItemApi / connectNotificationItem，toastAnatomy / toastKeyboard / toastMeta 改为 notificationAnatomy / notificationKeyboard / notificationMeta；TOAST_DURATION / TOAST_GAP / TOAST_MAX / TOAST_PLACEMENT 与 NOTIFICATION_GAP / NOTIFICATION_MAX / NOTIFICATION_PLACEMENT 改读 NOTIFICATION_PRESETS.<preset> 或 notificationPresetOf(preset)；resolveToastDuration(loading, duration) 改为 resolveNotificationDuration(loading, duration, preset)，resolveToastId 改为 resolveNotificationItemId；其余 Toast* 类型（如 ToastTone、ToastRecord、ToastTranslations）改为同名的 Notification*；机器事件 TOAST.* 改为 ITEM.*，getRootProps 等改为 getItemProps / getItem<部件>Props；删除 createToastStackController（含 scaleFactor 选项，叠放由 notificationMachine 的 stacked 接管）、resolveToastServiceItem / ResolvedToastServiceItem / ToastServiceDefaults 与 createFeedbackServiceController 的 idPrefix 选项
  • 声音：@xihan-ui/sound 的 withToastSoundService / ToastSoundServicePort / ToastSoundServiceOptions / ToastSoundKey 改为 withNotificationSoundService / NotificationSoundServicePort / NotificationSoundServiceOptions / NotificationSoundKey；@xihan-ui/vue/sound、@xihan-ui/react/sound 的 withToastSound / ToastSoundOptions 改为 withNotificationSound / NotificationSoundOptions，选项、声音映射与返回值不变

RadioGroup（Segmented 并入）

  • Segmented 删除：Headless 的 connectSegmented、segmentedMachine 等与全部 Segmented* 类型（含 resolveSegmentedIndicator、SegmentedBox）及 translations.segmented，三端的 XhSegmented*、useSegmented* 与 <xh-segmented>，@xihan-ui/styles/segmented.css 与全部 --xh-segmented-* 组件槽
  • 迁移：XhSegmentedRoot 改为 XhRadioGroupRoot variant="segmented"，collection、value、loop、block、tone、size 等原样沿用；XhSegmentedIndicator 改为 XhRadioGroupThumb（部件 thumb），XhSegmentedItemIcon / XhSegmentedItemText 改为 XhRadioGroupItemIcon / XhRadioGroupItemText；隐藏输入改为每个条目一份原生 radio，不再有整组的 hidden-input。Web Components 写 <xh-radio-group variant="segmented">，滑块写 data-xh-part="thumb"，条目用 <div data-xh-part="item"> 而不是 <button>。组件槽 --xh-segmented-bg / -border / -radius / -track-padding 改为 --xh-radio-group-track-*，--xh-segmented-item-* 改为 --xh-radio-group-segment-*，--xh-segmented-indicator-* 改为 --xh-radio-group-thumb-*，--xh-segmented-icon-size 改为 --xh-radio-group-icon-size
  • 键盘统一为 APG 单选组：segmented 形态按 Enter 不再选中，Home / End 不再跳到首末段；RadioGroup 未传 dir 时，左右方向键按祖先的书写方向翻转（此前缺省按 ltr）

Icon（IconWrapper 并入）

  • IconWrapper 删除：三端的 XhIconWrapper / XhIconWrapperProps / <xh-icon-wrapper> / XhIconWrapperElement，Headless 的 connectIconWrapper、iconWrapperAnatomy 等与 IconWrapper* 类型，@xihan-ui/styles/icon-wrapper.css，--xh-icon-wrapper-* 与 data-scope="icon-wrapper"
  • 迁移：底框改写在图标自己身上，variant 改名 frame：<XhIconWrapper variant="subtle" tone="brand" size="lg"><XhIcon :icon="FolderIcon" /></XhIconWrapper> 写成 <XhIcon :icon="FolderIcon" frame="subtle" tone="brand" size="lg" />；原先不写 variant 的中性淡底对应 frame="subtle"。组件槽 --xh-icon-wrapper-size / -glyph-size / -radius / -bg / -shadow 改为 --xh-icon-frame-*，--xh-icon-wrapper-fg 改为 --xh-icon-fg

Typography（GradientText 并入）

  • GradientText 删除：三端的 XhGradientText / XhGradientTextProps / <xh-gradient-text> / XhGradientTextElement，Headless 的 connectGradientText、gradientTextAnatomy 等与 GradientText* 类型，@xihan-ui/styles/gradient-text.css，--xh-gradient-text-from / -to 与 data-scope="gradient-text"
  • 迁移：渐变字写成 XhTypographyRoot 里的 XhTypographyText variant="gradient"；from / to / direction 改为 text 部件上的覆盖槽 --xh-typography-gradient-from / -to / -direction，走向取 CSS 写法（direction="to-bottom-right" 写成 to bottom right）。Web Components 写 <xh-typography> 内的 <span data-xh-part="text" variant="gradient">

其余组件

  • Anchor：滚动容器 scrollElement 改名 target，与 Affix、BackTop 一致（Vue :target="el"，React target={() => ref.current}，Web Components 的 property el.target）；Headless refs getScrollEl 改为 getTargetEl
  • Cascader：浮层按内容定宽，不再随字段盒拉伸，改锚在字段盒上；材质由 frosted 改为实体的 floating 面；--xh-cascader-content-max-w 缺省改为不封顶，新增下界 --xh-cascader-content-min-w。删除组件槽 --xh-cascader-content-backdrop、--xh-cascader-content-highlight、--xh-cascader-loading-min-w、--xh-cascader-empty-min-h、--xh-cascader-loading-min-h 与 --xh-cascader-input-py（搜索框高度改由 --xh-cascader-input-h 给）
  • DownloadTrigger：删除关键帧 xh-download-trigger-content-hide，在途时文字的隐去改由过渡承担
  • EmptyState：页面首屏就在的空状态不再播放开幕，皮肤的开幕关键帧只写在 :not([data-instant]) 下；React 的 EmptyStateContext 新增 rootRef，自行渲染根节点时要把它接到根元素上
  • ImageViewer：删除 --xh-image-viewer-loading-size、--xh-image-viewer-loading-radius、--xh-image-viewer-loading-bg（取图占位面改为加载环，尺寸由新增的 --xh-image-viewer-status-size 给）
  • LoadingBar：收尾改为等真实的淡出过渡播完；fadeDuration 的含义改为淡出时长（写进 --xh-loading-bar-fade，不给时取 --xh-motion-duration-exit，此前缺省 200ms）；删除 LOADING_BAR_FADE_DURATION，resolveLoadingBarFadeDuration 未给或非有限时返回 undefined；机器事件 after.fadeDuration 改名 FADE.DONE
  • Marquee：pauseOnHover 缺省由关改为开，要关掉写 pauseOnHover={false}（Web Components pause-on-hover="false"）；paused 改为受控属性，给了它时暂停开关只发出 onPausedChange（Vue update:paused，Web Components paused-change），需由作者写回
  • NumberAnimation：easing 改按 CSS 缓动函数解读，"ease-out" 这类写法由匀速改为按 CSS 曲线播放，认不出的写法在起跑时报错，要匀速写 linear；不写 duration / easing 时，缺省节奏由线性 1000ms 改为按数值角色取令牌（首次滚动取 --xh-motion-duration-reveal，换目标取 --xh-motion-duration-morph），首次滚动时不在视口里的停在起点；删除导出 NUMBER_ANIMATION_DURATION 与 resolveNumberAnimationDuration，要固定节奏照旧写 duration
  • Progress / LoadingBar / FileUpload：填充改为铺满轨道、按比例平移，range 不再写内联 inline-size，改写私有槽 --xh-_progress-value / --xh-_loading-bar-value（0–1）；自带整套皮肤的项目改读这两个槽。Notification 倒计时条改为裁切收起，共享关键帧 xh-countdown 随之改写
  • SideNav：分组改为合法的列表结构：group 不再输出 role="group" / aria-labelledby，新增部件 group-list（Vue / React XhSideNavGroupList，Web Components <ul data-xh-part="group-list">，Headless getGroupListProps({ value })）。在每个分组里把 group-label 之后的条目包进一层 group-list；依赖 [data-part='group'][role='group'] 的样式或测试改认 [data-part='group-list']
  • Table：删除关键帧 xh-table-loading-pulse（空表取数改为加载环），--xh-table-loading-duration 改为环转一圈的时长，--xh-table-state-min-h 缺省由 8rem 改为 0
  • Tabs / Anchor / NavigationMenu：指示条改为量排布位、以 transform 摆放；Anchor 与 NavigationMenu 的连接层不再写内联的 inset-* 与尺寸，改写私有槽 --xh-_anchor-indicator-x / -y / -w / -h 与 --xh-_navigation-menu-indicator-x / -y / -w / -h，自带整套皮肤的项目改读这些槽
  • TimePicker / TimeRangePicker：删除 step，改为按单位的 timeStep: { hour?, minute?, second? }：step={15} 改为 timeStep 传 { minute: 15 }（Vue :time-step="{ minute: 15 }"，Web Components 属性 step 改为 time-step='{"minute":15}'），api 的 step 改为 timeStep。isTimeUnavailable 改为 (value, unit, context)：时列的 value 恒按 24 小时制给出（12 小时制下按显示值判定的改按 24 小时制），context 带已选的时与分；TimeRangePicker 原第三个参数 index 挪进 context.index，写成 (value, unit, { index }) => …
  • Timestamp：用词与缺省日期写法改由 Intl.RelativeTimeFormat / Intl.DateTimeFormat 按 locale 给出，显示文本随之变化（如英文 datetime 为 08/11/2026, 09:30:05，中文相对说法为 30分钟前，一分钟以内为该语言的「现在」）；相对说法认将来时刻（5分钟后），离现在三十天及以上才退回绝对日期；相对型不给 now 时自动刷新。依赖旧文案的快照与断言需更新
  • Truncate：开了 expandable 后文字盒子（root）不再是按钮，不再带 role="button"、tabindex、aria-expanded，点文字或在文字上按 Enter / Space 不再展开；展开改由 root 之后的原生按钮部件 trigger 承担。Vue / React 自动铺出这颗按钮（Vue 设 inheritAttrs: false，透传属性落在文字盒子上）；Web Components 需在 root 旁写一个 <button data-xh-part="trigger">

Headless

  • Badge、EmptyState、Marquee、Skeleton、Spinner、Timestamp、Watermark 改由状态机驱动：connectX(props, normalize) 改为 connectX(service, normalize)，先用对应的 badgeMachine、emptyStateMachine、marqueeMachine、skeletonMachine、spinnerMachine、timestampMachine、watermarkMachine 建服务再连接；三端组件除上方已列出的变化外用法不变
  • 日期族改用 @xihan-ui/core/date：buildWeekDays、buildPeriodGrid、calendarPeriodOf、calendarPeriodValue 删除 timeZone 选项（日历只按日期字段格式化，组件的 timeZone prop 不变）；删除导出 parseCalendarDate（改用 PlainDate.from(v)，非法串抛 RangeError）、isoWeekNumber / isoWeekYear（改用 PlainDate.from(v).weekOfYear / .yearOfWeek）、isoWeekStart（改用 fromIsoWeek(year, week)）、isoWeeksInYear（改用 @xihan-ui/core/date 的同名函数），以及 calendarHeadingPieces、calendarPeriodStart、calendarWeekListedIn、isoWeekOf、blocksToDate、parseTimeValue、draftFromTime、timeFromDraft 与类型 CalendarHeadingPieces
  • 时间列算子收为共享的一份：删除 timePickerColumns、timePickerColumnsFor、timePickerItemValue、TIME_PICKER_STEP 与 TimePickerColumnsOptions，改用 timeColumns、timeColumnsFor、timeItemValue 与 TimeColumnsOptions（入参 step: number 改为 timeStep: TimeStep）；resolveTimeStep 的入参改为 TimeStep、返回三个单位的步进，resolveTimeStep(15) 写成 resolveTimeStep({ minute: 15 }).minute
  • ColorPicker：ColorPickerServices 新增必填的 recentSwatchPicker，自行组装服务表的调用方用 colorPickerRecentSwatchPickerProps 再建一台色块选择器补上；colorPickerMeta.requiredParts 去掉 trigger（常驻形态不写触发器）
  • Timestamp：formatRelativeTime 的 locale 改为必填，将来的时刻不再返回 undefined

样式与令牌（@xihan-ui/styles、@xihan-ui/tokens）

  • 循环动画的周期令牌改名，旧名不再输出：--xh-spin-duration → --xh-motion-loop-spin、--xh-caret-duration → --xh-motion-loop-caret、--xh-shimmer-duration → --xh-motion-loop-shimmer，取值不变；tokens.json、tokens 对象与 TokenName 类型同样只有新名
  • 组件私有的关键帧并入共享关键帧（@xihan-ui/styles/motion.css），旧名删除：各组件的旋转（xh-spinner-rotate、xh-popconfirm-rotate、xh-switch-rotate、xh-toast-spin、xh-approval-rotate、xh-clipboard-rotate、xh-download-trigger-rotate、xh-notification-spin）→ xh-spin；xh-reasoning-shimmer、xh-tool-call-shimmer、xh-skeleton-shimmer → xh-shimmer；xh-approval-in、xh-message-feed-item-in、xh-question-flow-in、xh-tool-call-enter → xh-item-in；xh-approval-result-in、xh-message-feed-button-in、xh-question-flow-result-in、xh-log-button-in → xh-pop-in；xh-reasoning-fade-in、xh-clipboard-loading-reveal、xh-download-trigger-loading-reveal → xh-fade-in；xh-clipboard-loading-hide → xh-fade-out；xh-diff-view-reveal、xh-form-summary-enter → xh-drop-in；xh-dialog-in / -out、xh-notification-in / -out → xh-sheet-in / xh-sheet-out；xh-drawer-in-* / xh-drawer-out-*（四个方向）→ xh-slide-in / xh-slide-out。在 xihan.overrides 层重定义过旧名的改为重定义新名，新名跨组件共享，只想换一个组件的动画就改写该部件的 animation-name

@xihan-ui/core

  • 删除 RuntimeConfig.reducedMotion 与 createRuntimeConfig 的同名选项：减弱动效改按元素所在的作用域判断，容器上的 data-motion 对 JS 驱动的滚动同样生效；要强制减弱动效，在容器上写 data-motion="reduce" 或调用 setMotionOverride('reduce')
  • createPresence 删除 config 选项，调用处去掉即可；减弱动效下 Presence 照样等退场动画播完，浮层、对话框、抽屉等先以 120ms 淡出再卸载，不再瞬时消失

@xihan-ui/motion

  • 缓动表删除 decelerate 与 accelerate（EasingName 随之少了这两个名字），分别改写为 'cubic-bezier(0, 0, 0, 1)' 与 'cubic-bezier(0.3, 0, 1, 1)'
  • resolveEasing 认不出写法时抛 TypeError，不再退回线性；新认下 ease / ease-in / ease-out / ease-in-out、step-start / step-end、steps() 与 linear()。此前写成 'ease-out' 一类、实际按匀速播放的，现在按 CSS 曲线播放，要匀速写 'linear'，要库里的曲线写命名缓动 'easeOut'；越界的 cubic-bezier()、带单位的分量与非字符串一律报错，tweenValueAt 规则相同。来自配置或后端的缓动串请在入口处用 resolveEasing 校验

@xihan-ui/animations

  • 预设改取动效令牌：fade 取 200ms（原 240ms），带位移的淡入、缩放与模糊取 320ms、位移 16px（原 12px），rise / drop-in / spin-in 取 520ms、位移 24px 与强调曲线，注意类统一取 640ms（原 520–900ms）；playAll 缺省间隔由 60ms 改为 40ms
  • 删除 clampSpec，新增 validateMotionSpec：越界配方不再被悄悄钳住，play / playAll 校验不通过时同步抛 RangeError（缓动写法不合法抛 TypeError）且不起播；任意一秒内闪烁超过三次同样拒播；createMotionPlayer 的 speed 不在 (0, 100] 内、playAll 的 stagger 为负或非有限时抛错。原先依赖钳制的配方先用 validateMotionSpec 找出越界字段；要保持旧节奏，给 play 传 duration、给 playAll 传 stagger: 60

缺省值与外观

以下变化不删改 API，但升级后画面或行为会不同：

  • 减弱动效改为去掉位移、保留淡变：--xh-motion-duration-micro / -enter / -exit 在减弱档由 1ms 改为 120ms。把几何变化（位移、缩放、尺寸）挂在这三个时长上的自定义样式，改用 --xh-motion-duration-move / -nudge / -expand / -collapse 等几何时长；--xh-motion-duration-nudge 由 200ms 改为 120ms
  • 缺省主题的描边与淡底令牌（--xh-border-default / -subtle / -strong / -control-hover，--xh-bg-subtle / -subtle-hover / -subtle-active，--xh-bg-muted）改为半透明墨色，缺省面上的对比度不变；拿它们当遮盖底（吸顶条、叠层）的自定义样式改用新增的不透明档 --xh-bg-subtle-opaque、--xh-bg-subtle-hover-opaque、--xh-bg-subtle-active-opaque、--xh-bg-muted-opaque、--xh-border-default-opaque
  • Select、Combobox、TreeSelect 的候选面板改为与字段盒等宽，长选项在条目里截断；需要面板按内容撑宽的，改写 --xh-select-content-min-w 等对应的 --xh-<组件>-content-min-w
  • Select、Combobox、TreeSelect 只传 collection 的自动结构在 multiple 下改为标签行，缺省最多显示 3 枚，其余折叠为 +N（maxTagCount 可调）
  • Reasoning 缺省 variant / size 由 subtle / sm 改为 outline / md，要保持原样显式写回；CodeView、DiffView 缺省字号由 sm 档改为 md 档（写 size="sm" 保持原样）；Log 行高由 1.25rem 改为 1.5rem（--xh-log-line-height 可改回）
  • SideNav 宽度改读侧栏令牌，折叠宽由 56px 改为 64px（写 --xh-side-nav-collapsed-w: 56px 保持原样），当前项不再加粗；Layout 侧栏里放 SideNav 时内衬缺省为 0
  • Badge md / lg 计数盒由 28 / 32px 收为 20 / 24px；Spinner md / lg 直径由 24 / 32px 改为 20 / 24px
  • NumberAnimation 改用 Intl.NumberFormat 输出，缺省按浏览器语言格式化（部分语言的小数点与数字系统会变），要固定写法写 locale="en-US"；Marquee 的 speed 改按实测内容长度换算为真正的每秒像素数，未写 --xh-marquee-span 的滚速会变
  • DatePicker 的 showTime 小时制缺省改按 locale 推断，传了 12 小时制地区（如 en-US）时多出上下午列，写 hourCycle={24} 保持原样
  • Tooltip 新增接替窗口 skipDelayDuration（缺省 300ms）：一个提示开着或刚收起时，指向下一个直接接替、不再等待也不播进场；要回到旧行为写 skipDelayDuration={0}
  • Tour 当前步的目标取不到时先不露面、等它出现，等满 targetTimeout（缺省 3000ms）仍没有才按居中呈现（此前立即居中）；要回到旧行为写 targetTimeout={0}
  • Heatmap 缺省播放填色动画（写 animated={false} 关闭）；数据含负数且未写 scale 时缺省按发散色阶（写 scale="sequential" 保持原口径）；palette 的 green / blue / orange / red 改取基础色板同名色相，要回到语气色写 tone

升级时最容易漏的几处

  • 删掉或改了名的属性不会报错：Vue 与 Web Components 把它当成原生属性透传到根元素上，写了等于没写。Vue 项目建议开启 vue-tsc 的 checkUnknownProps 与 checkUnknownEvents 一次扫出来，透传的原生属性（id、title、aria-*）按 Vue 适配器 · 原生属性透传与严格模板检查 放行
  • Select 只负责从固定选项里选，不带输入筛选与远程搜索；要边输入边筛选改用 Combobox，它只负责呈现，筛选结果与输入框里的文字由调用方掌管
  • ImageViewer 的图片经 collection 传入，没给时打开只有工具条与空视口
  • Button 的加载态与文字分别放进 XhButtonIndicator / XhButtonLabel；纯图标按钮要写 iconOnly（Vue 模板里 icon-only）并自带可及名
  • Switch、Checkbox 的文字写进默认插槽才接得上可及名，写在组件外面的文字不会成为它的名字
  • SideNav 的 item 部件必须写，链接条目要带 href：回车激活走浏览器原生的链接行为
  • 合并与改名再提一次：轻提示并入通知（preset="toast"），分段控件并入单选组（variant="segmented"），令牌 --xh-shimmer-duration 改名 --xh-motion-loop-shimmer

  • 新增 @xihan-ui/viz：零运行时依赖、不碰 DOM 的图表引擎，以纯函数提供比例尺、刻度与时间间隔、统计与分箱、形状与曲线、坐标轴布局、场景与过渡、几何拾取、降采样、数字与时间格式、文字折行、颜色换算与色板校验，以及无障碍摘要与数据表模型；关系、层级、桑基布局与列式大数据工具放在子入口 @xihan-ui/viz/graph、/hierarchy、/sankey、/columns、/canvas，不用不计体积；非法输入抛 VizError。Headless 与三个适配器已依赖它，无需单独安装

  • 新增 8 个图表组件，三端同时提供：CartesianChart（直角坐标图）、PieChart（饼图）、FunnelChart（漏斗图）、RadarChart（雷达图）、SankeyChart（桑基图）、GraphChart（关系图）、HierarchyChart（层级图）、Sparkline（迷你图）；皮肤子路径 @xihan-ui/styles/cartesian-chart.css 等随组件提供

  • 新增 CartesianChart 以 mark 组合画法：柱（分组、堆叠、百分比、浮柱、棒棒糖与哑铃、直方图、waterfall 瀑布）、折线与面积（区间带、stackOffset 流图）、scatter 散点与气泡（color 按值着色，配 palette 与色阶图例）、candlestick K 线、boxplot 箱线与小提琴；横竖两向，比例尺按数据推断，另可选 sqrt / pow / symlog 与时间轴 timeZone

  • 新增 CartesianChart 读数辅助：数据标签 labels、堆叠合计 totals、线尾标签 endLabel；annotations 画参考线、参考带、极值与指定点标注、平均线、趋势线与移动平均；提示框缺省列出同一位置的全部系列，tooltipOrder 可按数值排序

  • 新增 CartesianChart 缩放与刷选：zoom 支持 Ctrl / ⌘ 滚轮、拖动平移、双指捏合与 + / − 键，带缩略线缩放条，受控 window / onWindowChange 让多图联动；brush 用拖动或 Shift + 方向键刷选，onBrushSelectionChange 给出范围与框内数据

  • 新增 CartesianChart 大数据与实时数据：renderer 取 svg / canvas / auto，auto 在标记超过 3000 个时数据层改用画布，键盘、读屏、主题、强制色与打印不受影响；data 可传 createColumnStore 建的列式数据仓，百万点经降采样仍流畅；多次追加合并到同一帧刷新，follow 让窗口随新数据右移；xAxis.ordinal 跳过休市，yAxis.fit: 'window' 按窗口内数据取值域，坐标轴 minSize 让上下叠放的图对齐

  • 新增 PieChart 缺省为环形，中心显示合计并跟随激活的扇区，另有实心饼、sweep="half" 半环与 rose 玫瑰图，超过 maxSlices 的小扇区并为「其他」，labelContent 定制标签；FunnelChart 以 conversion 标出逐级或相对首级的转化率，可画成金字塔；RadarChart 比较 3–10 个 indicators，rings / ringLabels 调圈数并标值；SankeyChart 可横排或竖排，流带按 linkColor 取源色、目标色或渐变

  • 新增 GraphChart 提供 force、circular、tree、radial-tree、preset 五种 layout，可拖动节点（draggableNodes）、给连线写 label，zoom 打开平移缩放，受控 view 让多图同步；HierarchyChart 提供矩形树图、旭日图、冰柱图与打包圆，点击或 Enter 逐层下钻（受控 rootKey），colorBy="value" 时每层一条色阶图例；Sparkline 提供折线、面积、柱与盈亏四种 variant，以及 markers、正常区间 band 与目标线 reference

  • 新增 图表共通能力：pending 且还没有数据时空态显示加载环与 loadingText，取完仍无数据才显示 emptyText；animated（缺省开）播放入场与更新过渡，数据更新与图例切换从原位插值，数值标签从旧值滚到新值，减弱动效下只保留淡变；受控 hiddenSeries / activeKey 让多图联动，onDatumActive / onDatumPress 报告悬停与按下的数据

  • 新增 图表无障碍：绘图区只占一个 Tab 位，方向键在数据之间移动，根内自动生成视觉隐藏的摘要与数据表；同一份表格模型以 table 交出（Vue 作用域插槽、React 函数式 children、Web Components 只读属性），可直接交给 Table 做可见的表格视图；数据或配置有误时经诊断通道报 chart.* 诊断码

  • 新增 图表配色与皮肤：--xh-chart-* 令牌提供亮暗两套分类色 1–8（经对比度与色弱区分度校验）、有序 / 顺序 / 发散色阶、涨跌色 --xh-chart-rise / --xh-chart-fall（缺省绿涨红跌，可覆盖）以及网格、轴线色与几何度量；强制色与打印下自动改用纹理与线型区分系列，祖先写 data-xh-chart-patterns 也可开启；图表共用部件的皮肤收为家族配方 @xihan-ui/styles/chart.css

  • 新增 Heatmap 发散色阶 scale="diverging"（以 midpoint 为界）与按确切比例着色的 continuous；onCellPress（Web Components cell-press）报告点击或按 Enter 的格子；animated 入场时按日期顺序扫过填色，数据变化时各格渐变到新档；悬停时详情条所指的格子描边高亮

  • 新增 GridList 网格列表：可选择的行、行主操作与独立的行内按钮，支持单选、多选（含 Shift 范围选）、方向键与连打检索，可与 Sortable 组合拖动排序，空态与加载态带加载环

  • 新增 Citation 引用来源：行内引用编号、来源预览与来源列表，方向键导航并带完整的可及关系；sources 与 @xihan-ui/chat-stream 的 SourcePart[] 同形；预览缺省在正文内展开收起，previewMode="hover" 改为锚在编号旁的悬停卡片（openDelay / closeDelay / placement / offset），一处引用对应多个来源时写 sourceIds 在预览里轮换

  • 新增 子入口 @xihan-ui/core/date：Temporal 形的 PlainDate / PlainTime / PlainDateTime 与毫秒精度的 ZonedDateTime，提供公历加减、差值与取整，夏令时跳过或重复的时刻按 disambiguation 取舍；按地区划分的周（CLDR 48）、月 / 季 / 年边界与 ISO 周反查（fromIsoWeek）；IANA 时区的规范化与枚举；与时区无关的格式化器 createDateFormatter

  • 新增 动效令牌按角色补齐：几何时长 --xh-motion-duration-move / -expand / -collapse，整幅位移 --xh-motion-travel 与 --xh-motion-travel-opacity，数据动效 -reveal / -morph，表现性的 -attention、--xh-motion-distance-lg、--xh-motion-ease-emphasis，交互光 --xh-motion-duration-glint，呼吸 --xh-motion-loop-breathe，挤压下限 --xh-motion-scale-squash，以及弹簧预设 --xh-motion-spring-<名>-stiffness / -damping；@xihan-ui/styles/motion.css 新增共享关键帧 xh-item-in、xh-drop-in、xh-sheet-in / -out、xh-slide-in / -out、xh-slide-fade-in / -out、xh-shimmer、xh-breathe

  • 新增 @xihan-ui/motion 与令牌同源：readMotion(el) 按元素读取实际生效的时长与缓动（组件槽覆盖、局部 data-motion 与系统偏好都已算进），motionDurations / motionEasings / motionDistances / motionStaggerStep 是读不到样式时的同值常量，resolveMotionPreference 接受元素；新增可中途改目标、承接松手速度的弹簧 createSpringValue 与手势松手工具 rubberBand / rubberClamp / projectRelease / nearestSnap / glideSpring；@xihan-ui/pointer 单指与多指会话的 onEnd 带出松手速度 velocity

  • 新增 Core 行为原语：trackArrivals（新到的条目按顺序错开进场，首屏已有的直接呈现）、trackListMotion（接住条目的离场与换位）、trackReorder（宿主重排后补偿换位）、trackAppearance（首屏不播进场）、glideBy / glideFrom；createFocusScope 的返回值新增 returnFocus() / reactivate()，PresenceHandle 新增 onReenter；悬停意图的缺省时长导出为 HOVER_INTENT_OPEN_DELAY / HOVER_INTENT_CLOSE_DELAY

  • 新增 墨色域：彩色区块写 data-xh-ink="dark" / "light"，或配合 --xh-ink-surface 写 "auto" 按底色亮度自动选；域内的描边、分隔、淡底与交互阶梯取墨色按比例透明，正文、焦点环与主要动作取墨色本身，在黄、绿、橙等彩色底上描边的显著度保持一致；data-xh-ink-margin="ample" 让次要文字取墨色 72%。实心按钮、实心 Tag 与 Tooltip 里的快捷键、分隔和小徽标随之按所在底色取墨色

  • 新增 视觉环境第八轴 material（standard / liquid），经 setPreference({ material: 'liquid' })、<xh-config material> 或 Vue provideXhConfig 的 initial.material 设置，Portal 会带到浮层。liquid 档下导航层换成液态面（--xh-material-liquid-*，共享层 @xihan-ui/styles/liquid.css）：按下层深浅自动换色调与通透档（可用 data-xh-backdrop 声明下层）、按住时鼓出形变、同组块相近时粘连成片；覆盖 FloatButton 与展开组、BackTop、Layout 固定顶栏、Carousel 控制钮与分页、ImageViewer 工具条、MessageFeed 与 Log 的回到底部钮，实心 Button 与可交互 Card 悬停时描边扫过一道交互光，RadioGroup segmented、Tabs、Anchor、NavigationMenu 的指示器两沿由弹簧驱动。高对比、减少透明、强制色、打印与减弱动效下各有替代外观，standard 档外观不变

  • 新增 家族配方：@xihan-ui/styles/material.css 统一绘制 frosted 面（覆盖槽 --xh-frosted-bg / -border / -fg / -shadow / -backdrop / -highlight），12 个浮层与各浮动钮改由它提供材质与交互阶梯；@xihan-ui/styles/loading-ring.css 统一加载环画法，另有压在动作钮上、钮宽不变的一档；@xihan-ui/styles/tag-list.css 统一多选控件的已选标签行（只缩不涨、逐枚截断、+N 始终完整）；@xihan-ui/styles/choice-card.css 提供选择卡片；勾选标记配方让 Checkbox、CheckboxGroup、Transfer、Table、QuestionFlow 的勾与半选杠常驻并随状态淡变

  • 新增 方向与布局令牌：书写方向符号 --xh-direction-sign（ltr 为 1、rtl 为 -1）与行内起止缘 --xh-direction-start / --xh-direction-end，随就近的 dir 继承；侧栏宽 --xh-sider-w（15rem）/ --xh-sider-collapsed-w（4rem），Layout 与 SideNav 缺省读取；字段盒内输入框最小宽 --xh-control-input-min-w

  • 新增 虚拟滚动接入：Tree、Listbox、Select、Combobox、TreeSelect、Table、Log 新增 virtualizer，Transfer 新增按侧设置的 virtualizers，接入后只渲染窗口内的行，键盘、检索、选择与 ARIA 位置仍按完整集合计算；Virtualizer 新增随整页滚动（scrollContainer: 'window'）、贴底锚定（anchor: 'end'）与吸顶分组标题（stickyIndices），增删条目时视口不跳；InfiniteScroll 新增 edge="start" 向前加载；ScrollArea 新增 scrollTo() 与 scroll-change / reach-end 事件

  • 新增 Collapsible、Accordion 与 Tabs 的 lazyMount（第一次展开或选中时才挂载内容）与 unmountOnExit（收起或选走后卸载），Web Components 把内容写在面板内的 <template> 里按需克隆

  • 新增 Dialog 的 draggable（Web Components panel-draggable）：按住标题栏拖动面板，新增 drag-trigger 部件供键盘挪位与回中；Drawer 的 resizable：新增 resize-trigger 部件，拖动或用方向键调整面板厚度，范围由 minPanelSize / maxPanelSize 限定，支持受控 panelSize

  • 新增 Tabs 与 Toolbar 的「更多」下拉：放一枚 overflow-trigger 部件，宽度不够时自动出现，Tabs 列出可见区外的标签，Toolbar 把放不下的条目收进菜单；Tabs 另新增 close-trigger 部件，指针与触屏也能关闭标签

  • 新增 Menu、ContextMenu、Menubar 的选择型条目 CheckboxItem、RadioGroup、RadioItem（如 XhMenuCheckboxItem），支持受控 checkboxValue / radioValue 与逐条 closeOnSelect，缺省选中后不关闭菜单；ContextMenu 新增整张菜单的 disabled

  • 新增 导航：NavigationMenu 面板条目可再带一层子级（NavigationMenuNode.children，部件 branch-trigger / branch-indicator / branch-content）；Breadcrumb 新增 ellipsis-trigger 部件，折叠位可用键盘与读屏就地展开完整路径；Pagination 新增 first-trigger / last-trigger 部件与整组 disabled；SideNav 新增搜索过滤（input / empty 部件与 filter）与图标栏名称提示 XhSideNavTooltip；XhBreadcrumbLink、XhNavigationMenuLink、XhSideNavLink 支持 asChild，可直接借用路由链接渲染

  • 新增 Tooltip 的接替窗口 skipDelayDuration（缺省 300ms，相邻提示直接接替），XhTooltipProvider（Web Components <xh-tooltip-provider>）把子树里的提示编成一组并提供组级延时缺省，followCursor 让提示跟随指针；Popover 新增 disabled；Tour 步骤的 target 可传元素或返回元素的函数，目标未挂载时等它出现，超过 targetTimeout（缺省 3000ms）仍未出现则该步居中呈现

  • 新增 Alert 的 banner：页面顶部横幅，贴边铺满整行，只在朝向内容的一侧画描边；Notification 缺省的卡片预设也可用 loading() 与 promise() 以加载态弹出并随 Promise 落定改写；Notification 的叠放 stacked 由轻提示专有改为两种预设通用

  • 新增 日期与时间：CalendarPicker、CalendarRangePicker、DatePicker、DateRangePicker 新增 firstDayOfWeek；CalendarPicker、DatePicker 新增多选上限 maxSelected；CalendarRangePicker 新增 activeIndex；DateField 新增 hourCycle（12 小时制多出上下午段）；DateRangePicker 新增一体化时间 showTime，起止各一组时间列，由 confirm-trigger 收口；DatePicker 与 DateRangePicker 的时间列支持 hourCycle、按单位的 timeStep 与带上下文的 isTimeUnavailable，min / max 可以带时刻，同一天界外的时刻不可选

  • 新增 选择类：Combobox、TreeSelect、Cascader 多选时已选项排成标签（tag-list 部件与 maxTagCount），与 Select 一致；TreeSelect 新增浮层内搜索 searchable（input 部件与 filter）；Cascader 新增自定义匹配 filter 与懒加载分支（节点写 hasChildren，由 loadChildren 取子项，列末显示加载、失败与重试）；Transfer 新增分页 pageSize，全选与计数仍按整侧计算

  • 新增 CheckboxGroup、RadioGroup 的卡片形态 variant="card" 与说明行部件 item-description；CheckboxGroup 新增选中数上下限 min / max；RadioGroup 新增 variant="segmented"、loop、block 与条目图标部件 item-icon

  • 新增 Form 字段级接口 dirty、isFieldDirty、isFieldTouched、resetField，不提交的校验 validateAll / validateField / validateFields，规则可写 deps 联动重校；onSubmit 可返回 Promise，落定前表单处于忙态、不能重复提交，失败经 onSubmitError 报出；FieldArray 新增 insert(index, item?)，Web Components 补齐 add、insert、removeItem、move 等命令式方法

  • 新增 FileUpload 的粘贴上传 allowPaste（缺省开）、准入判定 validate、并发上限 maxConcurrentUploads（超出的排队，状态 queued）与保留文件的 cancelUpload（状态 canceled）；TagsInput 新增准入判定 validate 与拒收事件 onTagReject，delimiter 可传一组断词符

  • 新增 Slider 的反向 inverted、整段拖动 draggableRange 与 trackFill；NumberField 长按加减逐步加速（下限 minChangeInterval），新增 clampValueOnBlur 与越界状态 outOfRange；Switch 的滑块可以横向拖动切换

  • 新增 颜色：ColorPicker、ColorField、ColorSlider 支持 oklch 值串（format="oklch"）；ColorPicker 输入盒接入字段外壳并新增 variant（outline / subtle / ghost）；ColorPicker 新增常驻形态 inline（取色面直接铺在页面里）与最近使用色（recentColors / defaultRecentColors / maxRecentColors、onRecentColorsChange，部件 recent-swatch-picker）

  • 新增 Mention 支持多行正文（input 部件写 as="textarea"），插入的引用按整体删除，新增 mentions；ImageCropper 新增水平 / 垂直翻转（flip、flip-trigger 部件）与按所见出图的 toCanvas()；SignaturePad 新增签名数据 value / defaultValue / onValueChange，可无损回显并续写，另有撤销 / 重做部件 undo-trigger / redo-trigger

  • 新增 Table 的单元格合并 cellSpan、列定义 children 表头分组、树形表级联勾选 cascade 与 checkedStrategy；冻结列不再要求数字宽度，横向滚动压住内容时冻结列边缘出现描边提示；Tree 新增尺寸档 size、缩进参考线 lines 与节点级加载态 loadingValue

  • 新增 Steps 的点状形态 variant="dot"、当前步进度环 percent 与只读展示 readOnly；Progress 在 semantics="meter" 下支持 thresholds 分段色带、target 目标刻度、scale 量程刻度与 indicator="needle" 指针（仪表盘、子弹图），线形新增 steps 分格、striped 条纹与 buffer 缓冲段

  • 新增 Carousel 的 effect="fade" 淡变换页，滚出可视区或页面转入后台时自动播放暂停（pausedBy 新增 visibility）；Sortable 跨列表拖放：写同一 group（各列表另写 listId）的列表之间可用指针或键盘搬移条目，落进别的列表时触发 transfer

  • 新增 Card 的整卡可点形态 interactive（新部件 trigger 承载链接或按钮）；Descriptions 新增 header / title / extra；Flex 的 orientation / align / justify / gap 接受断点对象；Grid 格子新增跨行 rowSpan

  • 新增 通用与展示：Icon 新增圆形底框 frame（solid / subtle / outline / ghost，覆盖槽 --xh-icon-frame-*）；Typography 新增渐变字 variant="gradient" 与行内 strikethrough / underline / mark；Truncate 新增中间省略 position="middle" 与展开按钮文案 translations；Spinner 新增 delay，等够时长才露面；Badge 新增呼吸圆点 pulse 与偏移槽 --xh-badge-offset-inline / --xh-badge-offset-block；Marquee 新增暂停开关部件 autoplay-trigger、defaultPaused / onPausedChange 与两端渐隐 fade；NumberAnimation 新增 locale 与 formatOptions（货币、百分比、单位、紧凑记数）；JsonViewer 新增 search，高亮命中并逐个跳转

  • 新增 Timestamp 的 timeZone（按 IANA 时区的墙钟显示）、refreshInterval 与 translations（含 justNow），相对型自动刷新，页面隐藏或离开视口时暂停；Watermark 新增 fullscreen（固定铺满视口、压在模态之上，层号经 --xh-watermark-layer 覆盖），image 也接受 http(s)、blob: 与相对地址，删掉或改写水印节点会被原位放回

  • 新增 @xihan-ui/chat-stream 的会话改为消息树：ThreadStore 新增 regenerate、retry、edit、continue、selectBranch 与 getTree，submit 可带文件与数据 parts，UIMessage 新增 parentId 与 status，createThreadStore 可经 messages 恢复会话；stop() 当场收尾并把这一轮记为 aborted

  • 新增 流式 Markdown：@xihan-ui/markdown 渲染任务列表与脚注，裸地址自动成链（bareLinks，缺省开），仍在生长的末块不再露出没闭合的强调、行内代码与链接符号；行内引用 [@来源] 与公式 $…$ 渲成占位节点，MarkdownStream 经 Vue 的 citation / math 插槽、React 的 renderCitation / renderMath、Web Components 的 inline-mount 事件把引用角标（可直接接 Citation）与公式产物放进去

  • 新增 代码与日志：CodeView 按缩进折叠语法块（blockFolding、folded / defaultFolded，部件 line-fold-trigger）；DiffView 支持行评论（commentable 给每行一颗评论钮并发出 comment-request，commentLines 在指定行下铺出 comment-thread）；Log 支持 ANSI 着色（行上写 ansi）与按级别过滤 levels

  • 新增 AI 对话：MessageFeed 新增日期分隔 separator、回到底部钮上的未读数 unread-count 与等待首个片段时的呼吸点 pending-indicator；Approval 新增 requireReason（拒绝必须写理由）与待决呼吸点 pending-indicator；QuestionFlow 的选项与题目可写 description，多选题新增 minSelections / maxSelections；Reasoning 给了 startTime 时思考中显示已用秒数

  • 修复 浮层关闭那一刻就把焦点交回触发器（Dialog、Drawer、Popover、Popconfirm、Command、Tour、ImageViewer、Select 等），退场动画期间焦点不再落到 body；退场中途重新打开时从当前透明度接着淡入，焦点按这一次的初始焦点落位；Accordion、Collapsible、Reasoning、ToolCall 展开或收起到一半反向时从当前开合程度接着走

  • 修复 动效作用域：系统开启减弱动效时，写了 data-motion="default" 的子树恢复完整 CSS 动效；animate()、@xihan-ui/animations 预设、@xihan-ui/backgrounds 与贴底滚动按宿主所在的 data-motion 作用域判断；@xihan-ui/animations 的 bounce 预设不再因逐帧缓动的写法被浏览器整段拒绝；data-transparency="reduce" 在嵌套的局部主题里不再失效；高对比档下关闭叉、箭头、对号、单选点等皮肤字形不再消失

  • 修复 书写方向：RTL 下行内居中的元素（居中的轻提示堆叠、Carousel 分页、ImageViewer 工具条、Slider 刻度与值气泡等）不再偏出；Switch 滑块、Tree 与 TreeSelect 分支箭头、Rating 星形、ColorSlider 与 Slider 值气泡、PasswordInput 强度条、SideNav 分支箭头改按就近的 dir 换向，RTL 页面里局部写回 ltr 时不再错位；Popover、HoverCard、Popconfirm 的缩放原点在较旧的浏览器里也按书写方向取对；Tabs 整页 RTL 而未传 dir 时指示条不再落错

  • 修复 LoadingBar、Carousel、NumberAnimation 的 id 在服务端渲染与水合两侧一致；Web Components 连接之后才赋的 defaultValue、defaultOpen 等初值不再被忽略；TagGroup 放行输入法组合，按住 Enter / Space 只切换一次，点标签里的链接或按钮不再改变选中；按钮类触发器换面时字色与底色同步淡变；列表浮层的 1px 顶光不再随列表滚走；CheckboxGroup 勾中色与 Checkbox 一致，Table 禁用且勾中的勾选框显示置灰的勾

  • 修复 日期族不再依赖浏览器的周数据：同一个 locale 在各浏览器里排出同一张月历（此前少数地区的周首日因浏览器而异）；SideNav 分组改为合法的列表结构，读屏能念出列表项数与分组（需补 group-list，见升级须知）；分段形态（原 Segmented）的滑块在祖先带缩放（如对话框进场）时不再缩小偏位

  • 修复 ImageViewer 取图失败时画面正中显示警示字形（此前没有任何表现），禁用的翻页、缩放钮改为换前景色；LoadingBar 改长淡出时长时，条子不再在淡出途中先缩回；Marquee 的 speed 改按实测内容长度换算，不再随容器宽度偏快或偏慢；纵向 Carousel 拖拽不再取错坐标轴；空 Tree 或随后才由脚本填充条目时，Web Components 不再误报 wc.missing-part；Sortable 落点线在强制颜色模式下不再消失；Heatmap 的 thresholds 含重复值或非有限值时不再多出空档，改为剔除并报 chart.invalid-range

  • 修复 Anchor 点目录项平滑滚动途中，高亮不再被途经区块冲掉，改为锁到滚动停稳；Tour 收起时气泡与高亮框不再滑向视口左上角；同页多个 SideNav 的折叠态悬停弹出不再互相撤销等待；Toolbar 里的菜单触发器用上下键展开时工具条不再同时走位；Web Components 的 Breadcrumb max-items 恢复生效；Pagination 省略位浮层的非法延时不再被当作 0，改为报 INVALID_DELAY

  • 修复 Layout 侧栏里放 SideNav 时导航右缘不再被裁掉；Pagination 每页条数下拉不再占满 16rem，改为按内容定宽；Command 面板进场的位移与缩放方向改正；Notification 轻提示预设的行首缺省字形改为按语气区分（此前四种语气都画成信息字形）；Toolbar 分组内相接的分段按下时不再缩放撕开接缝；Tabs 竖排限高时标签不再被压扁；PageHeader 在视口恰为 640px 时与其余组件同档换排布

  • 修复 ImageCropper 出图不再忽略旋转与圆形外形，改为按所见导出，方向键跟随屏幕方向；TextField 的字数与 maxLength 改按字素计，组合 emoji、国旗各算一个字；Transfer 与 Virtualizer 组合时列表铺满面板、自绘滚动条跟随虚拟视口；DatePicker 手机档样式在 Safari 16.2 / 16.3 恢复生效；Slider、ColorSlider 的值气泡拖动时不再随拇指放大

  • 修复 CodeView 的 filename 部件留空时显示根上的 filename；DiffView 没写头部时以文件路径为可及名；parseUnifiedPatch 不再把 git diff 末尾的换行多算成一行；React 的 MarkdownStream 重渲时不再冲掉选区；@xihan-ui/chat-stream 的传输在取消时抛错，不再把已停止的一轮记成 error

  • 优化 初始内容不播进场：挂载时已打开、已展开或已存在的内容直接呈现，之后的变化照常播动画。覆盖 Dialog、Drawer、Popover、Popconfirm、Tooltip、HoverCard、Menu、ContextMenu、Menubar、NavigationMenu、Command、FloatingPanel、FloatButton、Tour、ImageViewer，Select、Combobox、TreeSelect、Cascader、ColorPicker 与四个日期 / 时间选择器，Accordion、Collapsible、ToolCall、Reasoning，Layout 侧栏、Steps、TagGroup、Badge、EmptyState，以及 MessageFeed 首屏的历史消息与其中的 ToolCall、Approval、QuestionFlow 卡片

  • 优化 到达与换位：Command、Notification、MessageFeed 新到的条目按到达先后错开进场，Command 过滤后重新露出的结果不重播；TagsInput 标签、FieldArray 行、Select 多选标签、TagGroup、FileUpload 文件列表与 Notification 卡片增删时带进退场，其余项滑到新位置；Sortable、Table、Tree、Tabs 放下或换位后条目从原处滑到新位置，Sortable 带松手速度弹簧落位，键盘重排逐格滑动

  • 优化 进退场补齐：Badge 计数出现与清零原地弹出、缩小淡出；Skeleton 加载完后盖在真实内容上淡出；Avatar、Image 占位与图片交叉淡变，Avatar 新增 fallbackDelay（缺省 300ms），缓存命中时不再闪一下首字母；Alert 关闭先淡出再收起占位；BackTop、Tag、FloatButton 展开列表、MessageFeed 与 Log 的回到底部钮都在退场播完后才隐藏，FloatButton 触发器展开后「+」转成「×」；Form 错误摘要与字段错误文案淡入淡出，下方内容不再跳动；FileUpload 传完时进度条走满后淡出

  • 优化 加载与占位态：Button、Clipboard、DownloadTrigger、Popconfirm 确认钮在途时加载环居中压在钮上、钮宽不变，短请求不闪；Switch、Notification、Approval 在途改用同一副加载环，Notification 落定时与语气字形交叉淡变；Table、Tree、Cascader、Select、Combobox、Listbox、Mention、Transfer、TreeSelect、Command、GridList 首次加载显示加载环，已有内容时后台刷新保留上一帧并淡化；ImageViewer 取图时画面正中转一枚加载环；Spinner 三点档改为依次亮起

  • 优化 位置与尺寸过渡：Tabs、Anchor、NavigationMenu 与 RadioGroup segmented 的指示器只在换项时滑动，首次落位、窗口缩放与字体加载时直接到位；NavigationMenu 两张面板间切换改为瞬时；FloatingPanel 进出最大化、SideNav 折叠展开、Splitter 折叠、Tour 换步、Steps 推进平滑过渡；Progress、LoadingBar、FileUpload 的填充改为平移，进度变化不再重排；Popover、Popconfirm、HoverCard 在 *-start / *-end 对齐时从锚点一端涨开；Pagination 页码面板从省略位一侧滑入

  • 优化 手势与细节：ImageViewer 平移限定在图片范围内，拖出范围有阻尼、快甩有惯性，换图时新图直接淡入；Carousel 拖拽松手按速度判定翻页并由弹簧落位，首末页往外拖有阻尼，loop 回绕沿原方向接续；四个日期 / 时间选择器打开时时间列直接停在选中格；Cascader 悬停换列时不再反复重播进场；PromptInput 发送与停止的字形切换改为淡变；PasswordInput 强度条平滑增长，单选圆点缩放落位，DateField 当前段反白淡变，CalendarRangePicker 挑到一半时预览改为中性淡底

  • 调整 减弱动效改为去掉位移、保留淡变：换色与淡入淡出保留 120ms，位移、缩放与尺寸变化仍瞬时完成；Drawer、轻提示与 Layout 覆盖档侧栏在减弱档改为淡入淡出，浮层退场先淡出再卸载。几何过渡改取专属时长：展开箭头随正文开合同步，集合行与树行的底色过渡改为 micro，字段焦点环即时出现，行尾对号与勾选标记改为淡变（见升级须知）

  • 调整 缺省主题的描边与淡底改为半透明墨色，落在作者自己的彩色区块上会成为该底色的深浅变体；Table 吸顶表头与冻结列等要盖住下层的面改用不透明档（见升级须知）

  • 调整 浮层定宽：Select、Combobox、TreeSelect 的候选面板与字段盒等宽，Select、TreeSelect 的浮层锚在字段盒上；Cascader 归为面板型浮层，按内容定宽、改用实体的 floating 面；NavigationMenu 面板按内容自然宽度排开，超过 --xh-navigation-menu-content-max-w 才折行

  • 调整 面板内的搜索框统一：Command、Cascader、Transfer、TreeSelect 的内嵌搜索框改为通栏一行，高度与字号随尺寸档，只画一道面内分隔线，聚焦时不画焦点环，占位文字与其余字段同色

  • 调整 尺寸与排版统一：TimePicker、TimeRangePicker、DatePicker、DateRangePicker 的时间格随尺寸档定高与字号（此前固定 28px）；Steps 序号圆点随密度换档；InputGroup 未设尺寸时整组与单个字段同宽；TagsInput 计数改为 12px 说明字号；Menu、ContextMenu、Menubar 的条目说明改用控件次级字号；Alert、Notification 的指示符到正文统一为 12px；ImageViewer 关闭钮改为 40px 圆形；ToolCall、Approval、QuestionFlow 的状态标签统一语气色，与 Tag sm 等高；ToolCall 触发条改用标签字重

  • 调整 动作与面：FileUpload 的三颗按钮改用 Action Control 家族，悬停 / 按下降一档、不再抬影；outline 动作钮的禁用描边改取 --xh-border-default；Pagination 跳页框改用字段外观；ColorPicker 输入盒与 Select 等下拉选择同一副字段外壳；Table 表头下沿与表尾上沿改为内部分隔色（新增 --xh-table-header-border / --xh-table-footer-border）；Tree 落点线改为品牌色；Carousel 轨道、ImageViewer 图片、Sortable 条目的位移改写独立的 translate / rotate / scale，样式里写的 transform 改为与之叠加

  • 调整 SideNav 宽度改读 --xh-sider-w / --xh-sider-collapsed-w，与 Layout 侧栏同宽，当前项不再加粗；Reasoning 缺省改为 outline、md，Reasoning 与 ToolCall 内距与 Accordion 同档；CodeView、DiffView 缺省字号改为 md 档，CodeView 高亮行改为中性淡底加行首强调条，Log 行高改为 1.5rem（见升级须知）

  • 调整 缺省值改按语言推断：DatePicker 的 showTime 小时制按 locale 推断；NumberAnimation 与 Timestamp 的输出改由 Intl 按语言生成；NumberAnimation 缺省节奏改按数值角色取动效令牌（见升级须知）

  • 调整 Heatmap 并入图表家族：palette 扩为基础色板的十二个色相加 gray；详情条改为与其他图表一致的 frosted 提示框；缺省播放填色动画，数据含负数时缺省按发散色阶（见升级须知）

  • 调整 文档站新增「图表」分类，Heatmap 移入；组件总览改用 SVG 示意图；动效规范页按角色、令牌与编排规则重写；自定义元素版示例的模块脚本改由 Vite 编译，示例里可以直接 import 包

  • 移除 Toast、Segmented、IconWrapper、GradientText 四个组件，分别并入 Notification、RadioGroup、Icon、Typography（见升级须知）

  • 移除 对 @internationalized/date 的依赖（连带 @swc/helpers），库包不再有运行时第三方依赖

v2.1.0 (2026-09-24) ​

本版补齐集合类组件的条目契约：逐条语气、说明、快捷键与首尾两格的逐条钩子，菜单的 collection 可以直接铺出分组；选中标记统一为行尾对号。本版包含少量破坏性变更（Tree、Listbox、TagGroup 的选中外观与相关部件、槽名），按次版本发布，升级前请看下方升级须知。

升级须知

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 个）。所有更名与删除均不保留别名、转发或兼容层，引用旧名会直接报错。

升级须知

以下按包、组件、部件与属性、行为四类列出破坏性变更的范围与去向。完整对照表（旧名 → 新名，逐部件、逐槽名）见各包随 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) ​

版本与兼容性

首个正式版。从这一版起，版本与兼容性政策的全部条款生效。

  • 新增 框架无关的无头内核：状态、交互与无障碍逻辑住在 @xihan-ui/headless，适配器只把 connect() 产出挂到宿主元素上；同一份内核在两端行为一致
  • 新增 119 个组件，每个同时产出无头内核、Vue 组件、自定义元素与默认皮肤——通用 15、布局 8、导航 16、数据录入 32、数据展示 30、反馈 9、浮层 7、AI 对话 2，逐个见组件总览
  • 新增 @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 个输入 / 选择控件有三种盒，盒是 <button> 的那五家没法把清空钮放进框里

  • 调整 清空 / 关闭 / 移除按钮收成四类契约：焦点模型、空态、尺寸、圆角、互斥、文案键、键盘路径逐条统一；select / cascader / tree-select / popselect 补上了此前完全缺席的键盘清空

  • 调整 状态属性收成一套词汇：当前项一律 data-current，data-active 的一名三义拆成 data-in-path 与 data-passed，组级混合态归 checked | unchecked | indeterminate

  • 调整 默认语言跟随运行时：日期系兜底从写死 zh-CN 改成「显式 locale → 全局配置 → 宿主语言 → en-US」。默认周首日随之从周一变成周日，要固定就显式传 locale 或 firstDayOfWeek

  • 调整 「移除这一枚 chip / 这一行」统一叫 item-delete-trigger，四个文案键归成 deleteItem

  • 调整 选择态一族（table / tree / transfer）的选中集合统一叫 selection，载荷键统一 { value }

  • 调整 兜底字形改用真图标（--xh-glyph-mark-* 二十个令牌），不再是跨系统长相各异的 Unicode 字符

  • 调整 减弱动效只剩一条通道，CSS 侧新增 [data-motion='reduce'] 钩子；缓动与时长的真源是令牌

  • 调整 并排成对的面板定高——穿梭框搬走条目后整体不再变矮

  • 调整 菜单族三家（menu / menubar / context-menu）逐条同值：menubar 此前根本没有「子菜单触发项展开态」这条规则

  • 修复 side-nav 折叠成图标栏后，行按钮与链接没有可及名——读屏用户完全不知道每一项是什么（真机 axe 扫出，critical）

  • 修复 date-picker / time-picker / combobox 有值时下拉钮被藏掉：鼠标用户没有打开入口，Escape 收起时焦点掉到 body

  • 修复 日历周序号在周日起算时整列少 1（ISO 周里周日属于上一周）

  • 修复 TimeProps.locale 的窄联合与全局 BCP 47 locale 对不上，配 de-DE 会拿到中文用词

  • 修复 4 条子路径导出的类型文件根本不存在，按这些子路径引入时类型全部解析不到

  • 优化 无障碍：真机 axe 覆盖到 dialog / drawer / image-viewer 三个模态，全部通过

  • 优化 版本策略页按实测重算：data-state 取值清单删掉 4 个库里已不存在的，WC 命令式方法从 22 条改成 29 条

v1.0.0-alpha.2 (2026-08-16) ​

@xihan-ui/motion 与 @xihan-ui/animations 是新包，这一版首次发布。

  • 新增 @xihan-ui/motion 动效原语与 @xihan-ui/animations 现成动效两个包，并补齐动效地基的四个缺口

  • 新增 @xihan-ui/icons 的 SVG → IconRecord 构建期转换器：xihan-icons 命令与 @xihan-ui/icons/codegen 子路径，把任意 SVG 目录转成可摇树的运行期模块

  • 新增 首方图标集扩到覆盖中后台界面的常用语义，共 179 枚手绘图标，分九类；只引一枚仍是 149 B（gzip），集合变大不影响你的产物

  • 新增 自定义元素的全局文案层 setXhConfig()

  • 新增 startSkinCheck() 开发期探测与 styles.missing-skin 诊断码——漏引皮肤不再静默

  • 优化 75 个组件的插槽写上真类型，vue-tsc 从此接得住插槽名与载荷键名的拼写错误

  • 优化 104 个组件全部留出 <Comp>Translations 的位，哪怕眼下一句文案都没有——后面要加时不必改结构

  • 优化 每份皮肤都能单独引入，动画不再指望别处的文件在场

  • 修复 官网作为第一个真实消费方落地时暴露的四条问题（宿主定位、图层序等），全部改代码而非只改文档

  • 调整 collection 铺开的结构必须凑齐必备部件，三档语义写进文档

v1.0.0-alpha.1 (2026-08-13) ​

@xihan-ui/sound 是新包，这一版首次发布；@xihan-ui/icons 在上一版没能发出去，这一版补齐。

  • 新增 @xihan-ui/sound 声音层：纯 Web Audio 的程序化 UI 音效，零音频文件、零第三方依赖、框架无关；命令式反馈服务已接上

  • 新增 进度条的环形与仪表盘两种形态（variant 由 line 扩成 line / circle / dashboard）

  • 新增 级联选择的空态兜底：empty 部件、data-empty 标记与文案覆盖

  • 新增 checkbox / switch / combobox / color-picker 能进 HTML 表单，表单字段组件由 18 个变 20 个，五个缺口清完

  • 新增 复合控件响应表单重置：机制本体加 17 个组件全部接上；Web Components 侧同步

  • 新增 --xh-border-control / --xh-border-control-hover 两支控件边界令牌，data-contrast 随之接上

  • 新增 popconfirm 与 float-button 的组件文档页第一次有了 Props 表

  • 修复 摇树第一次真的生效：只用一个组件不再拖来整个库。此前七个库包都是单入口打包，500+ 模块被摊平进一份 dist/index.js，sideEffects: false 随之失效。实测只用 XhBadge 由 168,947 B 降到 538 B

  • 修复 RTL 下浮层的 start / end 第一次真的翻过来

  • 修复 浮层箭头指向锚点，不再钉死在浮层中点

  • 修复 index.css 的级联层序：层序声明挪到入口最顶，此前令牌与部分组件皮肤抢先立层

  • 修复 四处只在真实宿主里才现形的缺陷（含首屏即展开的对话框与抽屉能服务端直出、无 window 的宿主里不再抛异常）

  • 修复 带语气的 outline 控件边框补到 3:1，控件边界切到 border.control，WCAG SC 1.4.11 第一次真的达标

  • 修复 补齐 4 处「边框改不动」的覆盖槽

  • 修复 combobox 展开按钮翻面只转箭头字形，不再带着悬停底色一起转

  • 修复 级联选择的空态占位在 Web Components 侧补齐，两个适配器不再分叉

  • 调整 跨组件已经分叉的名字统一回一套（7 处）。part 名与 prop 名在 1.0 之后就是公开 API，趁 alpha 一次改完，逐条迁移点见各包 CHANGELOG

  • 调整 下拉与列表族的条目度量与高亮档位统一成两档制，分两批铺完 12 个组件

  • 调整 级联选择皮肤翻修：展开路径改品牌淡底加粗、分支条目补右向箭头、列改内容撑宽定高

  • 调整 hideOutside 的入参形状随真实宿主那四处修复一并变化

v1.0.0-alpha.0 (2026-08-11) ​

框架无关重写

基座 ​

  • 新增 @xihan-ui/kernel 结构原语：anatomy、mergeProps、normalizeProps、Scope、context、id 生成，以及浮层定位、虚拟滚动、代码着色三个端口的类型契约
  • 新增 @xihan-ui/machine 自研薄状态机：定义层、createService 解释器与 vanilla 运行时，受控值绑定与效应生命周期
  • 新增 @xihan-ui/behavior 交互行为原语：消解层、焦点域、滚动锁、进出场，随后补上条目集合导航（roving tabindex 底座）与首字母连打检索
  • 新增 @xihan-ui/tokens 设计令牌体系与主题运行时，令牌从 DTCG 源产出 CSS / JSON / TS 三种形态
  • 新增 @xihan-ui/styles 纯 CSS 皮肤层，后续补上 reset 层
  • 新增 @xihan-ui/kernel 全局诊断通道，状态机错误投递进该通道而不是抛在使用者脸上

适配器 ​

  • 新增 @xihan-ui/vue Vue 3 适配器，Button / Dialog 纵切片先打穿全链路
  • 新增 @xihan-ui/web-components Web Components 适配器，Light DOM 行为宿主；xh-dialog 把「有状态组件也能框架无关」这件事验证掉
  • 新增 WC 侧观察 Light DOM 增删并重新接线，抹平「运行期增删条目」上的适配器分叉
  • 新增 WC 角色节点契约校验与 Custom Elements Manifest 生成

组件 ​

  • 新增 102 个组件逐批铺开，每个都同时产出无头内核、Vue 组件、自定义元素与默认皮肤：从 Button / Dialog 起，经 Switch、Checkbox / Collapsible / Separator、Toggle / Progress / Badge、RadioGroup / Tabs / Accordion、Tooltip / Popover、Menu、Select / Avatar / Field、NumberField，到日期族与最后一批，双适配器铺满
  • 新增 alert / spinner / skeleton / empty-state 四个反馈类组件
  • 新增 Checkbox 三态
  • 调整 Select 支持多选，选中值由单值改为集合：SelectValueChangeDetails.value 由 string | null 变 string[]，SelectApi 的 value / valueText 变数组，setValue 签名变 (next: string | string[]) => void；Vue 侧 update:value 载荷与 WC 侧 value-change 的 detail 随之变化。见选择器

视觉词汇表 ​

  • 新增 三个正交的视觉轴：variant 形态（solid / subtle / outline / ghost）、tone 语气（brand / neutral / success / warning / danger / info）、size 尺寸（sm / 缺省 / lg）。语气做成与组件无关的共享一层，各组件的形态规则只消费它声明的私有槽——加一个语气改一处，不是逐个组件写六遍
  • 新增 34 个组件接入这套词汇表：按钮族与表单控件、十个输入类组件、以及标签页、步骤条、菜单族、分页、表格、对话框、抽屉等。没写轴的组件外观与接入前逐值一致
  • 调整 实心底上的前景色按实测对比度分派而非统一白字：600 档上白字对 brand 5.08、neutral 7.80、danger 4.83 达标，而 success 3.04、warning 2.70、info 3.47 都不到 4.5，这三族配深字
  • 调整 破坏性变更：alert 的 variant 改名为 tone。它原本的取值是 success / warning / danger——那是语气不是形态，与全库词汇表冲突。取值不变，只改属性名；同时移除公开导出的 AlertVariant 类型
  • 调整 toast 的配色改走共享语气层，由 type 内部派生（error → danger，loading → 中性），公开 API 不变
  • 调整 三条轴由裸 string 收成联合类型，从 @xihan-ui/kernel 导出：Tone（六档）、Size（sm / md / lg）、ControlVariant（outline / subtle / ghost，十二个输入控件）与 ActionVariant（前者再加 solid，按钮族）
  • 修复 checkbox 半选态的横杠此前不可见：方框只在全选时填色，半选保持画布底，而横杠用的是实心底上的前景色，白压白等于没画

自研替换第三方 ​

  • 新增 @xihan-ui/position 自研浮层定位引擎（包含块解析、缩放换算、翻面与避让、跟随更新），移除 @floating-ui/dom
  • 新增 自研虚拟滚动内核，移除 @tanstack/virtual-core
  • 新增 WC 自研响应式基类，移除 @lit/reactive-element
  • 新增 @xihan-ui/markdown 自研解析与渲染，移除 markdown-it
  • 新增 代码着色走端口，内置自研粗粒度词法器，可换 Shiki
  • 调整 至此全部库包的运行时第三方依赖只剩一个（@internationalized/date，仅日期族使用）。见包与依赖关系

AI 与 Markdown ​

  • 新增 @xihan-ui/chat-stream 协议内核与 AI 组件族第一批：SSE 读取、协议归一、parts 归约、会话 store，配 Thread / Composer / CodeBlock 三件与粘底原语，双适配器
  • 新增 @xihan-ui/markdown 流式渲染内核，增量切块 + 稳定 key + 消毒
  • 优化 Markdown 逐步实现缩进代码块、Setext 标题、跨行链接引用定义与列表松紧排布，CommonMark 官方用例一致率由 375 提升至 489

视觉层 ​

  • 新增 @xihan-ui/backgrounds：WebGL2 背景效果与数据驱动粒子点云，框架无关、零第三方依赖。流场跑片元着色器、粒子走 gl.POINTS，两通道共用同一段 GLSL；内置 14 个效果，不支持 WebGL2 时降级为 CSS 静态背景
  • 新增 两个适配器接上视觉层，各走独立子入口 @xihan-ui/vue/backgrounds 与 @xihan-ui/web-components/backgrounds，@xihan-ui/backgrounds 声明为可选 peer
  • 修复 修复画面在真实页面里一片空白的三个成因

图标 ​

  • 新增 Icon 原语：IconRecord / IconNode / IconTag 类型、connectIcon、XhIcon、<xh-icon> 与 icon.css。图标数据是结构化节点数组而非 SVG 字符串，渲染端逐节点建元素，运行期不经 HTML 解析器
  • 移除 旧 @xihan-ui/icons（27 个第三方图标集的聚合，约四万个图标）整包移除并在 npm 上弃用，重写为只收自研图标的首方集，第一批 29 个覆盖组件库自用的全部语义

无障碍 ​

  • 新增 无障碍扫描接上真实浏览器与 axe，逐个组件扫
  • 新增 键盘规格表机读化，随包提供
  • 修复 存量无障碍违规清零，由 24 条降到 2 条（WC 侧 steps 一条，外加一条步骤重放豁免）
  • 修复 令牌 fg-subtle 达到 AA，并给对比度立下判据
  • 修复 焦点陷阱抓不住第一次逃逸；移除持有焦点的条目后不再让整组脱离 Tab 序列；删掉文件上传条目后把焦点交回投放区
  • 修复 浮层族改用 fixed 坐标系，不再被 overflow 祖先裁掉
  • 修复 挡住输入法组合态
  • 修复 Dialog 三处：模态背景失活、非模态焦点域、收起态 hidden
  • 修复 Field 的名字关联不再依赖 control 是可标注元素；Splitter root 不再输出 aria-orientation
  • 修复 消解层只在展开期间入栈，不再与开合无关地常驻
  • 修复 状态机停机后送入的事件一律静默丢弃，dev 下不再抛

令牌与发布 ​

  • 调整 皮肤层令牌成为唯一事实源，删掉全部字面量兜底，跨组件共享的默认值全部令牌化
  • 新增 14 个公开包锁步同版发布

Released under The MIT License

Copyright ©2021-Present XiHanFun and contributors.