Pinte gradientes e use transparência e modos de mesclagem

Visão geral

Preencha uma área com um gradiente axial (linear) ou radial definido por dois pontos. Em seguida, componha formas sobrepostas com alfa constante e um modo de mesclagem opcional. O código segue examples/25-gradients.php e examples/20-transparency.php.

Um gradiente é um sombreamento (shading) da ISO 32000-2. linearGradient() emite um sombreamento Type 2 (axial), e radialGradient() emite um sombreamento Type 3 (radial). A transparência usa a constante alfa do estado de gráficos. setAlpha() define o valor ca para pintura sem traçado e o valor CA para pintura com traçado.

Instalação

composer require nextpdf/core:^3

Você não precisa de uma extensão opcional. A API de gradiente, alfa e modo de mesclagem é estável desde a 1.0.0 e funciona em toda a matriz de backport 8.1–8.4.

Visão geral conceitual

linearGradient(x, y, w, h, start, end) pinta uma mesclagem de cores ao longo do eixo da caixa, entre dois pontos Color. A ISO 32000-2 define o Coords de um sombreamento axial como [x0 y0 x1 y1]. Se os pontos finais coincidirem, nada é pintado. radialGradient(...) mescla entre dois círculos. O Coords radial é [x0 y0 r0 x1 y1 r1], e ambos os raios devem ser ≥ 0.

setAlpha($alpha, $mode) define a opacidade constante para as operações de pintura seguintes. O primeiro argumento é a constante alfa (ca/CA). O segundo argumento seleciona o modo de mesclagem (BM no modelo de imagem transparente). Redefina o alfa para 1.0 e o modo de mesclagem para Normal antes de desenhar conteúdo não relacionado.

Superfície da API

A superfície da API é gerada a partir do PHPDoc. Esta receita usa estes métodos:

linearGradient(float $x, float $y, float $w, float $h, Color $start, Color $end): static
radialGradient(float $x, float $y, float $w, float $h, Color $start, Color $end): static
setAlpha(float $alpha, BlendMode $mode = BlendMode::Normal): static
Color::rgb(int $r, int $g, int $b), Color::white(), Color::black() fornecem os pontos de cor do gradiente.
setFillColor(...) define a cor que será composta pelo alfa e pelo modo de mesclagem.

Exemplo de código — Início rápido

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;
use NextPDF\Graphics\BlendMode;
use NextPDF\Graphics\Color;

$doc = Document::createStandalone();
$doc->addPage();

// Axial gradient: blue -> white across a 190 x 40 box.
$doc->linearGradient(10, 30, 190, 40, Color::rgb(30, 58, 138), Color::white());

// Two overlapping rectangles at 70% opacity with Multiply blend.
$doc->setAlpha(0.7, BlendMode::Multiply);
$doc->setFillColor(220, 38, 38);
$doc->rect(20, 90, 60, 40, 'F');
$doc->setFillColor(37, 99, 235);
$doc->rect(50, 90, 60, 40, 'F');
$doc->setAlpha(1.0, BlendMode::Normal); // reset

$doc->save(getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/gradients.pdf');

Exemplo de código — Produção

Este é o exemplo completo, pronto para o ambiente de testes. Ele respeita NEXTPDF_COOKBOOK_OUTPUT sem adicionar entropia própria.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;
use NextPDF\Graphics\BlendMode;
use NextPDF\Graphics\Color;

$doc = Document::createStandalone();
$doc->setTitle('Gradients and Transparency');
$doc->addPage();

$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Gradients and Transparency', newLine: true);
$doc->ln(4);

// 1. Axial gradient — blue to white.
$doc->setFont('helvetica', 'B', 12);
$doc->cell(0, 8, '1. Axial gradient', newLine: true);
$doc->ln(2);
$doc->linearGradient(
    x: 10, y: $doc->getY(), w: 190, h: 40,
    start: Color::rgb(30, 58, 138), end: Color::white(),
);
$doc->ln(44);

// 2. Radial gradient — red centre fading to white.
$doc->setFont('helvetica', 'B', 12);
$doc->cell(0, 8, '2. Radial gradient', newLine: true);
$doc->ln(2);
$doc->radialGradient(
    x: 50, y: $doc->getY(), w: 110, h: 55,
    start: Color::rgb(220, 38, 38), end: Color::white(),
);
$doc->ln(59);

// 3. Constant alpha + blend mode over a light backdrop.
$doc->setFont('helvetica', 'B', 12);
$doc->cell(0, 8, '3. Alpha 0.7 with Multiply blend', newLine: true);
$doc->ln(2);
$baseY = $doc->getY();
$doc->setAlpha(1.0, BlendMode::Normal);
$doc->setFillColor(245, 245, 245);
$doc->rect(15, $baseY, 90, 40, 'F');
$doc->setAlpha(0.7, BlendMode::Multiply);
$doc->setFillColor(220, 38, 38);
$doc->rect(20, $baseY + 5, 40, 30, 'F');
$doc->setFillColor(37, 99, 235);
$doc->rect(40, $baseY + 5, 40, 30, 'F');

// Always reset compositing state before continuing.
$doc->setAlpha(1.0, BlendMode::Normal);
$doc->setFillColor(255);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/gradients.pdf';
$doc->save($out);

echo "Created gradients.pdf\n";

Casos extremos e pegadinhas

Pontos finais coincidentes no gradiente não pintam nada. Uma caixa de tamanho zero, em que w ou h colapsa o eixo, produz um sombreamento axial vazio conforme a ISO 32000-2. Confirme que a caixa tem dimensão.
Os raios devem ser não negativos. Um raio negativo em radialGradient() é inválido. Dois raios iguais a zero não pintam nada.
O alfa persiste entre as operações de pintura. setAlpha(0.7, …) permanece em vigor para cada pintura posterior até que você o redefina. Restaure setAlpha(1.0, BlendMode::Normal) após um bloco transparente, ou o conteúdo posterior aparecerá desbotado.
Um modo de mesclagem precisa de um plano de fundo. Um modo de mesclagem como Multiply ou Screen é composto sobre o que já está desenhado. Sobre uma página vazia, o efeito fica invisível, então desenhe um plano de fundo primeiro.
O array de modos de mesclagem do PDF 2.0 está obsoleto. O NextPDF emite um único nome de modo de mesclagem, que é a forma do PDF 2.0. A especificação torna obsoleta a forma de array legada.

Desempenho

Um gradiente consiste em um objeto de sombreamento mais um preenchimento. O alfa e o modo de mesclagem são parâmetros do estado de gráficos. Cada um tem custo constante por uso, e ambos permanecem dentro do orçamento de 2000 ms / 64 MB. Não ocorre rasterização, então os gradientes permanecem como sombreamentos independentes de resolução.

Notas de segurança

Esta receita pinta apenas a geometria e as cores que o código fornece. Ela não analisa entradas nem acessa a rede. Valide os valores de cor e de coordenada provenientes de dados não confiáveis antes de usá-los.

Conformidade

Declaração	Especificação	Cláusula
`ShadingType` 2 é axial, 3 é radial.	ISO 32000-2	§8.7.4.3
O `Coords` axial é `[x0 y0 x1 y1]`; pontos finais coincidentes não pintam nada.	ISO 32000-2	§8.7.4.5.3
O `Coords` radial é `[x0 y0 r0 x1 y1 r1]`; raios ≥ 0.	ISO 32000-2	§8.7.4.5.4
`CA`/`ca` são as constantes alfa de stroking/non-stroking.	ISO 32000-2	§8.4.5
`BM` é o modo de mesclagem atual.	ISO 32000-2	§11.3.5

Perfil de reprodutibilidade — estrutural. O /ID do trailer e os átomos de data variam a cada salvamento. O ambiente de testes remove esses átomos e, em seguida, compara a estrutura normalizada pelo qpdf. Esta receita descreve como o NextPDF produz a estrutura. Ela não faz uma afirmação genérica de conformidade com a ISO 32000-2.

Contexto comercial

Não aplicável. Gradientes, alfa e modos de mesclagem são recursos do Core. Eles não são bloqueados pelo Premium.