Playwright JSHandle 详解：表示页面内 JavaScript 对象及其完整 API

本文围绕 Playwright API 参考中的 JSHandle 类展开。JSHandle 是 Playwright 在「测试进程」与「浏览器进程」之间引用页面内任意 JavaScript 对象的桥梁：读完本文，你能掌握 JSHandle 的创建方式、生命周期与垃圾回收语义、全部 API 方法（evaluate、evaluateHandle、getProperties、getProperty、jsonValue、asElement、dispose）的多语言用法，以及参数序列化与跨进程传递的底层实现。

什么是 JSHandle

Playwright 可以为页面中的 DOM 元素或其他任意对象创建句柄（handle）。句柄本身存活在 Playwright 进程中，而真实对象存活在浏览器里。Playwright 有两种句柄：

• JSHandle：引用页面中的任意 JavaScript 对象；
• ElementHandle：引用页面中的 DOM 元素，在 JSHandle 基础上额外提供对元素执行操作与断言的方法。

由于页面中的任意 DOM 元素本身也是 JavaScript 对象，因此任何 ElementHandle 同时也是 JSHandle。这一继承关系在源码中直接体现：client/elementHandle.ts 中 class ElementHandle<T extends Node = Node> extends JSHandle<T>。

最直接的创建方式是 [method: Page.evaluateHandle]：

const windowHandle = await page.evaluateHandle(() => window);
// ...

JSHandle windowHandle = page.evaluateHandle("() => window");
// ...

window_handle = await page.evaluate_handle("window")
# ...

window_handle = page.evaluate_handle("window")
# ...

var windowHandle = await page.EvaluateHandleAsync("() => window");

除 evaluateHandle 外，Page.querySelector / Page.querySelectorAll 及其 Frame 对应方法也可以获得句柄（对 DOM 元素而言得到的是 ElementHandle）。

生命周期：引用保持与垃圾回收

API 文档对 JSHandle 生命周期有三条关键描述：

1. JSHandle 会阻止其引用的 JavaScript 对象被垃圾回收，除非句柄通过 [method: JSHandle.dispose] 释放；
2. JSHandles 在其源 frame 发生导航、或父 context 被销毁时会被自动释放；
3. 从 handles 指南 的 "Handle Lifecycle" 一节可以进一步确认：一旦创建，句柄就会持续保留对象，直到页面导航或手动 dispose()。

从源码结构看，这一语义由两层实现支撑：

• 浏览器侧：服务端 server/javascript.ts 中的 JSHandle 持有 CDP 的 objectId。dispose()（L215-L224）会调用 context._releaseHandle(this) 真正释放浏览器侧引用，并打上 _disposed 标记防止重复释放。
• 调试辅助：构造函数里如果检测到 globalThis.leakedJSHandles，会把未释放的句柄连同创建栈记入其中（L142-L143），方便排查句柄泄漏——这正是「忘记 dispose 会导致对象无法回收」的实证工具。

客户端的 dispose() 还有一个容错细节：捕获 target closed 类错误并静默返回，避免页面已关闭时清理资源反而抛错（见 client/jsHandle.ts#L81-L89）：

async dispose() {
  try {
    await this._channel.dispose({}, kNoTimeout);
  } catch (e) {
    if (isTargetClosedError(e))
      return;
    throw e;
  }
}

dispose() 的官方说明：

The jsHandle.dispose method stops referencing the element handle.

把 JSHandle 当作参数传递

JSHandle 实例可以作为 [method: Page.evalOnSelector]、[method: Page.evaluate]、[method: Page.evaluateHandle] 等方法的参数。handles 指南 给出了一个完整的「在页面创建数组并跨多次 evaluate 复用」的示例：

// Create new array in page.
const myArrayHandle = await page.evaluateHandle(() => {
  window.myArray = [1];
  return myArray;
});

// Get the length of the array.
const length = await page.evaluate(a => a.length, myArrayHandle);

// Add one more element to the array using the handle
await page.evaluate(arg => arg.myArray.push(arg.newElement), {
  myArray: myArrayHandle,
  newElement: 2
});

// Release the object when it's no longer needed.
await myArrayHandle.dispose();

// Create new array in page.
JSHandle myArrayHandle = page.evaluateHandle("() => {\n" +
  "  window.myArray = [1];\n" +
  "  return myArray;\n" +
  "}");

// Get the length of the array.
int length = (int) page.evaluate("a => a.length", myArrayHandle);

// Add one more element to the array using the handle
Map<String, Object> arg = new HashMap<>();
arg.put("myArray", myArrayHandle);
arg.put("newElement", 2);
page.evaluate("arg => arg.myArray.add(arg.newElement)", arg);

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

# Create new array in page.
my_array_handle = await page.evaluate_handle("""() => {
  window.myArray = [1];
  return myArray;
}""")

# Get current length of the array.
length = await page.evaluate("a => a.length", my_array_handle)

# Add one more element to the array using the handle
await page.evaluate("(arg) => arg.myArray.push(arg.newElement)", {
  'myArray': my_array_handle,
  'newElement': 2
})

# Release the object when it's no longer needed.
await my_array_handle.dispose()

// 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's no longer needed.
await myArrayHandle.DisposeAsync();

参数是如何穿越进程边界的？在客户端 client/jsHandle.ts#L98-L112，serializeArgument 把参数中的每个 JSHandle 替换为 { h: index } 占位符，并把句柄对应的 channel 收集进 handles 数组随协议一起发送；服务端在 dispatchers/jsHandleDispatcher.ts#L84-L86 的 parseArgument 中再把 guids 还原为真实的 JSHandle 对象。

服务端 server/javascript.ts#L253-L293 的 evaluateExpression 还处理了两个边界：

• 跨执行上下文：若句柄在其他 execution context 中创建，会先 context.adoptIfNeeded(handle) 采纳（adopt），并在求值完成后自动 dispose 采纳的临时句柄（L291）；若上下文不匹配则直接抛出 JSHandles can be evaluated only in the context they were created!（L278-L282）。
• 已释放的句柄：对已 dispose 的句柄求值会抛出 JSHandle is disposed!（L266-L267）。

API 全解

method: JSHandle.evaluate

since: v1.8 · 返回值：Serializable

Returns the return value of expression。该方法把句柄本身作为第一个参数传给 expression；如果 expression 返回 Promise，evaluate 会等待其 resolve 并返回结果值。

用法

const tweetHandle = await page.$('.tweet .retweets');
expect(await tweetHandle.evaluate(node => node.innerText)).toBe('10 retweets');

ElementHandle tweetHandle = page.querySelector(".tweet .retweets");
assertEquals("10 retweets", tweetHandle.evaluate("node => node.innerText"));

tweet_handle = await page.query_selector(".tweet .retweets")
assert await tweet_handle.evaluate("node => node.innerText") == "10 retweets"

tweet_handle = page.query_selector(".tweet .retweets")
assert tweet_handle.evaluate("node => node.innerText") == "10 retweets"

var tweetHandle = await page.QuerySelectorAsync(".tweet .retweets");
Assert.AreEqual("10 retweets", await tweetHandle.EvaluateAsync("node => node.innerText"));

参数说明

• expression：JavaScript expression to be evaluated in the browser context. If the expression evaluates to a function, the function is automatically invoked.（适用于 Java/Python/C# 等以字符串形式传入的绑定）
• pageFunction（仅 JS）：Function to be evaluated in the page context.
• arg（可选，EvaluationArgument）：传给 expression 的额外参数。句柄本身始终是第一个参数，arg 是第二个。
• exposeFunctions（可选，boolean，默认 false，JS 专用，since v1.62）：置为 true 时，arg 中传入的函数会通过 Page.exposeFunction 暴露到页面中，可在页面函数内调用，调用返回 Promise。由于底层经 Page.exposeFunction 暴露，技术上页面所有 frame 与 world 都可访问；顶层导航后暴露的函数会被清除。默认 false 时函数不可序列化，传入会抛错。详见 params.md#L587-L591。

客户端实现见 client/jsHandle.ts#L43-L48：先把 arg 序列化（若 exposeFunctions 为 true 则通过 serializeArgumentWithCallbacks 为每个函数注册 binding），再发送 evaluateExpression 协议消息，最后用 parseResult 反序列化返回值。

async method: JSHandle.evaluateHandle

since: v1.8 · 返回值：JSHandle

Returns the return value of expression as a JSHandle。同样把句柄作为第一个参数传给 expression，函数返回 Promise 时同样会等待。

evaluate 与 evaluateHandle 的唯一区别在于：后者返回 JSHandle 而非序列化后的值。参数（expression / pageFunction / arg / exposeFunctions）语义与 evaluate 完全一致。

实现上对应 client/jsHandle.ts#L50-L55 发送的 evaluateExpressionHandle 协议消息，服务端以 returnByValue: false 执行（server/javascript.ts#L178-L180），并把结果包装回新的 JSHandle——因此可以在返回值上继续链式操作，而不必一次性把大对象序列化回测试进程。

async method: JSHandle.getProperties

since: v1.8 · 返回值：Map<string, JSHandle>

返回一个 Map，键是自有属性名（own property names），值是属性对应的 JSHandle。

用法

const handle = await page.evaluateHandle(() => ({ window, document }));
const properties = await handle.getProperties();
const windowHandle = properties.get('window');
const documentHandle = properties.get('document');
await handle.dispose();

JSHandle handle = page.evaluateHandle("() => ({ window, document })");
Map<String, JSHandle> properties = handle.getProperties();
JSHandle windowHandle = properties.get("window");
JSHandle documentHandle = properties.get("document");
handle.dispose();

handle = await page.evaluate_handle("({ window, document })")
properties = await handle.get_properties()
window_handle = properties.get("window")
document_handle = properties.get("document")
await handle.dispose()

handle = page.evaluate_handle("({ window, document })")
properties = handle.get_properties()
window_handle = properties.get("window")
document_handle = properties.get("document")
handle.dispose()

var handle = await page.EvaluateHandleAsync("() => ({ window, document }");
var properties = await handle.GetPropertiesAsync();
var windowHandle = properties["window"];
var documentHandle = properties["document"];
await handle.DisposeAsync();

客户端实现（client/jsHandle.ts#L62-L67）逐条把 getPropertyList 返回的 {name, value} 映射为本地 JSHandle。值得注意的一点：服务端 internalGetProperties 在句柄没有 objectId（即直接持有字面量值）时会返回空 Map（server/javascript.ts#L194-L198）——这意味着对纯字面量值（如 evaluateHandle(() => 42)）调用 getProperties 得到的可能是空结果。

async method: JSHandle.getProperty

since: v1.8 · 返回值：JSHandle

从被引用对象中获取单个属性。

参数：propertyName（string）——要获取的属性名。

实现上，服务端 server/javascript.ts#L182-L192 的 _getProperty 是先构造一个只含该属性的临时对象再取其属性列表，然后立即 dispose 中间句柄：

private async _getProperty(propertyName: string): Promise<JSHandle> {
  const objectHandle = await this.evaluateHandle((object: any, propertyName) => {
    const result: any = { __proto__: null };
    result[propertyName] = object[propertyName];
    return result;
  }, propertyName);
  const properties = await objectHandle.internalGetProperties();
  const result = properties.get(propertyName)!;
  objectHandle.dispose();
  return result;
}

可以看到 getProperty 本质上是 evaluateHandle + internalGetProperties 的组合，这也是它能返回 JSHandle（而不是序列化值）的原因。

async method: JSHandle.jsonValue

since: v1.8 · 返回值：Serializable

返回对象的 JSON 表示。注意两点语义：

• 即使对象定义了 toJSON 函数，也不会被调用；
• 若被引用对象不可字符串化，方法返回空 JSON 对象；若对象存在循环引用，则抛出错误。

服务端实现（server/javascript.ts#L204-L209）直接调用页面内注入的 utilityScript.jsonValue 完成序列化，绕过 JSON.stringify 的 toJSON 钩子，从而保证拿到的是对象结构本身的 JSON 表示。

method: JSHandle.asElement

since: v1.8 · 返回值：null | ElementHandle

如果句柄是 ElementHandle 的实例，返回句柄自身；否则返回 null。用于在 Java/C# 等静态类型语言中把 querySelector 的结果安全地转换为元素句柄（例如 handles 指南 中的 jsHandle.asElement() 用法）。

从源码结构看，基类 JSHandle.asElement() 恒返回 null（client/jsHandle.ts#L73-L75），而 ElementHandle 覆写该方法返回 this（client/elementHandle.ts#L56-L58）。协议层据此区分两种 channel 类型：dispatcher 构造时用 jsHandle.asElement() ? 'ElementHandle' : 'JSHandle' 决定类型名（dispatchers/jsHandleDispatcher.ts#L39-L41）。

async method: JSHandle.dispose

since: v1.8

停止对浏览器侧对象的引用，使其可以被垃圾回收。建议在不再需要句柄时显式调用；页面导航或 context 销毁时 Playwright 也会自动清理。

JSHandle 与 ElementHandle、Locator 的关系与取舍

handles 指南 对 ElementHandle 的定位给出了明确的官方建议：

We only recommend using ElementHandle in the rare cases when you need to perform extensive DOM traversal on a static page. For all user actions and assertions use locator instead.

核心区别在于：ElementHandle 指向某个具体的 DOM 节点，而 Locator 捕获的是「如何找到该元素」的逻辑。用 handle 时，如果元素文本变化或被 React 重新渲染为完全不同的组件，handle 仍指向那个过期的 DOM 节点，可能导致意外行为：

const handle = await page.$('text=Submit');
// ...
await handle.hover();
await handle.click();

而 Locator 在每次使用时都会用选择器重新定位当前最新的 DOM 元素：

const locator = page.getByText('Submit');
// ...
await locator.hover();
await locator.click();

因此推荐的使用姿态是：常规交互与断言用 Locator 和 web-first assertions；JSHandle/ElementHandle 用于需要在页面上下文里保留并操作任意 JS 对象的场景——例如跨多次 evaluate 复用一个数组、遍历复杂对象结构（getProperties）、把页面对象以 JSON 形式取出（jsonValue）。

小结

• JSHandle 是 Playwright 表示「页面内 JavaScript 对象」的通用句柄，ElementHandle 是其面向 DOM 元素的子类；
• 典型创建入口：Page.evaluateHandle、Page.querySelector/querySelectorAll 及 Frame 对应方法；
• 核心 API 七件套：evaluate（取序列化值）、evaluateHandle（取新句柄）、getProperties/getProperty（对象遍历）、jsonValue（结构 JSON，不调 toJSON）、asElement（类型转换）、dispose（释放引用）；
• 句柄会阻止页面内对象被 GC，源 frame 导航或 context 销毁时自动释放，其余情况请手动 dispose()；
• 句柄可安全地作为 evaluate 系列方法的参数跨进程传递，底层通过 channel guid 序列化/反序列化完成（见 client/jsHandle.ts 与 server/dispatchers/jsHandleDispatcher.ts）。

相关文档：JSHandle API 参考、Handles 指南、公共参数说明。