评估 JavaScript

¥Evaluate JavaScript

Puppeteer 允许在 Puppeteer 驱动的页面上下文中评估 JavaScript 函数：

¥Puppeteer allows evaluating JavaScript functions in the context of the page driven by Puppeteer:

// Import puppeteer
import puppeteer from 'puppeteer';

(async () => {
  // Launch the browser
  const browser = await puppeteer.launch();

  // Create a page
  const page = await browser.newPage();

  // Go to your site
  await page.goto('YOUR_SITE');

  // Evaluate JavaScript
  const three = await page.evaluate(() => {
    return 1 + 2;
  });

  console.log(three);

  // Close browser.
  await browser.close();
})();

提醒

尽管该函数是在脚本上下文中定义的，但它实际上由 Puppeteer 进行字符串化，通过 Chrome DevTools 协议发送到目标页面并在那里进行评估。这意味着该函数无法访问脚本中的作用域变量。

¥Although the function is defined in your script context, it actually gets stringified by Puppeteer, sent to the target page over Chrome DevTools protocol and evaluated there. It means that the function cannot access scope variables in your script.

或者，你可以提供字符串形式的函数体：

¥Alternatively, you can provide a function body as a string:

// Evaluate JavaScript
const three = await page.evaluate(`
    1 + 2
`);

提醒

上面的示例产生了等效的结果，但它也说明了无法知道可用于计算函数的类型和全局变量。特别是，在 TypeScript 中，你应该小心确保被求值函数引用的对象是正确的。

¥The example above produces the equivalent results but it also illustrates that the types and global variables available to the evaluated function cannot be known. Especially, in TypeScript you should be careful to make sure that objects referenced by the evaluated function are correct.

返回类型

¥Return types

你计算的函数可以返回值。如果返回的值是原始类型，Puppeteer 会自动将其转换为脚本上下文中的原始类型，如前面的示例所示。

¥The functions you evaluate can return values. If the returned value is of a primitive type, it gets automatically converted by Puppeteer to a primitive type in the script context like in the previous example.

如果脚本返回一个对象，Puppeteer 会将其序列化为 JSON 并在脚本端重建它。此过程可能并不总是产生正确的结果，例如，当你返回 DOM 节点时：

¥If the script returns an object, Puppeteer serializes it to a JSON and reconstructs it on the script side. This process might not always yield correct results, for example, when you return a DOM node:

const body = await page.evaluate(() => {
  return document.body;
});
console.log(body); // {}, unexpected!

为了处理返回的对象，Puppeteer 提供了一种通过引用返回对象的方法：

¥To work with the returned objects, Puppeteer offers a way to return objects by reference:

const body = await page.evaluateHandle(() => {
  return document.body;
});
console.log(body instanceof ElementHandle); // true

返回的对象是 JSHandle 或 ElementHandle。ElementHandle 扩展了 JSHandle 并且它仅为 DOM 元素创建。

¥The returned object is either a JSHandle or a ElementHandle. ElementHandle extends JSHandle and it is only created for DOM elements.

有关句柄可用的方法的更多详细信息，请参阅 API 文档。

¥See the API documentation for more details about what methods are available for handles.

将参数传递给评估函数

¥Passing arguments to the evaluate function

你可以为你的函数提供参数：

¥You can provide arguments to your function:

const three = await page.evaluate(
  (a, b) => {
    return 1 + 2;
  },
  1,
  2
);

参数可以是原始值或 JSHandle。

¥The arguments can be primitive values or JSHandles.

注意

Page、JSHandle 和 ElementHandle 提供了几种不同的辅助程序来评估 JavaScript，但它们都遵循本指南中概述的基本原则。

¥Page, JSHandle and ElementHandle offer several different helpers to evaluate JavaScript but they all follow the basic principles outlined in this guide.