Vẽ chuyển sắc và dùng độ trong suốt với chế độ hòa trộn

Tổng quan nhanh

Tô một vùng bằng chuyển sắc hai điểm dừng theo trục (tuyến tính) hoặc xuyên tâm. Sau đó kết hợp các hình chồng lên nhau bằng alpha cố định và một chế độ hòa trộn tùy chọn. Mã nguồn dựa trên examples/25-gradients.php và examples/20-transparency.php.

Chuyển sắc là một dạng tô bóng (shading) theo ISO 32000-2. linearGradient() tạo ra dạng tô bóng Type 2 (theo trục), còn radialGradient() tạo ra dạng tô bóng Type 3 (xuyên tâm). Độ trong suốt sử dụng hằng số alpha của trạng thái đồ họa. setAlpha() đặt giá trị ca cho phần không tô viền và giá trị CA cho phần tô viền.

Cài đặt

composer require nextpdf/core:^3

Bạn không cần bất kỳ phần mở rộng tùy chọn nào. API cho chuyển sắc, alpha và chế độ hòa trộn đã ổn định kể từ 1.0.0 và chạy trên ma trận backport 8.1–8.4.

Tổng quan khái niệm

linearGradient(x, y, w, h, start, end) vẽ một dải chuyển màu dọc theo trục của hộp, giữa hai điểm dừng Color. ISO 32000-2 định nghĩa Coords của một dạng tô bóng theo trục là [x0 y0 x1 y1]. Nếu các điểm cuối trùng nhau thì không có gì được vẽ. radialGradient(...) pha màu giữa hai đường tròn. Coords xuyên tâm là [x0 y0 r0 x1 y1 r1], và cả hai bán kính đều phải ≥ 0.

setAlpha($alpha, $mode) đặt độ mờ cố định cho các thao tác vẽ tiếp theo. Đối số đầu tiên là hằng số alpha (ca/CA). Đối số thứ hai chọn chế độ hòa trộn (BM trong mô hình tạo ảnh trong suốt). Hãy đặt lại alpha về 1.0 và chế độ hòa trộn về Normal trước khi vẽ nội dung không liên quan.

Bề mặt API

Bề mặt API được sinh từ PHPDoc. Công thức này sử dụng các phương thức sau:

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() cung cấp các điểm dừng chuyển sắc.
setFillColor(...) đặt màu sẽ được ghép bằng alpha và chế độ hòa trộn.

Mẫu mã — bắt đầu nhanh

<?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');

Mẫu mã — bản dùng trong sản xuất

Đây là ví dụ hoàn chỉnh, sẵn sàng đưa vào khung kiểm thử. Ví dụ này tôn trọng NEXTPDF_COOKBOOK_OUTPUT và không tự thêm bất kỳ yếu tố ngẫu nhiên nào.

<?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";

Trường hợp biên & điểm cần lưu ý

Các điểm cuối chuyển sắc trùng nhau thì không vẽ gì. Nếu một hộp có kích thước bằng không do w hoặc h làm trục bị triệt tiêu, nó sẽ tạo ra một dạng tô bóng theo trục rỗng theo ISO 32000-2. Hãy bảo đảm hộp có kích thước.
Bán kính phải không âm. Truyền một bán kính âm vào radialGradient() là không hợp lệ. Nếu cả hai bán kính bằng không thì không có gì được vẽ.
Alpha vẫn duy trì qua các lần vẽ. setAlpha(0.7, …) vẫn có hiệu lực cho mọi thao tác vẽ sau đó cho đến khi bạn đặt lại. Hãy khôi phục setAlpha(1.0, BlendMode::Normal) sau một khối trong suốt; nếu không, nội dung sau đó sẽ bị mờ nhạt.
Chế độ hòa trộn cần có nền phía sau. Một chế độ hòa trộn như Multiply hoặc Screen sẽ ghép lên những gì đã được vẽ. Trên một trang trống thì hiệu ứng không nhìn thấy được, vì vậy hãy vẽ phần nền trước.
Mảng chế độ hòa trộn trong PDF 2.0 đã lỗi thời. NextPDF xuất ra một tên chế độ hòa trộn đơn lẻ, đúng với dạng của PDF 2.0. Đặc tả kỹ thuật xem dạng mảng cũ là lỗi thời.

Hiệu năng

Mỗi chuyển sắc gồm một đối tượng tô bóng và một thao tác tô. Alpha và chế độ hòa trộn là các tham số của trạng thái đồ họa. Mỗi loại có chi phí cố định cho mỗi lần dùng, và cả hai đều nằm trong ngưỡng 2000 ms / 64 MB. Không có bước raster hóa nào diễn ra, vì vậy các chuyển sắc vẫn là những dạng tô bóng không phụ thuộc độ phân giải.

Lưu ý bảo mật

Công thức này chỉ vẽ hình học và màu sắc do mã của bạn cung cấp. Nó không phân tích đầu vào và không truy cập mạng. Hãy xác thực các giá trị màu và tọa độ đến từ dữ liệu không đáng tin trước khi dùng chúng.

Tuân thủ

Phát biểu	Đặc tả	Điều khoản
`ShadingType` 2 là theo trục, 3 là xuyên tâm.	ISO 32000-2	§8.7.4.3
Theo trục, `Coords` là `[x0 y0 x1 y1]`; các điểm cuối trùng nhau thì không vẽ gì.	ISO 32000-2	§8.7.4.5.3
Xuyên tâm, `Coords` là `[x0 y0 r0 x1 y1 r1]`; bán kính ≥ 0.	ISO 32000-2	§8.7.4.5.4
`CA`/`ca` là hằng số alpha cho stroking/non-stroking.	ISO 32000-2	§8.4.5
`BM` là chế độ hòa trộn hiện tại.	ISO 32000-2	§11.3.5

Hồ sơ khả năng tái lập — theo cấu trúc. /ID trong trailer và các phần tử ngày tháng thay đổi ở mỗi lần lưu. Khung kiểm thử loại bỏ các phần tử đó, rồi so sánh cấu trúc đã chuẩn hóa bằng qpdf. Công thức này mô tả cách NextPDF tạo ra cấu trúc. Nó không đưa ra tuyên bố tuân thủ bao quát đối với ISO 32000-2.

Bối cảnh thương mại

Không áp dụng. Chuyển sắc, alpha và chế độ hòa trộn là các tính năng của Core. Chúng không yêu cầu Premium.