scratcher28/browsershot

使用无头Chrome将网页转换为图像或PDF

维护者

详细信息

github.com/scratcher28/browsershot

主页

源代码

资助包维护！
Patreon

安装: 4

依赖项: 0

建议者: 0

安全性: 0

星标: 2

关注者: 2

分支: 486

3.32.3 2019-09-20 08:01 UTC

Requires

Requires (Dev)

MIT dba21ee6b7854646e2a3f3a4731f39c88ae8ab8e

imagepdfconvertheadlesswebpagechromescreenshotpuppeteer

This package is not auto-updated.

Last update: 2024-10-01 14:03:49 UTC

README

Latest Version MIT Licensed Build Status StyleCI Total Downloads

此包可以将网页转换为图像或PDF。转换由Puppeteer在幕后完成，它控制着Google Chrome的无头版本。

以下是一个快速示例

use Spatie\Browsershot\Browsershot;

// an image will be saved
Browsershot::url('https://example.com')->save($pathToImage);

如果传递给save方法的路径有pdf扩展名，它将保存PDF。

// a pdf will be saved
Browsershot::url('https://example.com')->save('example.pdf');

您还可以使用任意HTML输入，只需将url方法替换为html

Browsershot::html('<h1>Hello world!!</h1>')->save('example.pdf');

Browsershot还可以在JavaScript执行后获取HTML页面的主体

Browsershot::url('https://example.com')->bodyHtml(); // returns the html of the body

Spatie是一家位于比利时的安特卫普网页设计公司。您可以在我们的网站上找到我们所有开源项目的概述这里。

要求

此包需要node 7.6.0或更高版本和Puppeteer Node库。

在MacOS上，您可以通过NPM在您的项目中安装Puppeteer

npm install puppeteer

或者您可以选择全局安装它

npm install puppeteer --global

在由Forge提供的Ubuntu 16.04服务器上，您可以像这样安装最新稳定版本的Chrome

curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
sudo apt-get install -y nodejs gconf-service libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates fonts-liberation libappindicator1 libnss3 lsb-release xdg-utils wget
sudo npm install --global --unsafe-perm puppeteer
sudo chmod -R o+rx /usr/lib/node_modules/puppeteer/.local-chromium

自定义node和npm二进制文件

根据您的配置，node或npm可能不会直接对Browsershot可用。如果您需要手动设置这些二进制文件路径，可以通过调用setNodeBinary和setNpmBinary方法来完成。

Browsershot::html('Foo')
    ->setNodeBinary('/usr/local/bin/node')
    ->setNpmBinary('/usr/local/bin/npm');

默认情况下，Browsershot将使用node和npm来执行命令。

自定义包含路径

如果您不想手动指定二进制文件路径，而是想修改一般的包含路径，您可以使用setIncludePath方法来设置它。

Browsershot::html('Foo')
    ->setIncludePath('$PATH:/usr/local/bin')

设置包含路径在无法自动找到node和npm的情况下非常有用。

自定义node模块路径

如果您想使用替代的node_modules源，您可以使用setNodeModulePath方法来设置它。

Browsershot::html('Foo')
  ->setNodeModulePath("/path/to/my/project/node_modules/")

自定义二进制文件路径

如果您想使用替代的脚本源，您可以使用setBinPath方法来设置它。

Browsershot::html('Foo')
  ->setBinPath("/path/to/my/project/my_script.js")

自定义chrome/chromium可执行文件路径

如果您想使用由puppeteer安装的替代chrome或chromium可执行文件，您可以使用setChromePath方法来设置它。

Browsershot::html('Foo')
  ->setChromePath("/path/to/my/chrome")

向Chromium传递自定义参数

如果您需要向Chromium传递自定义参数，请使用addChromiumArguments方法。

此方法接受键/值对的数组，或仅值。所有这些参数都将自动以--为前缀。

Browsershot::html('Foo')
  ->addChromiumArguments([
      'some-argument-without-a-value',
      'keyed-argument' => 'argument-value',
  ]);

如果没有提供键，则将参数原样传递。

此方法在需要传递标志以修复某些Linux发行版（例如CentOS）上的字体渲染问题时非常有用。

Browsershot::html('Foo')
  ->addChromiumArguments([
      'font-render-hinting' => 'none',
  ]);

安装

此包可以通过Composer安装。

composer require spatie/browsershot

使用

在所有示例中，都假设您已在文件顶部导入此命名空间

use Spatie\Browsershot\Browsershot;

屏幕截图

这是创建网页图像的最简单方法

Browsershot::url('https://example.com')->save($pathToImage);

格式化图像

默认情况下，截图的格式将是png。（根据Puppeteer的配置）
但您可以通过质量选项将其更改为jpeg。

Browsershot::url('https://example.com')
    ->setScreenshotType('jpeg', 100)
    ->save($pathToImage);

调整图像大小

默认情况下，截图的大小将与您在桌面上的分辨率匹配。想要其他大小的截图？没问题！

Browsershot::url('https://example.com')
    ->windowSize(640, 480)
    ->save($pathToImage);

您还可以独立于窗口大小设置输出图像的大小。以下是如何将分辨率1920x1080的截图调整到200x200大小的示例。

Browsershot::url('https://example.com')
    ->windowSize(1920, 1080)
    ->fit(Manipulations::FIT_CONTAIN, 200, 200)
    ->save($pathToImage);

您可以使用clip仅截取页面的一部分。

Browsershot::url('https://example.com')
    ->clip($x, $y, $width, $height)
    ->save($pathToImage);

使用select截取匹配选择器的元素。

Browsershot::url('https://example.com')
    ->select('.some-selector')
    ->save($pathToImage);

图像处理

您可以使用spatie/image提供的所有方法。以下是一个创建灰度图像的示例。

Browsershot::url('https://example.com')
    ->windowSize(640, 480)
    ->greyscale()
    ->save($pathToImage);

截取整个页面

您可以使用fullPage()截取页面的全部长度。

Browsershot::url('https://example.com')
    ->fullPage()
    ->save($pathToImage);

设置设备缩放比例

您还可以通过传递2或3的设备缩放因子值来捕获更高像素密度的网页。这模拟了网页在视网膜/xhdpi显示上的显示方式。

Browsershot::url('https://example.com')
    ->deviceScaleFactor(2)
    ->save($pathToImage);

移动仿真

您可以使用mobile和touch方法来模拟移动视图。mobile会将显示设置为考虑页面的meta viewport，就像Chrome移动版一样。touch将浏览器设置为模拟触摸功能，从而允许对检查触摸的页面进行欺骗。结合userAgent方法，这些方法可以用来有效地截取页面的移动截图。

Browsershot::url('https://example.com')
    ->userAgent('My Mobile Browser 1.0')
    ->mobile()
    ->touch()
    ->save($pathToImage);

设备仿真

您可以使用device方法来模拟设备视图。设备的名称可以在这里找到。

$browsershot = new Browsershot('https://example.com', true);
$browsershot
        ->device('iPhone X')
        ->save($pathToImage);

等同于

Browsershot::url('https://example.com')
    ->userAgent('Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A372 Safari/604.1')
    ->windowSize(375, 812)
    ->deviceScaleFactor(3)
    ->mobile()
    ->touch()
    ->landscape(false)
    ->save($pathToImage);

背景

如果您在捕获截图时想忽略网站的背景，请使用hideBackground()方法。

Browsershot::url('https://example.com')
    ->hideBackground()
    ->save($pathToImage);

关闭对话框

JavaScript弹出窗口，如警报、提示和确认，会导致站点渲染停止，从而导致截图为空。调用dismissDialogs()方法会自动关闭此类弹出窗口，允许截取截图。

Browsershot::url('https://example.com')
    ->dismissDialogs()
    ->save($pathToImage);

禁用JavaScript

如果您想在捕获页面时完全禁用JavaScript，请使用disableJavascript()方法。
请注意，某些网站没有JavaScript可能无法正确渲染。

Browsershot::url('https://example.com')
    ->disableJavascript()
    ->save($pathToImage);

等待懒加载资源

一些网站通过Ajax或使用webfonts懒加载额外的资源，这些资源可能无法及时加载到截图时。使用waitUntilNetworkIdle()方法，您可以告诉Browsershot在截图前等待500毫秒没有网络活动，确保所有额外的资源都已加载。

Browsershot::url('https://example.com')
    ->waitUntilNetworkIdle()
    ->save($pathToImage);

或者，您可以使用较宽松的waitUntilNetworkIdle(false)，这允许在500毫秒的等待期间有2个网络连接，这对于脚本定期ping Ajax端点的网站很有用。

延迟截图

您可以使用setDelay()延迟截图。如果您需要等待JavaScript完成或尝试捕获懒加载资源，这很有用。

Browsershot::url('https://example.com')
    ->setDelay($delayInMilliseconds)
    ->save($pathToImage);

等待JavaScript函数

您还可以使用waitForFunction()等待JavaScript函数直到它返回true。如果您需要等待与网络状态无关的JavaScript任务，这很有用。

Browsershot::url('https://example.com')
    ->waitForFunction('window.innerWidth < 100', $pollingInMilliseconds, $timeoutInMilliseconds)
    ->save($pathToImage);

添加JavaScript

您可以使用Puppeteer的addScriptTag语法在截图或输出之前添加JavaScript。

Browsershot::url('https://example.com')
    ->setOption('addScriptTag', json_encode(['content' => 'alert("Hello World")']))
    ->save($pathToImage);

添加CSS

您可以使用Puppeteer的addStyleTag语法在截图或输出之前添加CSS样式。

Browsershot::url('https://example.com')
    ->setOption('addStyleTag', json_encode(['content' => 'body{ font-size: 14px; }']))
    ->save($pathToImage);

直接输出到浏览器

您可以使用screenshot()方法将图像直接输出到浏览器。

$image = Browsershot::url('https://example.com')
    ->screenshot()

PDF文件

如果传递给save方法的路径有pdf扩展名，Browsershot会保存PDF。

// a pdf will be saved
Browsershot::url('https://example.com')->save('example.pdf');

或者，您可以显式使用savePdf方法

Browsershot::url('https://example.com')->savePdf('example.pdf');

您还可以传递一些HTML，这些HTML将被转换为PDF。

Browsershot::html($someHtml)->savePdf('example.pdf');

设置PDF大小

您可以指定宽度和高度。

Browsershot::html($someHtml)
   ->paperSize($width, $height)
   ->save('example.pdf');

可选地，您可以将自定义单位作为第三个参数传递给paperSize。

设置边距

可以设置边距。

Browsershot::html($someHtml)
   ->margins($top, $right, $bottom, $left)
   ->save('example.pdf');

可选地，您可以将自定义单位作为第五个参数传递给margins。

页眉和页脚

默认情况下，PDF不会显示由Chrome生成的页眉和页脚。以下是如何使页眉和页脚出现的方法。您还可以提供自定义HTML模板作为页眉和页脚。

Browsershot::html($someHtml)
   ->showBrowserHeaderAndFooter()
   ->headerHtml($someHtml)
   ->footerHtml($someHtml)
   ->save('example.pdf');

在页眉和页脚HTML中，以下类的任何标签都将将其打印值注入到其内容中。

  • date格式化打印日期
  • title文档标题
  • url文档位置
  • pageNumber当前页码
  • totalPages文档中的总页数

要隐藏页眉或页脚，您可以调用hideHeader或hideFooter。

背景

默认情况下，生成的PDF不会显示HTML页面的背景。如果您想包含背景，可以调用showBackground

Browsershot::html($someHtml)
   ->showBackground()
   ->save('example.pdf');

横向布局

如果您想生成的PDF是横向的，请调用landscape。

Browsershot::html($someHtml)
   ->landscape()
   ->save('example.pdf');

仅导出特定页面

您可以通过传递给pages方法的打印范围来控制应该导出哪些页面。以下是一些有效的打印范围示例：1、1-3、1-5, 8, 11-13。

Browsershot::html($someHtml)
   ->pages('1-5, 8, 11-13')
   ->save('example.pdf');

直接输出到浏览器

您可以使用pdf()方法直接将PDF输出到浏览器。

$pdf = Browsershot::url('https://example.com')
    ->pdf()

HTML

Browsershot还可以在JavaScript执行后获取HTML页面的主体

Browsershot::url('https://example.com')->bodyHtml(); // returns the html of the body

评估

Browsershot可以获取HTML页面的评估结果

Browsershot::url('https://example.com')
  ->deviceScaleFactor(2)
  ->evaluate("window.devicePixelRatio"); // returns 2

其他

设置任意选项

您可以通过调用setOption来设置任何任意选项

Browsershot::url('https://example.com')
   ->setOption('landscape', true)
   ->save($pathToImage);

解决CORS问题

如果您遇到与CORS相关的问题，您可以选择使用--disable-web-security禁用CORS检查。

Browsershot::url('https://example.com')
   ->setOption('args', ['--disable-web-security'])
   ->save($pathToImage);

更改浏览器语言

您可以使用setOption来更改浏览器的语言。
例如，为了以特定语言加载页面。

Browsershot::url('https://example.com')
   ->setOption('args', '--lang=en-GB')
   ...

设置用户代理

如果您想设置Google Chrome在截图时应使用的用户代理，可以这样做。

Browsershot::url('https://example.com')
    ->userAgent('My Special Snowflake Browser 1.0')
    ->save($pathToImage);

设置页面的CSS媒体类型

您可以使用媒体类型进行模拟，这在生成PDF截图时特别有用，因为它会尝试模拟页面的打印版本。

Browsershot::url('https://example.com')
    ->emulateMedia('screen') // "screen", "print" (default) or null (passing null disables the emulation).
    ->savePdf($pathToPdf);

Browsershot的默认超时设置为60秒。当然，您可以修改此超时。

Browsershot::url('https://example.com')
    ->timeout(120)
    ->save($pathToImage);

禁用沙箱

在Linux的某些虚拟化环境中运行时，可能需要禁用沙箱。

Browsershot::url('https://example.com')
   ->noSandbox()
   ...

忽略HTTPS错误

如有必要，您可以忽略HTTPS错误。

Browsershot::url('https://example.com')
   ->ignoreHttpsErrors()
   ...

指定代理服务器

您可以在连接时指定要使用的代理服务器。传递给setProxyServer的参数将被传递到Chromium的--proxy-server=选项。更多信息请参阅：https://www.chromium.org/developers/design-documents/network-settings#TOC-Command-line-options-for-proxy-settings

Browsershot::url('https://example.com')
   ->setProxyServer("1.2.3.4:8080")
   ...

设置extraHTTPHeaders

要发送自定义HTTP头，请设置extraHTTPHeaders选项，如下所示

Browsershot::url('https://example.com')
    ->setExtraHttpHeaders(['Custom-Header-Name' => 'Custom-Header-Value'])
   ...

使用HTTP身份验证

您可以为HTTP身份验证提供凭证

Browsershot::url('https://example.com')
    ->authenticate('username', 'password')
   ...

使用Cookies

您可以将Cookies添加到对给定URL的请求中

Browsershot::url('https://example.com')
    ->useCookies(['Cookie-Key' => 'Cookie-Value'])
   ...

如果需要，您可以指定将Cookies注册到的域名

Browsershot::url('https://example.com')
    ->useCookies(['Cookie-Key' => 'Cookie-Value'], 'ui.example.com')
   ...

在页面上单击

您可以在页面上指定点击操作。

Browsershot::url('https://example.com')
    ->click('#selector1')
    // Right click 5 times on #selector2, each click lasting 200 milliseconds.
    ->click('#selector2', 'right', 5, 200)

在页面上输入文本

您可以在页面上输入文本（您可以用这个功能来填写表单字段）。

Browsershot::url('https://example.com')
    ->type('#selector1', 'Hello, is it me you are looking for?')

您可以组合使用type和click来在表单提交后创建页面的截图

Browsershot::url('https://example.com')
    ->type('#firstName', 'My name')
    ->click('#submit')
    ->delay($millisecondsToWait)
    ->save($pathToImage);

更改下拉菜单的值

您可以在页面上更改下拉菜单的值（您可以用这个功能来更改表单选择字段）。

Browsershot::url('https://example.com')
    ->selectOption('#selector1', '100')

您可以组合使用selectOption、type和click来在表单提交后创建页面的截图

Browsershot::url('https://example.com')
    ->type('#firstName', 'My name')
    ->selectOption('#state', 'MT')
    ->click('#submit')
    ->delay($millisecondsToWait)
    ->save($pathToImage);

将选项写入文件

当给puppeteer提供的选项数量太多时，Browsershot会因命令行字符溢出而失败。Browsershot可以将选项写入文件，然后将该文件传递给puppeteer，从而绕过字符溢出。

Browsershot::url('https://example.com')
   ->writeOptionsToFile()
   ...

相关包

贡献

有关详细信息，请参阅CONTRIBUTING。

安全性

如果您发现任何与安全相关的问题，请通过电子邮件freek@spatie.be联系，而不是使用问题跟踪器。

替代方案

如果您无法安装Node和Puppeteer，请查看https://github.com/spatie/browsershot/tree/2.4.1中的browsershot的v2版本，它使用Chrome无头CLI来获取截图。v2不再维护，但应该工作得很好。

如果您使用无头Chrome无效，请查看此包的v1版本，它使用已废弃的PhantomJS二进制文件。

Postcardware

您可以使用此包（它遵循MIT许可协议），但如果它进入了您的生产环境，我们非常欢迎您从家乡给我们寄来一张明信片，说明您正在使用我们的哪个包。

我们的地址是：Spatie，Samberstraat 69D，2060 安特卫普，比利时。

所有明信片都发表在我们的网站上。

致谢

支持我们

Spatie是一家位于比利时的安特卫普的网页设计公司。您可以在我们的网站上找到我们所有开源项目的概述。

您的业务依赖于我们的贡献吗？请联系我们，并在Patreon上支持我们。所有承诺都将专门用于分配人力进行维护和新酷炫的东西。

许可协议

MIT许可协议（MIT）。有关更多信息，请参阅许可文件。