コンポーネントが所有する要素へのアクセス

コンポーネントによって表示された要素に標準の DOM API でアクセスするには、querySelector() と、this.template または this を使用します。セレクタを使わずに DOM 内の要素を探すには、ref を使用します。

querySelector()

DOM で要素へアクセスするための一般的な方法は、querySelector() を使用することです。Shadow DOM ノードを探すには、this.template の querySelector() または querySelectorAll() を使用します。Light DOM ノードの場合は、this でいずれかのメソッドを使用します。

1// shadow DOM
2this.template.querySelector("div");
3
4// light DOM
5this.querySelector("div");

{element}.template.querySelector を使用することもできます。

Note

コンポーネントが表示した要素を探すには、これらのメソッドを使用します。

要素の順序は保証されません。
DOM に表示されない要素は、querySelector の結果で返されません。
querySelector で ID セレクタは使用しないでください。HTML テンプレートに定義した ID は、テンプレートの表示時にグローバルに一意な値に変換される場合があります。JavaScript の ID セレクタを使用する場合、その ID は、変換された ID に一致しません。
Light DOM コンポーネントの場合、this.querySelector() は、Light DOM の子など、即時テンプレート外の要素を検索します。より限定的なセレクタを使用して、メソッドの範囲を絞り込んでください。

1<!-- example.html -->
2<template>
3  <div>First <slot name="task1">Task 1</slot></div>
4  <div>Second <slot name="task2">Task 2</slot></div>
5</template>

1// example.js
2import { LightningElement } from "lwc";
3
4export default class Example extends LightningElement {
5  renderedCallback() {
6    this.template.querySelector("div"); // <div>First</div>
7    this.template.querySelector("span"); // null
8    this.template.querySelectorAll("div"); // [<div>First</div>, <div>Second</div>]
9  }
10}

DOM 要素のクエリでグローバルプロパティの window や document は使用しないでください。「DOM のアクセスコンテインメント」を参照してください。また、lightning/platformResourceLoader 経由でサードパーティライブラリを操作していない場合には、JavaScript を使用して DOM を操作することはお勧めできません。宣言コードを記述するときは、Lightning Web コンポーネントの HTML ディレクティブを使用した方がよいでしょう。

Important

ref

ref は、セレクタなしで DOM 要素を見つけ、指定されたテンプレートに含まれる要素のみを照会します。まず、lwc:ref ディレクティブを要素に追加し、値を割り当てます。その参照をコールするには、this.refs を使用します。次の例では、<div> 要素に lwc:ref="myDiv" ディレクティブがあり、実行時、this.refs によって参照され、<div> へのアクセスが行われます。

1<template>
2  <div lwc:ref="myDiv"></div>
3</template>

1export default class extends LightningElement {
2  renderedCallback() {
3    console.log(this.refs.myDiv);
4  }
5}

考慮事項

this.refs をコールするには、あらかじめディレクティブ lwc:ref を定義しておく必要があります。存在しない ref に this.refs をコールすると、undefined が返されます。テンプレートに lwc:ref ディレクティブが重複して含まれている場合、this.refs は最後の <div> を参照します。

1<template>
2  <div lwc:ref="myDiv"></div>
3  <div lwc:ref="myDiv"></div>
4</template>

this.refs は、参照のみのプレーンなオブジェクトです。そのコンポーネントの内部でプロパティを追加、変更、または削除しようとすると、ランタイムエラーが発生します。キーは文字列で、値は DOM 要素です。this.refs の構文は、Light DOM や Shadow DOM の要素を参照する場合と同じです。

ref は設定と書き込みが可能であるため、コンポーネントで定義された ref は LightningElement.prototype の ref を上書きします。

<template> 要素や、Light DOM の <slot> 要素に lwc:ref を適用することはできません。

1<template lwc:render-mode="light">
2  <template lwc:if={myTemplate} lwc:ref="myTemplate"></template>
3  <!-- Not allowed -->
4</template>

1<template lwc:render-mode="light">
2  <slot lwc:ref="mySlot"></slot>
3  <!-- Not allowed -->
4</template>

for:each や iterator:* ループの内に lwc:ref を置くと、テンプレートコンパイラでエラーが発生します。

1<template for:each={items} for:item="item">
2  <div key={item} lwc:ref="foo"></div>
3  <!-- Not allowed -->
4</template>

複数のテンプレート

this.refs は、複数テンプレートのコンポーネントでは、最後に表示されたテンプレートを参照します。テンプレートが変更されると、this.refs オブジェクトも変更されます。

1import a from "./a.html";
2import b from "./b.html";
3
4export default class extends LightningElement {
5  count = 0;
6
7  render() {
8    return this.count % 2 === 0 ? a : b;
9  }
10
11  renderedCallback() {
12    console.log(this.refs);
13  }
14
15  increment() {
16    this.count++;
17  }
18}
19
20const cmp = createElement("c-component", { is: Component });
21// Logs `this.refs` for a.html
22
23cmp.increment();
24// Logs `this.refs` for b.html
25
26cmp.increment();
27// Logs `this.refs` for a.html

<template lwc:if={boolean}> に基づいて要素を条件付きで定義するには、1 つの親テンプレートの下に複数の子テンプレートを作成します。この例では、this.refs.toggleDarkMode は、表示された子テンプレートの中の要素を参照します。

1<template>
2  <template lwc:if={darkMode}>
3    <button lwc:ref="toggleDarkMode">Enable Light Mode</button>
4  </template>
5  <template lwc:else>
6    <button lwc:ref="toggleDarkMode">Enable Dark Mode</button>
7  </template>
8</template>

関連トピック

Light DOM

The Japanese Summer '24 guide is now live

日本語の Summer '24 ガイドが公開されました! 「Component Reference (コンポーネントリファレンス)」は、以前と同様にコンポーネントライブラリにあります。