Jixoai UI v0.4.0：改进视觉体验，扩展内容呈现

2026-09-10 jixoai v0.4.0 ui

按压动效可以挂在任意元素上；代码高亮按需选引擎，语言自动识别；图标有了组件；正文排版成体系，数学与图表有了组件。registry 从 113 条涨到 136 条，三处迁移动作都不留兼容层。

$ git log v0.3.0..v0.4.0 --oneline | wc -l
175

jixoai-ui 0.4.0 发布了（2026-09-10）。175 个提交，registry 从 113 条涨到 136 条，净增 23（新增 25，移除 icons 与 alert-dialog）。主线是动效改为附件；高亮、图标与排版，以及数学图表、表面结构与文档画布的更新落在同一条线上。三处迁移动作，都不留兼容层。

动效可以挂在任意元素上

按压特效改为 Svelte 附件。shimmer、pulse、rainbow 与 ripple 通过 {@attach pressEffect(fx)} 挂载，挂在你渲染的任意元素上；press-button、icon-button 与 chip 的 effect 属性退场，组件本身不再持有特效知识。

<script lang="ts">
  import PressButton, { shimmer, rainbow } from '$lib/ui/press-button/press-button.svelte';
  import { pressEffect } from '$lib/ui/press-button';
</script>

<PressButton variant="fill" {@attach pressEffect(shimmer())}>Deploy</PressButton>
<PressButton variant="outline" {@attach pressEffect(rainbow())}>Cancel</PressButton>

Svelte 的 attachments 已是一等语法，不需要实验开关。它与 action 是两种契约，特效导出因此重写为附件工厂，仓库全部 use: 挂载在同一次变更里搬完（32238a08）。

机制：附件契约与迁移口径

{@attach expr} 的值就是附件本身，签名为 (element) => cleanup；参数替换时按身份重新挂载，没有 update 通道，也没有 destroy 对象。action 形状的函数直接挂会崩溃，仓库里返回 {destroy} 的内部 action 在裸换语法时会静默泄漏，所以 svelte/attachments 的 fromAction(action, () => param) 负责桥接 action 形状的内部实现，共迁移 39 处 use: 挂载。

shimmer 与 rainbow 画的是宿主自己的边框环，环宽由 ringW 驱动，填充走 number | null | Canvas 三态通道，solidFill() 把任意 CSS 颜色铸成保证不透明的 0xRRGGBB。ripple 换成不带 viewBox 的 svg 座位，用 user units 承接宿主继承来的轮廓，逐层 clipPath 裁切加 feGaussianBlur 柔化。

特效家族有了自己的主页 /docs/effects.html，玻璃的双层游乐场整体搬了进去，原路由 /docs/components/glass.html 退场。

rainbow 画布：三个中性宿主按钮 upgrade / subscribe / ⌘ 共用同一个特效对象，宿主自己的边框就是流动的彩虹环，环宽由 ringW 驱动，填充走 auto / null / solidFill 三态

effects 主页：家族法则，特效是挂在元素上的附件工厂而不是组件；五枚小签列出两种挂载通道、动作桥与挂载点属性

高亮引擎按需安装，语言自动识别

高亮层拆成零依赖内核加六个可安装后端（microlighter, highlight.js, prismjs, shiki, sugar-high, tree-sitter）。默认只提供一个引擎及该引擎的全部能力，需要别的再按需安装。此前 code-card 与 highlight 两个条目把 prismjs 和 microlighter 写进 npm dependencies，装一个组件等于装下三个引擎，这一版改掉了。

语言检测是新增能力。LanguageDetector 抽象加内置的 DLD（默认语言检测器），分四层按需加载，lang="auto" 启用检测，markdown 面现在默认走 auto。行内代码的默认引擎换成 microlighter，4.5KB，零标记，纯文本可复制。

机制：DLD 的四层

第一层 filename/ext，扩展名表加精确 basename 表（Dockerfile、Makefile 类）。第二层 shebang 与 modeline，只看首行。第三层特殊结构：JSON 全文 parse，<?xml 与 <svg> 根判 svg，YAML、TOML 与 INI 走正则特征；本层不做编程语言指纹。第四层统计式检测，引擎是 betlang 的 wasm 构建。

code-card 的完整结构：文件名签 spawn.ts、右上 shiki · ts 引擎徽章、脚注 powered by Shiki · theme: jixoai 与 copy 控件

图标有了组件与按需加载

图标系统补上了组件面。<Icon name="check" /> 带类型安全的 IconName 联合与 size、strokeWidth 两个属性，取代此前 197 处 {@html icons.x} 注入（提案口径：registry 77 处加文档站 120 处）。

插件面把渠道变成公开 API。@jixoai/ui-vite-plugin/icons/[lucide|md|ph|rx] 是同一个包的独立入口，lucide 默认开启，其余按导入启用；jixoai({ icons: { library } }) 生成 icon-set.gen.ts，把自定义图标名一起并进 IconName。图标按块懒加载，消费方不用为整套图标付费。

这一版还给图标加了真实项目 E2E 层。examples/hmos-icons 是真消费者，真的被安装并构建，当场暴露两个缺陷（00d3fd92）。

细节：E2E 层暴露的两个缺陷

svgo 会把每个图标的 id 压成同一个短记号（a），同页内联两份 Sketch 导出就会互相错认 use 目标；现在 scopeIconIds 给每个打包 id 加上规范名前缀。RAW 安全闸门原本直接拒绝 Sketch 导出那种 use 加 xlink 的形状，让渠道在第三方图标集面前近乎不可用；现在按片段法放行同文档引用，外部引用照旧拒绝。插件测试套件 398/398 通过。

icons 页的组件面：Icon 组件的 size 梯级，同一个 prop 在 12 / 16 / 24 / 32 四档上实渲染

排版成体系，Markdown 结构可改

排版新增 prose 条目（<Prose> 提供者）与 typography lib。十一个旋钮（size, leading, family, ink, gradient, ground, align, indent, initialLetter, wrap, hyphens）全部走 absentSlot 语义：不设就是不发声，最近的上游设置生效，外层 <Prose size leading> 永远盖不过内层 <Markdown typography=>。这是级联上的主权契约，不靠 JS 遮罩。

阅读内容族把 Markdown 里没有对应组件的结构逐个提取出来，改组件就是改 Markdown 渲染。blockquote 支持 GitHub 边线、着色 callout 与手稿缩进几种变体；heading 按 level 出原生 h1–h6；Link 的外链默认带 suffix-icon；List 分出严谨的 ol 与 ul 场景。text.svelte 实现 <Text mark="…">，并把 P Strong Em Del Mark Ins Sub Sup 从同一个模块导出。Markdown 面本身是流式的，AST 映射到 registry 部件，代码块走 code-card 的代数守卫异步重绘。

细节：blockquote 的字面槽

左边线拆成 rule 与 ruleSize 两个字面槽：rule 选 inset 阴影或 border，ruleSize 走 1px/4px/8px。heading 带上从 markdown 面迁出的 em 尺寸梯级。

prose 页的旋钮展示：左栏 size 与 leading 走继承缩放（ambient 14px 对 17px），右栏 align justify 加 hyphens 与 wrap pretty

数学与图表有了组件

lib katex 是 renderToString 之上的薄门面。一个 import 同时拿到数学标记与字体：katex.min.css 的导入是模块唯一的副作用，字体跟着 npm 包走，消费方不用额外配字体。命名按语法标准来，LaTeX 的组件叫 math-block 与 math-inline，mermaid 的语法是它自己的，名字照用。

lib mermaid-engine 是懒加载单例，引擎约 1MB，按需 code-split。验收轮落了两处裁定：mermaid 的 CROSSED pin 自带画布，显式主题钉住时按目标主题绘制视口；math-block 增加 FIT 变体，不滚动、按比例缩放，打印默认走它（8893aa35）。

细节：katex 门面的默认值

jixoai 默认值三项，均可被调用方同键选项覆盖：output: 'htmlAndMathml'（视觉 HTML 加读屏 MathML）、throwOnError: false（无效 TeX 原地着色不抛错）、errorColor 绑 var(--error) 令牌。选项透传，registerMacros 是站点级扩展点，重复键后者覆盖。

弹层与卡片共用一套结构

2026-09-09 的结构内核把「底部动作区」收敛成一条法则。head、body、foot 三段加贴纸式结构，一切规则锚在 data-jx-* 属性族上，任意元素盖章即成结构；body 独享滚动；行内标尺统一由 CSS 服务端渲染。Dialog 卸掉自己的皮肉改用 Card 的方言，ButtonBar 退场。

动作带法则随后泛化到 sheet、system-dialog 与画布 dock 三处，按钮在纵向上铺满整条带，不再浮在带的中央留白。AlertDialog 随之改名 SystemDialog，registry 条目 alert-dialog 换成 system-dialog（ed1d8a3e，区间内唯一带 ! 标记的提交）。

card 页：结构内核与 head / body / foot 三段带，foot 里是行内动作座 Cancel / Save

文档演示默认带源码栏

ComponentCanvas 的常驻 playground 泳道改成画布内浮动、可折叠且可拖拽的 dock，默认展开，收起后是一个图标 chip，控件用 ItemGroup 组装；画布本身瘦成 code-card 那样的卡片。此前泳道常驻，白占 18–22rem 舞台宽度。

配套的 canvas-everywhere 让每个文档演示走画布渲染。此前 114 个页面里 443 个 ComponentCanvas 对 1580 个 SectionCard，读者看不到大部分演示背后的代码；现在演示默认带源码栏（e96f55bb）。

component-canvas：画布套画布，外层 LIVE 舞台内嵌一个简化实例，两层各有自己的 Code 栏

一条命令装整组组件

命令行新增分组别名。npx jixoai-ui add effects 展开整组，npx jixoai-ui add effects/glass 取单个成员。

@jixoai/ui-vite-plugin 0.3.0 同期发布：排版带来 prose 作用域与 parts 的 R2/R3；图标带来上述真实项目 E2E 层；画布带来 dock 的验收裁定（亚克力弹层材质、竖向握把图标，position: absolute 退场）。

迁移（破坏性变更）

三处迁移动作，都不留兼容层：特效挂载、条目改名与玻璃类退场。仓库里只有条目改名那一个提交带 ! 标记，另两处的破坏性写在各自的提案里。

第一处是特效从组件属性改为附件：

  <PressButton {@attach pressEffect(shimmer())}>Deploy</PressButton>

第二处是两个条目换名字：alert-dialog 改名 system-dialog，icons 拆成 icon 与 icon-set。最低摩擦路径是按新名字重新加条目：

npx jixoai-ui add system-dialog icon icon-set

第三处是玻璃。手调的 .jx-glass 类退场，改由 blur() 的默认值承接（14px 模糊，1.35 饱和，68% 填充），未配置的迁移是计算等效的。下面是完整的挂载迁移对照表。

迁移对照表：动作指令、构建器属性与附件记录各自的新写法

其余变更

玻璃：动态带加了三层视差景深，跑无缝循环（a8c6d02f）；blur() 收编了此前手调的每一处颜料，liquid() 与 liquid.apple() 挂上忠于 kube 的透镜。
高亮：langDetector 契约进内核条目，AUTO_LANG 在 code-card 落地，检测实验台进入文档页。
排版：oklch 令牌调色板升到 v2，次级行距梯级、fused 变体与共享的文本修饰内核落地（341b101a）。
其余 49 个提交是修复。

从 0.3.0 到 0.4.0 共 175 个提交，conventional 严格口径计 feat 41, fix 49, docs 66, chore 15, test 1, refactor 1；另有 2 个非标准前缀（polish 与 harden）。

致谢

Svelte 的 attachments 语法与 fromAction 桥、kube.io 的 liquid glass 源码级配方、GitHub linguist 的语言数据，分别圈定了这一版三处能力的上游边界。

链接

Changelog：GitHub Release v0.4.0 · compare v0.3.0...v0.4.0
文档与 registry：ui.jixoai.com · effects 家族主页 · README
契约来源：effect-attachments 提案 · card-surface-kernel 提案（提案目录在 0.5.0 才归档入库）
升级：见上面的迁移节（改挂载方式、按新名字重新加条目，玻璃走 blur() 的默认值）
反馈：GitHub Issues
本站系列：Jixoai UI v0.3.0（2026-09-06 发布）
English version: /blog/2026-09-10-ui-0-4-0/