カスタム要素のライフサイクルとアップグレード

定義・アップグレード：要素が「中身を得る」瞬間

カスタム要素は、customElements.define("my-card", MyCard) でタグ名とクラスを結びつけて初めて振る舞いを持ちます。重要なのは、定義より前にDOMへ書かれていてもエラーにならないことです。パーサは未知のハイフン入りタグを HTMLElement（正確には HTMLUnknownElement ではなく未定義のカスタム要素）として生成し、画面に存在はするが振る舞いを持たない状態で置いておきます。これを**未定義（undefined）**の要素と呼びます。

define が呼ばれると、ブラウザは文書中の同名タグをすべて探し、**アップグレード（upgrade）**します。アップグレードとは、既存の要素インスタンスに対してそのクラスのコンストラクタを実行し、プロトタイプを差し替えて「中身のある」カスタム要素に格上げする処理です。だから「要素を先に書く／define を先に呼ぶ」のどちらでも最終結果は同じになります。これがフレームワーク非依存で宣言的に使える理由です。基礎となる独自タグの考え方は Web コンポーネント に、要素がぶら下がる木構造は DOMツリーの内部構造 にまとまっています。

コンストラクタの制約：ここで属性に触ってはいけない

アップグレードでもパースでも、最初に走るのはクラスの constructor です。仕様はここに厳しい制約を課します。コンストラクタ内では 属性や子要素を読んだり付けたりしてはならず、super() 以外で要素の状態をほぼ変えられません。理由は、document.createElement("my-card") のようにまだ属性も子も無い空の状態で呼ばれる経路があり、そこで属性を前提にすると破綻するからです。実務では、コンストラクタは Shadow ルートの attachShadow と内部構造の用意までに留め、属性に依存する初期化は connectedCallback で行うのが定石です（Shadow DOM の境界は Shadow DOMのカプセル化とスロット合成 を参照）。

class MyCard extends HTMLElement {
  static observedAttributes = ["label", "disabled"];

  constructor() {
    super();
    // OK：Shadowルートと内部骨格の用意まで
    this.attachShadow({ mode: "open" });
    // NG例：this.getAttribute("label") / this.innerHTML = ... はここで触らない
  }

  connectedCallback() {
    // 接続時に属性を読んで描画する
    this.render();
  }

  attributeChangedCallback(name, oldVal, newVal) {
    if (oldVal !== newVal) this.render();
  }
}
customElements.define("my-card", MyCard);

コールバックの発火順序

ライフサイクルコールバックは4種あり、呼ばれる順序には明確な規則があります。

肝心なのは「接続時に何が先に来るか」です。パース由来で属性付きに生成された要素では、コンストラクタ → observed 属性ぶんの attributeChangedCallback（初期値、oldValue は null）→ connectedCallback の順になります。つまり connectedCallback の時点で初期属性は既に反映済みと考えてよい設計です。一方、createElement で空に作ってから後で属性を setAttribute し、その後 appendChild した場合は、attributeChanged が接続より前に走り、最後に connectedCallback が来ます。いずれにせよ observed 属性の変化通知は connectedCallback より前に処理されるのが原則です。

接続・切断は移動でも対で呼ばれる点に注意します。要素を別の親へ appendChild で移すと、ブラウザは内部的に旧位置からの除去（disconnectedCallback）→新位置への挿入（connectedCallback）を行います。連続して同一タスク内で起きるため、状態を持つ部品では「切断＝破棄」と決めつけず、this.isConnected で実際の接続状態を確認するのが安全です。

未定義要素の扱いとちらつき対策

define 前の未定義要素は、CSS から :defined / :not(:defined) 擬似クラスで狙えます。これを使うと、定義が済むまで未定義要素を隠すことで、属性反映前の素のテキストが一瞬見える「ちらつき（FOUC 的な未スタイル表示）」を防げます。

/* 定義が完了するまで、未定義のカスタム要素を隠す */
my-card:not(:defined) {
  visibility: hidden;
}

未定義要素は HTML 的にはインライン要素扱いで、display の既定値も標準要素とは異なります。中身を持たない箱として存在し、getAttribute などDOM API は通常どおり使えますが、クラス由来のメソッドやゲッタはアップグレード後にしか生えません。customElements.whenDefined() で定義完了を待ってから処理を進めると、未定義状態への依存を避けられます。

フォーム関連API：ElementInternals でネイティブ部品になる

既定のカスタム要素はフォーム送信に参加しません。<form> の中に置いても値が送られず、:disabled 連動も効きません。これを解決するのが**フォーム関連カスタム要素（form-associated custom element）**です。クラスに static formAssociated = true を宣言し、コンストラクタで this.internals = this.attachInternals() を呼んで ElementInternals を取得すると、ネイティブのフォーム部品と同じように振る舞えます。

class MyInput extends HTMLElement {
  static formAssociated = true;

  constructor() {
    super();
    this.internals = this.attachInternals();
  }

  set value(v) {
    // フォーム送信に乗る値を設定（name=... の値になる）
    this.internals.setFormValue(v);
  }

  formResetCallback() {
    this.value = "";
  }
  formDisabledCallback(disabled) {
    // 親 fieldset/form の disabled 連動を受け取る
    this.toggleAttribute("aria-disabled", disabled);
  }
}
customElements.define("my-input", MyInput);

setFormValue で送信値を持たせ、internals.setValidity(...) で**制約検証（constraint validation）**に参加できます。これにより form.checkValidity() や :invalid 擬似クラスがネイティブ要素と同列に効きます（HTML 標準の検証機構は フォーム入力検証 を参照）。フォーム関連要素には、通常のライフサイクルに加えて専用コールバックが増えます。

まとめ