デコレータ

デコレータは、クラスの動作を宣言的に注釈付けし、変更するために使用できる関数です。

Litは、要素の登録、リアクティブプロパティとクエリプロパティの定義、イベントハンドラメソッドへのイベントオプションの追加など、宣言的なAPIを有効にするオプションのデコレータセットを提供します。

たとえば、@customElementデコレータと@property()デコレータを使用すると、カスタム要素を登録し、リアクティブプロパティをコンパクトで宣言的な方法で定義できます。

@customElement('my-element')
export class MyElement extends LitElement {

  @property()
  greeting = 'Welcome';

}

lit/decorators.jsモジュールを介してすべてのLitデコレータをインポートできます

import {customElement, property, eventOptions, query} from 'lit/decorators.js';

コンポーネントを実行するために必要なコードの量を減らすために、デコレータをコンポーネントコードに個別にインポートできます。 すべてのデコレータは、lit/decorators/<decorator-name>.jsで使用できます。 例えば、

import {customElement} from 'lit/decorators/custom-element.js';
import {eventOptions} from 'lit/decorators/event-options.js';

デコレータを使用するには、TypeScriptまたはBabelなどのコンパイラでコードをビルドする必要があります。

将来的にデコレータがブラウザでネイティブにサポートされるようになれば、これは不要になります

TypeScriptは、実験的デコレータと標準デコレータの両方をサポートしています。 最適なコンパイラ出力のために、TypeScript開発者は今のところ実験的デコレータを使用することをお勧めします。 プロジェクトで標準デコレータを使用する必要がある場合、または"useDefineForClassFields": trueを設定する必要がある場合は、標準デコレータへの移行までスキップしてください。

実験的デコレータを使用するには、experimentalDecoratorsコンパイラオプションを有効にする必要があります。

また、useDefineForClassFields設定がfalseであることを確認する必要があります。 これは、targetがES2022以上に設定されている場合にのみ必要ですが、これを明示的にfalseに設定することをお勧めします。 これは、プロパティを宣言するときにクラスフィールドの問題を回避するために必要です。

// tsconfig.json
{
  "compilerOptions": {
    "experimentalDecorators": true,
    "useDefineForClassFields": false,
  }
}

emitDecoratorMetadataの有効化は必須ではなく、推奨されません。

Litデコレータは、TypeScriptの実験的デコレータモードで標準デコレータ構文（デコレータ付きクラスフィールドにaccessorを使用）をサポートするように設計されています。

これにより、動作を変更せずに、デコレータされたプロパティにaccessorキーワードを追加することから始めて、実験的デコレータから段階的に移行できます。 すべてのデコレータ付きクラスフィールドでaccessorキーワードを使用したら、コンパイラオプションを変更して標準デコレータへの移行を完了できます。

// tsconfig.json
{
  "compilerOptions": {
    "experimentalDecorators": false, // default for TypeScript 5.0 and up
    "useDefineForClassFields": true, // default when "target" is "ES2022" or higher
  }
}

注：accessorキーワードはTypeScript 4.9で導入され、メタデータ付きの標準デコレータにはTypeScript≧5.2が必要です。

Babelは、バージョン7.23以降、@babel/plugin-proposal-decoratorsプラグインを使用して標準デコレータをサポートしています。 BabelはTypeScript実験的デコレータをサポートしていないため、デコレータされたクラスフィールドでaccessorキーワードを使用して、標準デコレータ構文でLitデコレータを使用する必要があります。

これらのBabel設定で@babel/plugin-proposal-decoratorsを追加することにより、デコレータを有効にします

// babel.config.json
{
  "plugins": [
    ["@babel/plugin-proposal-decorators", {"version": "2023-05"}]
  ]
}

注：Litデコレータは、"version": "2023-05"でのみ機能します。 以前サポートされていた"2018-09"を含む他のバージョンはサポートされていません。

デコレータは、ECMAScript標準に追加するためのステージ3の提案です。 BabelやTypeScriptなどのコンパイラはデコレータをサポートしていますが、ブラウザはまだ実装していません。 LitデコレータはBabelとTypeScriptで動作し、ブラウザがネイティブに実装したときにも動作します。

TC39の提案がステージ3に達する前は、コンパイラは以前のバージョンのデコレータ仕様を実装していました。

これらの中で最も注目すべきは、TypeScriptの_実験的デコレータ_であり、Litは開始以来サポートしており、現在使用することをお勧めしています。

Babelは、デコレータプラグインの"version"オプションからわかるように、時間の経過とともにさまざまなバージョンの仕様をサポートしてきました。 以前は、Lit 2はBabelユーザー向けに"2018-09"バージョンをサポートしていましたが、現在は以下で説明する_標準_"2023-05"バージョンに置き換えられました。

_標準デコレータ_ は、ECMAScript / JavaScriptを定義する機関であるTC39でステージ3のコンセンサスに達したデコレータのバージョンです。

標準デコレータは、TypeScriptとBabelでサポートされており、近い将来、ネイティブブラウザでもサポートされる予定です。

標準デコレータと実験的デコレータの最大の違いは、パフォーマンス上の理由から、標準デコレータはデコレータされ、置き換えられるクラスメンバー（フィールド、アクセサー、メソッド）の_種類_ を変更できず、同じ種類のメンバーのみを生成することです。

多くのLitデコレータはアクセサーを生成するため、これはデコレータをクラスフィールドではなくアクセサーに適用する必要があることを意味します。

これを便利にするために、標準デコレータ仕様では、"自動アクセサー"を宣言するためのaccessorキーワードが追加されています。

class MyClass {
  accessor foo = 42;
}

自動アクセサーは、プライベートフィールドを読み書きするゲッターとセッターのペアを作成します。 デコレータは、これらのゲッターとセッターをラップできます。

実験的デコレータでクラスフィールドで機能するLitデコレータ（@property()、@state()、@query()など）は、標準デコレータではアクセサーまたは自動アクセサーに適用する必要があります。

@customElement('my-element')
export class MyElement extends LitElement {

  @property()
  accessor greeting = 'Welcome';

}

標準デコレータのコンパイラ出力は、アクセサ、プライベートストレージ、およびデコレータAPIの一部であるその他のオブジェクトを生成する必要があるため、残念ながら大きくなってしまいます。

そのため、デコレータを使用したいユーザーは、可能な場合は、TypeScriptの実験的なデコレータを今のところ使用することをお勧めします。

Litチームは、将来、標準デコレータをよりコンパクトなコンパイラ出力にコンパイルするために、オプションのLitコンパイラにデコレータ変換を追加することを計画しています。ネイティブブラウザのサポートにより、コンパイラ変換の必要性もなくなります。

このページを編集