拥抱 ES 装饰器

Gem 的 v1.x.x 版本支持 TypeScript 的实验性装饰器,装饰器为用户提供了非常友好的开发体验。 现在 ES 的装饰器提案已经进入 State 3 阶段, 各个浏览器供应商、构建工具都进行了各自的实现,从 v2 开始,Gem 将使用 ES 装饰器实现, 让你用 JavaScript 写的自定义元素也具备良好的类型支持。

import { GemElement, customElement, html } from '@mantou/gem';
import { attribute, property, emitter } from '@mantou/gem';

@customElement('my-element')
class MyElement extends GemElement {
  @attribute
  src;

  @property
  callback = () => {};

  @emitter
  error;

  render = () => {
    return html`<div @click=${this.callback}>${this.src}</div>`;
  };
}

NOTE

  • esbuild >= 0.21.2, target 不要使用默认 esnext
  • vite >= 5.3
  • typescript >= 5.0
  • Chrome bug track
  • Firefox bug track

和 TS 装饰器的差异

TS 的字段装饰器在类定义之后立即执行,能很方便的在原型对象上定义访问器属性。 而 ES 的字段装饰器必须使用 accessor 才能达到类似的效果,就算使用 accessor 也将使 Gem 丧失部分功能。 所以 Gem 使用了特殊的方式来现实,使他看起来和 TS 装饰器没有任何区别, 实际上,这些装器返回的初始化函数将在每次实例化 MyElement 时运行,可以检查 tsc 编译后的代码:

let MyElement = (() => {
  return class MyElement extends _classSuper {
    src = __runInitializers(this, _src_initializers, void 0);
  };
})();

使用装饰器元数据

v1.x 使用了许多静态属性来记录元素的样式等其他特性,它们会增加学习成本,所以 v2 将它们使用 Decorator Metadata 代替。当外部需要获取元素的这些特性时(例如 Gem Devtools),可以使用 Symbol.metadata 进行访问。

使用 ES 装饰器的缺陷

@attribute 不再通过 observedAttributes 进行工作,而是拦截 setAttribute,在 DevTools 中修改时不使用修改后的 setAttribute,所以在 DevTools 中修改元素 Attribute 不能触发元素更新。

NOTE

安装浏览器扩展 Gem DevTools 将解决这一问题