メインコンテンツへスキップ

ハンドル

はじめに​

Playwright は、ページ DOM 要素またはページ内のその他のオブジェクトへのハンドルを作成できます。これらのハンドルは Playwright プロセス内に存在しますが、実際のオブジェクトはブラウザ内に存在します。ハンドルには 2 種類あります。

  • JSHandle : ページ内の任意の JavaScript オブジェクトを参照します。
  • ElementHandle : ページ内の DOM 要素を参照します。要素に対してアクションを実行したり、そのプロパティをアサートしたりするための追加メソッドがあります。

ページ内の DOM 要素は JavaScript オブジェクトでもあるため、すべての ElementHandle は JSHandle でもあります。

ハンドルは、ページ内の実際のオブジェクトに対して操作を実行するために使用されます。ハンドルで評価したり、ハンドルのプロパティを取得したり、評価パラメータとしてハンドルを渡したり、ページオブジェクトを JSON にシリアライズしたりできます。これらのメソッドについては、JSHandle クラス API を参照してください。

API リファレンス​

JSHandle を取得する最も簡単な方法を次に示します。

var jsHandle = await page.EvaluateHandleAsync("window");
//  Use jsHandle for evaluations.

Element Handle (要素ハンドル)​

非推奨

ElementHandle の使用は推奨されません。代わりに Locator オブジェクトと Web ファーストのアサーションを使用してください。

ElementHandle が必要な場合は、Page.WaitForSelectorAsync() または Frame.WaitForSelectorAsync() メソッドを使用して取得することをお勧めします。これらの API は、要素がアタッチされ、表示されるまで待機します。

// Get the element handle
var jsHandle = await page.WaitForSelectorAsync("#box");
var elementHandle = jsHandle as ElementHandle;

// Assert bounding box for the element
var boundingBox = await elementHandle.BoundingBoxAsync();
Assert.AreEqual(100, boundingBox.Width);

// Assert attribute for the element
var classNames = await elementHandle.GetAttributeAsync("class");
Assert.True(classNames.Contains("highlighted"));

パラメータとしてのハンドル​

ハンドルは、Page.EvaluateAsync() および同様のメソッドに渡すことができます。次のスニペットは、ページ内に新しい配列を作成し、データで初期化し、この配列へのハンドルを Playwright に返します。その後、後続の評価でハンドルを使用します。

// Create new array in page.
var myArrayHandle = await page.EvaluateHandleAsync(@"() => {
    window.myArray = [1];
    return myArray;
}");

// Get the length of the array.
var length = await page.EvaluateAsync<int>("a => a.length", myArrayHandle);

// Add one more element to the array using the handle
await page.EvaluateAsync("arg => arg.myArray.add(arg.newElement)",
    new { myArray = myArrayHandle, newElement = 2 });

// Release the object when it is no longer needed.
await myArrayHandle.DisposeAsync();

ハンドルのライフサイクル​

ハンドルは、Page.EvaluateHandleAsync()、Page.QuerySelectorAsync()、Page.QuerySelectorAllAsync() などのページメソッド、またはフレームの対応するメソッド Frame.EvaluateHandleAsync()、Frame.QuerySelectorAsync()、Frame.QuerySelectorAllAsync() を使用して取得できます。作成されたハンドルは、ページがナビゲートするか、JsHandle.DisposeAsync() メソッドを介して手動で破棄されない限り、ガベージコレクションからオブジェクトを保持します。

API リファレンス​

Locator vs ElementHandle (ロケーター vs 要素ハンドル)​

注意

ElementHandle の使用は、静的なページで広範囲な DOM トラバーサルを実行する必要があるまれな場合にのみ推奨されます。すべてのユーザーアクションとアサーションには、代わりにロケーターを使用してください。

Locator と ElementHandle の違いは、後者が特定の要素を指すのに対し、Locator はその要素を取得する方法のロジックをキャプチャすることです。

以下の例では、ハンドルはページ上の特定の DOM 要素を指しています。その要素のテキストが変更されたり、React によって完全に異なるコンポーネントをレンダリングするために使用されたりした場合でも、ハンドルは依然としてその古い DOM 要素を指しています。これにより、予期しない動作が発生する可能性があります。

var handle = await page.QuerySelectorAsync("text=Submit");
await handle.HoverAsync();
await handle.ClickAsync();

ロケーターを使用すると、ロケーターが使用されるたびに、セレクターを使用して最新の DOM 要素がページ内で特定されます。したがって、以下のスニペットでは、基になる DOM 要素が 2 回特定されます。

var locator = page.GetByText("Submit");
await locator.HoverAsync();
await locator.ClickAsync();