ElfUI

简体中文

English

简体中文

English

Appearance

变更日志 ​

v0.1.0-beta.19 — 2026-07-29 ​

  • 修复 InjectionKey 冲突，以及延迟子组件断开重连后无法挂载的问题。
  • Teleport、Suspense、ErrorBoundary、Transition、TransitionGroup 现在能正确持有并释放多根 DOM 与响应式作用域。
  • 离线动态组件 codegen 与 runtime compiler 对齐，保留属性、指令、事件和子节点。
  • 稳定 key 列表更新统一 batch；Vite 会跳过不含 ElfUI 宏导入文件的 TypeScript 解析。
  • 移除无效包依赖边，并加入非空的宏模板类型检查 fixture。
  • 按生命周期加固后的实测结果更新聚合体积预算，真实 tree-shaken 应用预算保持不变。

v0.1.0-beta.18 — 2026-07-29 ​

  • 修复模板事件 batch 中修改依赖后立即读取已缓存 useComputed() 仍返回旧值的问题。 computed 缓存现在会同步失效，普通 effect 仍延迟到事务结束时统一刷新。
  • 修复多个 useScrollLock() owner 并发锁定时，先释放的 owner 会提前解锁页面的问题。 现在仅在最后一个 owner 释放或卸载后恢复 body 原有的 overflow。

v0.1.0-beta.17 — 2026-07-29 ​

  • 删除 fragment 和 defineFragment() API，以及对应的编译器元数据和 Runtime helper。 局部结构直接保留在 defineHtml() 中，列表继续使用带 key 的 v-for。

v0.1.0-beta.16 — 2026-07-28 ​

  • defineFragment() 改为展开的具名回调参数。每个参数按名称对应同名片段属性，TypeScript 类型标注会生成对应的 props 类型，带默认值的参数会变成可选属性。
  • 旧的 defineFragment<Props>((props) => ...)、解构参数和剩余参数会由编译器诊断拒绝。

v0.1.0-beta.14 — 2026-07-28 ​

  • 修复父组件 onMounted() 早于子 Custom Element setup 的生命周期顺序；父组件现在可以在 mounted 中通过 useTemplateRef() 稳定调用子组件 defineExpose() API。
  • defineExpose() 新增 overrideNative 选项。有意增强 focus()、blur() 等原生语义时可以显式声明；scrollTo()、remove() 等普通命令仍建议改名。
  • 修复 Teleport 子树丢失 Provider 与 App 注入上下文的问题；逻辑组件父级、嵌套 Provider 优先级和 DevTools ownership 在移动到 body 后保持不变。
  • App/组件卸载现在会移除 Teleport 节点并停止其独立 effect scope，避免残留 DOM 和资源。
  • 编译器和 Runtime 增加仅开发态的模板节点源码标记，包含组件、命名 Fragment 和源码范围，供 ElfUI DevTools 精确定位；生产构建会完全裁剪这些标记。
  • 调试标记使用紧凑 codegen 协议。100 组件生产生成代码为约 200.5 KB min / 2.47 KB gzip / 1.09 KB Brotli，并增加独立开发代码体积门禁。
  • 七个框架包统一发布为 0.1.0-beta.14，Core 与 Vite Plugin 必须保持完全一致版本。

v0.1.0-beta.13 — 2026-07-28 ​

  • Core、Compiler 与 Vite Plugin 增加独立编译协议和启动期精确版本检查；错配会在模板编译前失败。
  • Vite Plugin 增加构建期 onMetadata / onDiagnostics 回调，供 Language Tools、DevTools 和文档生成器消费，不进入生产包。
  • MacroComponentMetadata 升级为 schema v2，增加组件结构、Fragment 依赖/归属/identity、源码范围和诊断摘要，同时保留 v1 适配器。
  • Fragment 增加循环引用诊断；匿名 array.map() 片段的索引 identity 边界可被工具识别。
  • 修复 beta.12 命名 Fragment 动态 Props 只保留初始快照的问题；:prop 和 v-bind 对象替换现在会精确刷新现有 DOM，不会重建 Fragment。
  • 增加 useId()，在客户端组件实例、多个 App 和 Custom Element 重连期间保持稳定唯一。
  • App 插件可返回同步清理函数；app.unmount() 在根组件卸载后按 LIFO 清理并隔离错误。
  • form-associated Runtime 接入 reset、disabled 与 state restore 原生回调，并把这些断言加入真实 Chromium 宿主矩阵。

v0.1.0-beta.12 — 2026-07-28 ​

编译期模板片段 ​

  • 增加 fragment\...`` 匿名模板片段 API。
  • 增加 const Card = defineFragment<Props>((props) => \...`)` 命名局部片段 API。
  • 片段只在编译期透明展开，不注册 Custom Element、不创建 Shadow Root，也不拥有独立生命周期作用域。
  • 命名片段的标签属性会编译为只读 props 对象；导出片段、动态模板和不支持的边界会给出编译诊断。
  • Vite 宏插件会识别新的宏导入，并继续要求 Core 与 compiler 使用一致版本。

发布对齐 ​

  • 七个框架包统一发布为 0.1.0-beta.12，使用时必须保持版本一致。
  • @elfui/router 保持兼容的对等依赖范围 >=0.1.0-beta.11 <0.2.0；Fragment 不改变 runtime/router 协议。

v0.1.0-beta.9 — 2026-07-22 ​

  • 修复宏 codegen 未把 RenderContext.directives 传给 resolveDirective()，局部指令现在可以在根模板和 v-for 子上下文中正常执行。
  • defineDirective 正式统一为单参数形式：const loading = defineDirective(definition)；变量名会转换为 kebab-case 模板名，旧的双参数形式不再支持。
  • 同名指令继续遵循组件局部优先于当前 App 的规则。
  • 组件卸载现在会释放仍存活的 v-if/v-for detached scope，保证指令清理钩子执行。

v0.1.0-beta.8 — 2026-07-22 ​

生命周期资源所有权与 API 收口 ​

  • onMounted() 可以同步或异步返回清理函数。卸载时按后注册先清理的顺序，在 onBeforeUnmount 之后、组件 DOM 和作用域释放之前执行；迟到的异步清理会立即执行。
  • 公开 API 统一为 onMounted、onUnmounted、useComputed、useEffect、明确数据源的 watch、theme、defineDirective 和 app.directive。
  • 删除 beta 别名 onMount、onUnmount、computed、watchEffect、watchPostEffect、watchSyncEffect、useTheme，以及公开的进程级全局 directive() 注册表。局部指令使用 defineDirective()，应用级指令使用 app.directive()。
  • 增加生命周期清理回归测试和公开 API 边界检查。

性能 ​

  • 长度相同且 key 顺序不变的列表现在直接更新 item/index state，不再分配完整 keyed diff 结构，也不会移动 DOM。
  • 宏生成组件会懒缓存并克隆较大的纯静态原生 HTML/SVG 子树；指令、ref、组件、自定义元素、slot 和动态边界仍走常规路径。
  • 没有注册生命周期 hook 的组件共享冻结空 hook 表，并在首次注册时写时复制，避免每个实例固定创建 11 个空数组。
  • 动态 style binding 复用两个声明缓冲区，重复更新不再为每轮更新和每个字符串片段新建 Map。
  • Core 全量入口已完成模块归因；完整聚合预算调整为 gzip 16.5 KB / Brotli 14.9 KB，真实 tree-shaken 应用预算仍为 gzip 9.8 KB / Brotli 8.9 KB。
  • verify:release 现在强制执行体积预算和真实 Chromium 相对性能门禁，并继续执行外部工具、宿主框架、多 Runtime 与真实发布包消费验证。

迁移 ​

直接更新 import。对于在 onMounted 中创建的外部资源，推荐直接返回清理函数：

ts
onMounted(() => {
  const chart = createChart(canvas.value!);
  return () => chart.destroy();
});

为保持原默认调度时序，将 watchEffect(fn) 迁移为 useEffect(fn, { flush: "pre" })；原来的两个调度快捷入口分别改用 post 和 sync。

v0.1.0-beta.7 — 2026-07-22 ​

宏语法去冗余 ​

  • 新增 defineHtml(\...`)，模板中的 ${...}` 继续按响应式表达式编译。
  • 新增 defineStyle(\...`)，并支持 defineStyle(styleA, styleB)` 组合多个导入样式。
  • 删除 html、css、MacroHtmlTemplate 的公开导出、源码实现和旧语法编译分支；这是 beta.7 的破坏性变化。
  • 删除已退出公共 API 的 useName、useProps、useEmit、useStyle 编译器兼容诊断路径，并清理残留 useState 注释示例。
  • 动态生成的任意 HTML 字符串仍不支持，框架没有因此增加运行时模板编译器。

迁移 ​

Core 与 Vite 插件必须一起升级：

bash
pnpm up @elfui/core@0.1.0-beta.7 @elfui/vite-plugin@0.1.0-beta.7

删除 html、css import，并把 tagged-template 直接移入宏调用：

ts
import { defineHtml, defineStyle } from "@elfui/core";

defineStyle(`:host { display: block; }`);
export const Button = defineHtml(`<button><slot></slot></button>`);

外部样式仍可使用 defineStyle(baseStyle, themeStyle)。升级后继续使用旧 import 会产生 TypeScript 或打包错误。

本页记录 ElfUI 框架固定版本组中面向用户的变化，包括 @elfui/shared、@elfui/reactivity、 @elfui/runtime、@elfui/compiler-template、@elfui/compiler、@elfui/core 和 @elfui/vite-plugin。

ElfUI 目前仍处于 beta 阶段。请让 @elfui/core 和 @elfui/vite-plugin 始终使用完全相同的版本。 当版本涉及编译器与运行时协议变化时，不支持混用不同版本。

v0.1.0-beta.6 — 2026-07-21 ​

统一应用入口 ​

  • 普通应用和组件库现在只需要把 @elfui/core 声明为直接运行时依赖。
  • Core 统一提供稳定的 runtime、响应式、生命周期、模型、指令、插件和内置渲染 API。
  • 编译器生成的 helper 改为使用 @elfui/core/internal。该子入口属于编译器内部协议，业务代码不得手写导入。
  • @elfui/runtime、@elfui/reactivity 和 @elfui/shared 仍会独立发布，供底层或脱离组件运行时的场景使用；普通应用不需要直接声明它们。
bash
pnpm add @elfui/core@0.1.0-beta.6
pnpm add -D @elfui/vite-plugin@0.1.0-beta.6

公共 API 与类型修正 ​

  • @elfui/core 现在公开 directive()，以及 onMounted()、onUnmounted() 等生命周期 API。
  • 可写 Ref、计算值和模型的 set() 返回值统一为 void，可以直接用于声明返回 void 的回调。
  • defineEmits<Interface>() 支持有限事件接口和只读事件名称数组。
  • defineExpose<Interface>() 支持普通有限键接口，不再要求字符串索引签名。
  • 改进指令泛型、基础类型 prop 构造器、模型值和严格可选属性的类型推断。
  • 运行时 useModel() 组合式函数不再被编译器误判为已移除的宏别名。

编译器与集成稳定性 ​

  • 编译产物的 helper 与公开 Core 入口之间建立了统一、可版本化的内部边界。
  • 加强模板引用、事件契约、列表/控制流值和源码诊断的回归测试。
  • 发布门禁覆盖外部 Canvas/SVG/WebGL 工具、Floating UI 类浮层、Observer、Worker/WASM 资源、重复挂载卸载清理以及多 runtime 副本。
  • 在真实浏览器中验证原生 Custom Elements，以及 React、Vue、Svelte 和 Angular 宿主集成契约。

升级说明 ​

Core 和 Vite 插件必须一起升级，然后重新安装依赖并清理 Vite 依赖缓存：

bash
pnpm up @elfui/core@0.1.0-beta.6 @elfui/vite-plugin@0.1.0-beta.6
pnpm install

如果还残留旧的预构建结果，请删除 node_modules/.vite 或重启 Vite。以下报错通常意味着项目正在混用 beta.6 源码和更早的包：

  • does not provide an export named 'directive'
  • Found ElfUI component pragma, but no import from "elfui"

当 Core 和插件都升级到 beta.6 后，宏组件应从 @elfui/core 导入；不要为了绕过旧插件警告而改回旧的 elfui 导入。

v0.1.0-beta.5 — 2026-07-21 ​

  • 稳定编译模板集成以及编译器/runtime 代码生成一致性。
  • 改进模板引用的可移植性和嵌套运行时值的自动解包。
  • 增加生成式宏组件和开发期源码元数据的回归覆盖。

v0.1.0-beta.4 — 2026-07-17 ​

  • 加固 mounted/unmounted 生命周期与外部资源清理边界。
  • 增加外部工具、React、Vue、Svelte、Angular、原生 Custom Elements 和多 runtime 副本的浏览器集成矩阵。
  • 扩展组件树、响应式副作用、模板绑定、模型/控制流和源码位置的 DevTools 元数据。
  • 增加 SSR、开发环境边界、生成代码、体积、发布产物和浏览器发布门禁。
  • 改进 prop 推断、数组副作用追踪、事件契约、插值解析、宿主属性、指令和 Observer 目标处理。

v0.1.0-beta.3 — 2026-07-14 ​

  • 修复预发布流程，确保 workspace 依赖能够安全解析为已发布包。
  • 增加依赖扫描和 CodeQL 自动化。
  • 完善 README 链接与项目品牌资源。

v0.1.0-beta.2 — 2026-07-12 ​

  • 确立 @elfui/core 作为宏组件包名。
  • 补齐公开包元数据、各包 README、exports 和发布产物验证。
  • 改为由版本标签触发可信发布，并修复 CI workspace 链接与编译器全局常量处理。

v0.1.0-beta.1 — 2026-07-12 ​

  • 发布首个公开 beta 固定版本组。
  • 建立编译器优先的宏组件、响应式、Custom Element runtime 和 Vite 插件初始基线。

该历史条目保持简短，因为它早于基于标签的版本记录流程。从 beta.6 开始，每次发布前都应在本页补充面向用户的变化、 兼容性影响和迁移要求。