Lit 3 アップグレードガイド

Lit 3.0 は、Lit 2.x からの破壊的変更が非常に少ないです

• IE11 はサポートされなくなりました。
• Lit の npm モジュールは、ES2021 として公開されるようになりました。
• Lit 2.x のリリースで非推奨とマークされた API は削除されました。
• SSR ハイドレーションサポートモジュールは、@lit-labs/ssr-client パッケージに移動しました。
• 型のみ: ReactiveElement の renderRoot と createRenderRoot() の型が更新されました。
• Babel デコレータのバージョン "2018-09" のサポートが削除されました。
• TypeScript の実験的デコレータと標準デコレータの間で、デコレータの動作が統一されました。
  • その結果、TypeScript を使用している場合は、両方の種類のデコレータの更新された型を取得するために、少なくとも TypeScript v5.2 にアップグレードする必要があります。

ほとんどのユーザーにとって、Lit 2 から Lit 3 へのアップグレードに必要なコード変更はありません。ほとんどのアプリとライブラリは、"^2.7.0 || ^3.0.0" のように、npm バージョン範囲を拡張して 2.x と 3.x の両方を含めることができます。

Lit 2.x と 3.0 は相互運用可能です。Lit のあるバージョンからのテンプレート、基本クラス、ディレクティブは、別のバージョンのものと連携します。

Lit 2 は ES2019 として公開され、Lit 3 は最新のブラウザとビルドツールで広くサポートされている ES2021 として公開されています。古いブラウザバージョンをサポートする必要があり、現在のツールが ES2021 を解析できない場合は、これは破壊的変更となる可能性があります。

Webpack 4 の内部パーサーは、ES2021 で導入された構文である nullish 合体演算子 (??)、論理代入 (??=)、オプションチェーン (?.) をサポートしていないため、それらに遭遇すると Module parse failed: Unexpected token をスローします。

推奨される解決策は、これらの新しい JS 構文の解析をサポートする Webpack 5 にアップグレードすることです。ただし、それができない場合は、babel-loader を使用して Lit 3 コードを変換し、Webpack 4 で動作させることができます。

Webpack 4 で Lit 3 をトランスパイルするには、次の必要な babel パッケージをインストールします

> npm i -D babel-loader@8 \
    @babel/plugin-transform-optional-chaining \
    @babel/plugin-transform-nullish-coalescing-operator \
    @babel/plugin-transform-logical-assignment-operators

そして、次のものと同様の新しいルールを追加します（プロジェクトに応じて変更が必要になる場合があります）

// In webpack.config.js

module.exports = {
  // ...

  module: {
    rules: [
      // ... your other rules

      // Add a babel-loader rule to downlevel Lit's ES2021 syntax so Webpack 4 can parse it.
      // TODO: Once on Webpack 5, this rule can be deleted.
      {
        test: /\.js$/,
        include: ['@lit', 'lit-element', 'lit-html'].map((p) =>
          path.resolve(__dirname, 'node_modules/' + p)
        ),
        use: {
          loader: 'babel-loader',
          options: {
            plugins: [
              '@babel/plugin-transform-optional-chaining',
              '@babel/plugin-transform-nullish-coalescing-operator',
              '@babel/plugin-transform-logical-assignment-operators'
            ],
          },
        },
      },
    ],
  }
}

JavaScript デコレータは最近、TC39 によって標準化され、4 段階の標準化プロセスのステージ 3 にあります。ステージ 3 は、VM やコンパイラなどの JavaScript 実装が安定した仕様を実装し始める段階です。TypeScript 5.2 と Babel 7.23 は最近、標準を実装しました。

つまり、標準デコレータ、TypeScript の実験的デコレータ、および Babel が実装した以前の提案（バージョン "2018-09" など）など、複数のバージョンのデコレータ API が存在します。

Lit 2 は TypeScript の実験的デコレータと Babel の "2018-09" デコレータをサポートしていましたが、Lit 3 は標準デコレータと TypeScript の実験的デコレータをサポートするようになりました。

Lit 3 のデコレータは、Lit 2 の TypeScript デコレータとほぼ下位互換性があります。- **ほとんどの場合、変更は必要ありません**。

実験的モードと標準デコレータモードの両方で Lit デコレータの動作を統一するために、いくつかの小さな破壊的変更が必要でした。

Lit 3.0 での Lit デコレータの動作の変更

• 以前はセッターの責任であった @property() と @state() でデコレートされたアクセサーに対して、requestUpdate() が自動的に呼び出されるようになりました。
• アクセサーの値は最初のレンダリング時に読み取られ、changedProperties と属性の反映の初期値として使用されます。
• Lit 3 デコレータは、@babel/plugin-proposal-decorators の version: "2018-09" オプションをサポートしなくなりました。Babel ユーザーは標準デコレータに移行する必要があります。
• [オプション]: 標準デコレータへの移行を支援するために、@property() と @state() を手書きのアクセサーのセッターに移行することをお勧めします。

Lit 2.x プロジェクトに非推奨警告がない場合は、このリストの影響を受けることはありません。

• ReactiveElement の UpdatingElement エイリアスを削除しました。
• メインの lit-element モジュールからのデコレータの再エクスポートを削除しました。
• queryAssignedNodes デコレータの非推奨の呼び出しシグネチャを削除しました。
• lit、lit-element、lit-html から、実験的なサーバーサイドレンダリングのハイドレーションモジュールを @lit-labs/ssr-client に移動しました。

UpdatingElement を ReactiveElement に置き換えます。これは、UpdatingElement が ReactiveElement のエイリアスであったため、機能的な変更ではありません。

// Removed
import {UpdatingElement} from 'lit';

// Updated
import {ReactiveElement} from 'lit';

Lit 3.0 のビルトインデコレータは、lit-element によってエクスポートされなくなり、代わりに lit/decorators.js からインポートする必要があります。

// Removed decorator exports from lit-element
import {customElement, property, state} from 'lit-element';

// Updated
import {customElement, property, state} from 'lit/decorators.js';

セレクターを受け取る queryAssignedNodes の使用を queryAssignedElements に移行します。

// Removed
@queryAssignedNodes('list', true, '.item')

// Updated
@queryAssignedElements({slot: 'list', flatten: true, selector: '.item'})

セレクターのない使用は、オプションオブジェクトを受け取る必要があります。

// Removed
@queryAssignedNodes('list', true)

// Updated
@queryAssignedNodes({slot: 'list', flatten: true})

実験的なハイドレーションサポートは、コアライブラリから @lit-labs/ssr-client に移動しました。

// Removed
import 'lit/experimental-hydrate-support.js';
import {hydrate} from 'lit/experimental-hydrate.js';

// Updated
import '@lit-labs/ssr-client/lit-element-hydrate-support.js';
import {hydrate} from '@lit-labs/ssr-client';

これは、ランタイムへの影響のない型のみの変更です。

ReactiveElement.renderRoot の型は Element | ShadowRoot から HTMLElement | DocumentFragment に変更され、ReactiveElement.createRenderRoot() の戻り値の型は HTMLElement | ShadowRoot から HTMLElement | DocumentFragment に変更されました。これにより、それらは互換性を持つようになり、lit-html の render() とも一貫性を持つようになりました。

この変更は、単に this.renderRoot にアクセスするコードには一般的に影響を与えません。ただし、以前の型に対して明示的な型注釈があったコードは更新する必要があります。

Lit 3 は標準デコレータのサポートを追加しますが、TypeScript ユーザーは実験的デコレータを使用することをお勧めします。これは、TypeScript と Babel のコンパイラからの標準デコレータのエミットされたコードが現在非常に大きいためです。

ブラウザが標準デコレータをサポートするか、新しい Lit コンパイラでデコレータ変換サポートをリリースしたときに、本番環境で標準デコレータをお勧めします。

しかし、標準デコレータを今すぐ試すことができ、TypeScript 5.2 以降と @babel/plugin-proposal-decorators プラグインを使用する Babel 7.23 で動作します。

TypeScript 5.2以降をインストールし、`tsconfig`ファイルに` "experimentalDecorators"`の設定が存在する場合は削除してください。

Babel 7.23以降と@babel/plugin-proposal-decoratorsをインストールしてください。プラグインには"version": "2023-05"オプションを必ず渡してください。

標準デコレータは、デコレートするクラスメンバーの種類を変更することはできません。ゲッターとセッターを作成する必要があるデコレータは、既存のゲッターとセッターに適用する必要があります。これをより人間工学的にするために、デコレータ標準では、クラスフィールドに適用されると「自動アクセサ」を作成するaccessorキーワードを追加しています。自動アクセサはクラスフィールドと非常によく似ていますが、プライベートストレージによってバックアップされたプロトタイプにアクセサを作成します。

@property()、@state()、@query()、@queryAll()、@queryAssignedElements()、および@queryAssignedNode()デコレータには、accessorキーワードが必要です。

例

class MyElement extends LitElement {
  @property()
  accessor myProperty = "initial value"
...
}

標準デコレータは、直接適用されているクラスメンバーのみを置き換えることができます。Litデコレータはプロパティの設定をインターセプトする必要があるため、デコレータはセッターに適用する必要があります。これは、ゲッターにデコレータを適用するというLit 2の推奨事項とは異なります。

@property()と@state()では、これは自動的に行われるため、セッター内のthis.requestUpdate()呼び出しを削除することもできます。requestUpdate()を呼び出さないようにする必要がある場合は、noAccessorプロパティオプションを使用する必要があります。

@property()と@state()では、プロパティを設定するときに、古い値を取得するためにデコレータによってゲッターが呼び出されることに注意してください。これは、ゲッターとセッターの両方を定義する必要があることを意味します。

変更前

class MyElement extends LitElement {
  private _foo = 42;
  set(v) {
    const oldValue = this._foo;
    this._foo = v;
    this.requestUpdate('foo', oldValue);
  }
  @property()
  get() {
    return this._foo;
  }
}

変更後

class MyElement extends LitElement {
  private _foo = 42;
  @property()
  set(v) {
    this._foo = v;
  }
  get() {
    return this._foo;
  }
}

このページを編集する