info2soft/browsershot

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

维护者

详细信息

github.com/info2soft/browsershot

主页

源代码

资助包维护！
Patreon

安装: 753

依赖: 0

建议: 0

安全性: 0

星标: 0

关注者: 0

分支: 485

3.32.2 2019-08-16 08:36 UTC

Requires

Requires (Dev)

MIT 6aa8750308a0473d1e3cc079e698b78f9495e6d7

imagepdfconvertheadlesswebpagechromescreenshotpuppeteer

This package is auto-updated.

Last update: 2024-09-28 21:54:44 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输入，只需用 html 替换 url 方法即可

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 方法。

该方法接受键/值对的 array，或者简单地接受值。所有这些参数都将自动以 -- 为前缀。

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来捕获更高像素密度的网页。这模仿了网页在retina/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弹出窗口，如alert、prompt和confirmations会导致站点渲染停止，从而导致截图为空。调用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);

添加JS

您可以使用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 相关的问题，可以选择禁用 CORS 检查，使用 --disable-web-security。

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")
   ...

设置额外的 HTTP 标头

要发送自定义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，请查看browsershot的v2版本，该版本使用Chrome无头CLI进行截图。版本v2不再维护，但应该工作得很好。

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

Postcardware

您可以自由使用此包（它是MIT许可的），但如果它进入您的生产环境，我们非常感谢您从家乡寄给我们一张明信片，说明您正在使用我们哪些包。

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

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

鸣谢

支持我们

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

您的业务依赖于我们的贡献吗？联系我们并支持我们在Patreon上。所有承诺都将专门用于分配人力资源进行维护和新奇事物。

许可证

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