netflex/renderer

Netflex 基础 PDF 生成器的交互式高级 API

v5.0.2 2024-08-16 15:57 UTC

This package is auto-updated.

Last update: 2024-09-16 16:08:49 UTC


README

Stable version Build status License: MIT Contributors Downloads

[只读] Netflex Renderer 组件的子树拆分(见 netflex/framework

此包提供了一个生成 PDF、图片和服务器端 HTML 渲染的高级别构建器接口。

完整的 API 参考文档在此处提供 可在此处找到

目录

安装

composer require netflex/renderer

使用方法

生成 PDF/JPG/PNG/HTML

这些方法也适用于 HTMLPNGJPG 类。

从原始 HTML

<?php

use Netflex\Render\PDF;

$pdf = PDF::from('<h1>Hello, World!</h1>');

通过渲染视图

<?php

use Netflex\Render\PDF;

$pdf = PDF::view('templates.example', ['foo' => 'bar']);

通过渲染命名路由

<?php

use Netflex\Render\PDF;
use App\Models\Product;

$pdf = PDF::route('products.show', ['product' => Product::first()]);

通过渲染 URL

<?php

use Netflex\Render\PDF;

// Internal URL (must be publicly reachable)
$pdf = PDF::url('/test');

// External URL
$pdf = PDF::url('https://www.apility.no');

设置像素比

这些方法也适用于 PNGJPG 类。

<?php

use Netflex\Render\PDF;

$pdf = PDF::from('<h1>Hello, World!</h1>');

$pdf->devicePixelRatio(2.0);

指定超时时间

有时文档可能需要一段时间才能加载。您可以指定要等待多长时间才认为请求超时。

这些方法也适用于 HTMLPNGJPG 类。

use Netflex\Render\PDF;

$pdf = PDF::from('<h1>Hello, World!</h1>');

// Only allow the request to load for 5 seconds, then time out.
$pdf->timeout(5000);

等待文档加载

如果您的文档使用 JavaScript 进行客户端渲染,您可能需要等待一段时间才能捕获文档。否则,您可能会得到空白或部分空白的结果。

这些方法也适用于 HTMLPNGJPG 类。

use Netflex\Render\PDF;

$pdf = PDF::from('<h1>Hello, World!</h1>');

// Waits until the whole page has loaded, including all dependent resources such as stylesheets and images.
$pdf->waitUntilLoaded();

// Waits until fired the page DOM has been loaded, without waiting for resources to finish loading.
$pdf->waitUntilDOMContentLoaded();

// Waits until there has not been any network requests for at least 500ms
$pdf->waitUntiNetworkIdle()

// Waits until there has not been more than 2 network requests for at least 500ms
$pdf->waitUntiNetworkSettled();

检索渲染内容

这些方法也适用于 HTMLPNGJPG 类。

<?php

use Netflex\Render\PDF;

// As a Laravel response:
$response = $pdf->toResponse();

// As a file handle
$file = $pdf->stream();

// As a link
$url = $file->link();

// As a string
$str = $file->blob();

所有渲染器都实现了 Laravel 的 Responsable 接口。这意味着您可以直接从您的路由或控制器返回它们,并且它们将自动转换为响应。

<?php

use Netflex\Render\PDF;

Route::get('example.pdf', function () {
    return PDF::from('<h1>Hello, World!</h1>');
});
<?php

namespace App\Http\Controllers;

use App\Models\Product;
use Netflex\Render\PDF;

class ExampleController extends Controller
{
    public function show (Product $product)
    {
        return PDF::view('product', ['product' => $product]);
    }
}

PDF

指定页面范围

<?php

use Netflex\Render\PDF;

$pdf = PDF::view('templates.example', ['foo' => 'bar']);

$pdf->pageRanges(1, 3, [5, 10], 12, /* ... */);

打印背景

<?php

use Netflex\Render\PDF;

$pdf = PDF::view('templates.example', ['foo' => 'bar']);

$pdf->printBackground();

页边距

<?php

use Netflex\Render\PDF;

$pdf = PDF::view('templates.example', ['foo' => 'bar']);

$pdf->marginTop('1cm');
$pdf->marginRight('100mm');
$pdf->marginBottom('128px');
$pdf->marginLeft(200);

// ... or

$pdf->marginTop(1, PDF::UNIT_CM);
$pdf->marginRight(100, PDF::UNIT_MM);
$pdf->marginBottom(128, PDF::UNIT_PX);
$pdf->marginLeft(200); // Let the backend decide the unit

// Or specify them like you would in CSS
$pdf->margin('1cm'); // All margings set to 1cm
$pdf->margin('1cm', '2cm'); // Top and bottom set to 1cm, Left and right to 2cm

纸张格式

<?php

use Netflex\Render\PDF;

$pdf = PDF::view('templates.example', ['foo' => 'bar']);

// Metric sizes
$pdf->format(PDF::FORMAT_A0);
$pdf->format(PDF::FORMAT_A1);
$pdf->format(PDF::FORMAT_A2);
$pdf->format(PDF::FORMAT_A3);
$pdf->format(PDF::FORMAT_A4); // <-- Default
$pdf->format(PDF::FORMAT_A5);
$pdf->format(PDF::FORMAT_A6);

// US. sizes
$pdf->format(PDF::FORMAT_LETTER);
$pdf->format(PDF::FORMAT_LEGAL);
$pdf->format(PDF::FORMAT_TABLOID;
$pdf->format(PDF::FORMAT_LEDGER);

文档缩放

<?php

use Netflex\Render\PDF;

$pdf = PDF::view('templates.example', ['foo' => 'bar']);

$pdf->scale(1.5); // Scale factor between 0.1 and 2.0

显式大小

<?php

use Netflex\Render\PDF;

$pdf = PDF::view('templates.example', ['foo' => 'bar']);

$pdf->width('100cm');
$pdf->height('200cm');

横幅模式

<?php

use Netflex\Render\PDF;

$pdf = PDF::view('templates.example', ['foo' => 'bar']);

$pdf->format(PDF::FORMAT_A3);
$pdf->landscape();

从 CSS 设置大小

<?php

use Netflex\Render\PDF;

$pdf = PDF::view('templates.example', ['foo' => 'bar']);

$pdf->preferCSSPageSize();

设置自定义页眉和页脚

您可以通过提供自己的视图来覆盖默认的页眉和页脚。

请注意,如果您为页眉指定了自定义模板,但没有为页脚提供自定义模板,则将显示默认页脚。这也适用于相反的情况。这是渲染后端的一个限制。

<?php

use Netflex\Render\PDF;

$pdf = PDF::view('templates.example', ['foo' => 'bar']);

// If you just would like to enable the default header and footer
// Not needed if you specify a custom header or footer.
$pdf->displayHeaderFooter();

$pdf->headerTemplate('blocks.pdf.header', ['hello' => 'world']);
$pdf->footerTemplate('blocks.pdf.header', ['hello' => 'world']);

// Or from raw markup
$pdf->headerTemplateFrom('<div><span class="date"></span></div>');
$pdf->footerTemplateFrom('<div><span class="date"></span></div>');

输出页码等

如果您指定了自定义页眉或页脚视图,则可以使用以下 Blade 指令。

<div class="example-footer">
    <div>@pdf_date</div>
    <div>@pdf_title</div>
    <div>@pdf_url</div>
    <div>@pdf_page_number</div>
    <div>@pdf_total_pages</div>
</div>

页面分页实用工具

<div>@pdf_page_break</div>
<div>@pdf_page_break_before</div>
<div>@pdf_page_break_before_avoid</div>
<div>@pdf_page_break_after</div>
<div>@pdf_page_break_after_avoid</div>

标签和元数据

您可以设置 PDF 标签和元数据。

<?php

use Carbon\Carbon;
use Netflex\Render\PDF;

$pdf = PDF::url('https://www.google.com');

$pdf->author('John Doe');
$pdf->title('Hello World!');
$pdf->keywords(['foo', 'bar', 'baz']);
$pdf->description('Lorem ipsum dolor sit amet, consectetur adipiscing elit');
$pdf->creator('Example Company Inc.');

// You can also override the creation and modified dates
$now = Carbon::now();

$pdf->created($now);
$pdf->modified($now);

图片

设置视口大小

默认视口大小为 1920x1080,设备像素比为 1x

<?php

use Netflex\Render\PNG;

$png = PNG::view('templates.example', ['foo' => 'bar']);

// Viewport size 2560x1440 at 2x devicePixelRatio
$png->width(2560);
$png->height(1440)
$png->devicePixelRatio(2.0);

这些选项在 JPG 和 PNG 之间共享

使用 CSS 选择器捕获特定元素

注意:仅捕获第一个匹配的元素。

<?php

use Netflex\Render\PNG;

$png = PNG::view('templates.example', ['foo' => 'bar']);

$png = $png->selector('div.card');
$png = $png->selector('#logo');
$png = $png->selector('span');

裁剪

注意:即使使用选择器来定位元素,裁剪始终相对于整个文档。这是后端的一个限制,将来可能会更改。

<?php

use Netflex\Render\PNG;

$png = PNG::view('templates.example', ['foo' => 'bar']);

// Extract a 256x256 image starting from x:10, y:10 offsets from the document top
$png = $png->clip(10, 10, 256, 256);

全页

如果您想要捕获整个页面,包括视口中不可见的内容。

<?php

use Netflex\Render\PNG;

$png = PNG::view('templates.example', ['foo' => 'bar']);

$png = $png->fullPage();

JPG

质量

<?php

use Netflex\Render\JPG;

$jpg = JPG::view('templates.example', ['foo' => 'bar']);

// Best quality
$jpg = $jpg->quality(100);

// Worst quality
$jpg = $jpg->quality(0);

PNG

透明

保留背景不透明度。

<?php

use Netflex\Render\PNG;

$png = PNG::view('templates.example', ['foo' => 'bar']);

$png->transparent();

HTML

HTML 渲染器可以用于获取作为 HTML 的渲染内容。如果您的视图/URL 的一部分使用 JavaScript 进行客户端渲染,这非常有用。

<?php

use Netflex\Render\HTML;

$html = HTML::view('templates.example', ['foo' => 'bar']);

$content = $html->blob();

服务器端渲染 (SSR)

此包提供了一个中间件,您可以使用它来服务器端渲染您的内容。

Netflex\Render\Http\Middleware\SSR

只需在您的 app/Http/Kernel.php 文件中注册即可

<?php

namespace App\Http;

use Netflex\Http\Kernel as HttpKernel;

class Kernel extends HttpKernel
{
    /**
     * The application's route middleware.
     *
     * These middleware may be assigned to groups or used individually.
     *
     * @var array
     */
    protected $routeMiddleware = [
        'ssr' => \Netflex\Render\Http\Middleware\SSR::class,
    ];

现在您可以在路由中使用它

<?php

Route::group(['middleware' => 'ssr'], function () {
    Route::get('/example', 'ExampleController@show');
});

MJML

MJML 渲染器用于将 MJML 转换为 HTML。 MJML 是一个用于生成响应式电子邮件标记的框架。

MJML 渲染器单独使用并不十分有用,但提供了一些辅助工具,可以与 Mailable 集成。

示例

<?php

use Netflex\Render\MJML;

$html = MJML::from('<mjml><mj-body><mj-text>Hello World</mj-text></mj-body</mml>')
  ->blobl();

在可邮寄内容中使用

不用写 .blade.php 文件,将视图写成 .mjml 文件。

在您的 Mailable 类中添加 trait Netflex\Render\Mail\MJML

示例

<!-- resources/views/mail/example.mjml -->
<mjml>
    <mj-body>
        <mj-section>
            <mj-column width="100%">
              <mj-text>
                {{ $message }}
                </mj-text>
            </mj-column>
        </mj-section>
    </mj-body>
</mjml>
<?php

namespace App\Mail;

use Illuminate\Mail\Mailable;
use Netflex\Render\Mail\MJML;

class ExampleMail extends Mailable
{
  use MJML;

    /**
     * Build the message.
     *
     * @return $this
     */
    public function build()
    {
        return $this->mjml('mail.example', ['message' => 'Hello World'])
            ->subject('Rendered with MJML!');
    }
}

生成的渲染标记将被缓存,直到源 .mjml 文件更改。但传递给视图的变量仍会动态注入。

视图宏

此包为您注册了一些到 View 类的宏,以便您方便使用。

<?php

use Illuminate\Support\Facades\View;

View::make('example')->renderPDF();
View::make('example')->renderJPG();
View::make('example')->renderPNG();
View::make('example')->renderHTML();

// You can also chain all the other options
View::make('example')->renderPDF()
    ->printBackground(); // ...etc

许可协议:[MIT 许可证](https://github.com/netflex-sdk/renderer/blob/HEAD/LICENSE)

版权所有 [Apility AS](https://www.apility.no/) © 2021