开发
下面的方法来提高 Gem 开发体验。
HTML CSS 模版语言支持
安装扩展:
自动格式化
Prettier
prettier 默认支持内联 html/css 模版,但不支持 css({}),使用下面的命令安装 prettier
以支持这种样式的格式化:
pnpm add -D prettier@npm:@mantou/prettierBiome
Biome v2 默认支持内联 html/css 模版,但不支持 css({})。
HMR
通过
unplugin-gem(推荐)
在有 JS HMR host 的构建工具中开启 hot,并启用 hmr。插件会自动注入 @mantou/gem/helper/hmr:
unpluginGem({
hmr: true,
});完整的 JavaScript HMR 仍需要 host 提供 import.meta.webpackHot(webpack/Rspack)或 import.meta.hot(Vite / 实验性 Rolldown)。Rollup 和 esbuild 只会注入运行时,以保持类更新兼容。
SWC 插件
- 在构建工具中开启
hot,例如 Webpack - 在构建工具配置中入口添加
@mantou/gem/helper/hmr(必须在任何元素类定义之前执行) - 在 SWC 插件配置中开启
hmr(true/"webpack-hot"、"import-meta-hot"或"module-hot")
支持范围
能正确热更新:
- 方法、getter/setter、箭头函数字段的函数体(包括私有和静态成员),例如模板、
@effect、@memo的内容及其依赖,以及构造函数体(对之后创建的元素生效) - 增删没有装饰器的方法、getter/setter、箭头函数字段(包括私有和静态成员)
- 增删
@attribute、@property、@emitter、@state、@part、@slot字段 - 样式(
@adoptedStyle、css),支持 Light DOM - 模块顶层的常量和函数
- 保留状态:元素实例的字段和
createState,以及模块顶层createStore创建的 store - 更新后的代码中使用
new MyElement()创建元素
会刷新页面:
- 增删带装饰器的方法或函数字段(例如
@effect、@template),增删构造函数 - 增删没有装饰器的普通实例字段
- 修改
@shadow、@light({ penetrable })、@async @connectStore连接的 store 有增减,或者连接的是本地 store、但不是模块顶层createStore创建的- 构造函数中有
super(参数)、new.target、TS 参数属性或带值的return
能热更新,但不保证可靠:
- 除
@effect、@memo依赖外,装饰器参数的修改不生效,例如@template的条件和@aria - 字段初始值、store 初始值的修改不生效,因为它们被当作状态保留
- 模块顶层除
createStore外的可变变量(例如let变量、用作缓存的Map)会在模块更新后重置 - 静态字段值的修改只对模块内通过类名读取生效,通过
this.constructor、customElements.get()读取的仍是旧值 - 计算属性名的成员不参与热更新
- 模块顶层的副作用会重复执行,例如事件监听、定时器、入口中的
render - 修改过的模板字面量(
html)对应的 DOM 会重建,其中的输入框焦点、子元素状态等会丢失;未修改的模板会复用已有 DOM - 父类更新时,新增字段只会添加到当前更新标签的实例上
- 没有元素定义的模块(工具函数、store 模块)更新后会交给导入它的模块处理,不在这条更新链上的其他模块仍使用旧版本
