Barcode

Tổng quan nhanh

NextPDF Pro bổ sung các bộ ký hiệu mã vạch 2D chuyên dụng và chuỗi cung ứng bên trên các bộ ký hiệu tuyến tính và QR trong phiên bản mã nguồn mở. Mỗi bộ ký hiệu render trực tiếp vào một bề mặt trang PDF dưới dạng một content stream tất định.

Khả dụng & cấp phép

Năng lực này đi kèm trong NextPDF Pro (nextpdf/pro) và kích hoạt bằng một license envelope hạng Pro. Một triển khai không có quyền đó sẽ không nạp các class của năng lực này. So sánh các phiên bản và lấy giấy phép.

Cài đặt

composer require nextpdf/pro:^3

Các bộ mã hóa của Pro tự đăng ký thông qua registry bộ mã hóa mã vạch tiêu chuẩn. Các ứng dụng tự dựng registry của riêng mình có thể đăng ký lại các bộ mã hóa của Pro một cách tường minh thông qua service provider đã xuất bản.

Tổng quan khái niệm

Phiên bản mã nguồn mở bao quát các bộ ký hiệu tuyến tính và QR thường ngày. NextPDF Pro mở rộng cùng registry đó với các bộ ký hiệu chuyên dụng cho bán lẻ, logistics, bưu chính, và công nghiệp mật độ cao:

• Micro QR Code — biến thể QR nhỏ gọn cho không gian nhãn nhỏ.
• DotCode — một bộ ký hiệu dạng ma trận chấm được thiết kế cho việc đánh dấu công nghiệp tốc độ cao.
• Han Xin Code — một bộ ký hiệu 2D có dung lượng văn bản CJK tập-lớn nguyên bản, theo ISO/IEC 20830.
• JabCode — một bộ ký hiệu 2D đa sắc với việc xếp tầng nhiều ký hiệu.
• rMQR — biến thể Micro QR hình chữ nhật cho các nhãn hẹp, rộng.
• GS1 DataBar — họ bộ ký hiệu bán lẻ và phiếu giảm giá của GS1.
• GS1 Composite (CC-C) — một thành phần cơ sở 1D được liên kết cộng với một thành phần mở rộng 2D PDF417 mật độ cao mang theo dữ liệu GS1 Application Identifier. (Việc mã hóa thành phần mở rộng 2D CC-A và CC-B không được hỗ trợ trong bản phát hành này; xem ma trận hỗ trợ.)

Mỗi bộ mã hóa tạo ra một đối tượng dữ liệu mã vạch mà trình render trang chuyển thành các toán tử nội dung PDF. Việc mã hóa là tất định: cùng đầu vào và tùy chọn luôn tạo ra cùng mẫu module, điều này giữ cho các tài liệu đã ký và đã lưu trữ có thể tái lập.

Tài liệu tham chiếu chuyên sâu mã vạch mang theo một ma trận hỗ trợ theo từng bộ ký hiệu kèm bằng chứng. Đối với mỗi bộ ký hiệu và biến thể, ma trận ghi lại một trong ba trạng thái: một fixture phù hợp trong-kho thực thi nó (Verified), bề mặt triển khai khẳng định nó mà không có một fixture chuyên dụng (Claimed), hoặc nó rơi ra ngoài phạm vi (Not supported). NextPDF báo cáo ma trận một cách trung thực: một biến thể đi kèm một bộ mã hóa nhưng thiếu một fixture reference-trace vẫn ở trạng thái Claimed kèm một ghi chú backfill thay vì bị nói quá.

Vì sao nó hoạt động theo cách này

Mỗi bộ mã hóa của Pro là một hàm thuần: cùng payload và tùy chọn luôn tạo ra cùng ma trận module, không có trạng thái ẩn hay tính ngẫu nhiên có seed. Tính tất định đó là quyết định chịu lực. Nó cho phép một mã vạch đi vòng qua một tài liệu đã ký hoặc đã lưu trữ mà không làm nhiễu byte stream, nên một lần render lại không bao giờ làm mất hiệu lực một chữ ký. Nó cũng khiến tính phù hợp có thể kiểm toán: ma trận hỗ trợ ghim mỗi bộ ký hiệu vào một reference trace đã lưu, được kiểm tra từng-bit-một so với một golden file. Việc mở rộng BarcodeEncoderRegistry của Core thay vì fork nó giữ cho các đảm bảo này giống hệt nhau qua phiên bản mở và Pro.

Bối cảnh thiết kế: Cùng những byte mỗi lần: các PDF có thể tái lập.

Bề mặt API

composer require nextpdf/pro:^3

Bề mặt mã vạch công khai của Pro bao gồm:

• Một điểm vào service-provider tĩnh đăng ký các bộ mã hóa 2D của Pro vào một registry bộ mã hóa mã vạch (MicroQR, DotCode, HanXin, JabCode, RMQR, GS1DataBar, và khóa thành phần GS1 Composite CC-C gs1-composite-cc-c). Việc mã hóa thành phần mở rộng 2D GS1 Composite CC-A và CC-B không được hỗ trợ trong bản phát hành này và không được đăng ký.
• Một bộ phân tích GS1 Application Identifier chấp nhận cả các chuỗi AI dễ đọc lẫn các URI GS1 Digital Link và tạo ra các chuỗi byte đã mã hóa cho các vật mang GS1-128, QR Code, và Data Matrix.
• Một bộ xác thực chuỗi cung ứng GS1 kiểm tra các check digit, cấu trúc AI, logic ngày tháng, và các tổ hợp AI bắt buộc theo hồ sơ ngành.

Bảng chữ ký phương thức được tạo ra đầy đủ render trên tài liệu tham chiếu chuyên sâu mã vạch.

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

use NextPDF\Barcode\BarcodeEncoderRegistry;
use NextPDF\Pro\Barcode\BarcodeProServiceProvider;

$registry = new BarcodeEncoderRegistry();
BarcodeProServiceProvider::register($registry);
// $registry now resolves the Pro specialty symbologies.

Mẫu mã — Sản phẩm

use NextPDF\Pro\Barcode\Gs1\Gs1Validator;
use NextPDF\Pro\Barcode\Gs1\Gs1SupplyChainProfile;

$result = Gs1Validator::validate(
    '(01)09521234543213(17)260131(10)ABC123',
    Gs1SupplyChainProfile::NONE,
);

if (! $result->isValid) {
    // Surface findings to your observability pipeline before encoding.
    foreach ($result->findings as $finding) {
        $logger->warning('GS1 validation finding', [
            'rule' => $finding->ruleId,
            'detail' => $finding->message,
        ]);
    }
}

Trường hợp ngoại lệ & lưu ý

• Registry mặc định ràng buộc trước các mục bộ mã hóa của Pro một cách lười và kiểm soát chúng thông qua registry năng lực. Một lệnh gọi BarcodeProServiceProvider::register() tường minh là phương án dự phòng được hỗ trợ khi một ứng dụng tự kết hợp registry của riêng mình mà không có mặc định.
• Việc đăng ký lại là bất biến (idempotent): một lệnh gọi register() thứ hai thay thế ràng buộc đầu tiên thay vì ném lỗi.
• Phạm vi biến thể GS1 DataBar là một phần theo thiết kế. Omnidirectional, Truncated, Stacked, Stacked Omnidirectional, và Limited là reference-verified; Expanded và Expanded Stacked nằm ngoài phạm vi trong bản phát hành này. Xem ma trận hỗ trợ.
• rMQR chấp nhận mọi phiên bản ISO 23941 thông qua bộ phù hợp được Annex xác thực. Siêu dữ liệu theo-dõi-phạm-vi có trước việc mở rộng dải-kích-thước sau này có thể nói chưa đủ về điều này; ma trận hỗ trợ ghi lại thực tế đã được mã xác minh.

Hiệu năng

Chi phí mã hóa tỷ lệ với độ dài payload và kích thước ký hiệu đích. Mỗi bộ ký hiệu bố trí ký hiệu của nó trong một lần duyệt duy nhất không có reflow. Các tầng nhiều ký hiệu của JabCode tỷ lệ với số ký hiệu (1–61). Việc mã hóa giữ ma trận module trong bộ nhớ; phiên bản ký hiệu lớn nhất được chọn giới hạn chi phí.

Lưu ý bảo mật

Các bộ mã hóa mã vạch không thực thi nội dung payload; chúng mã hóa nó dưới dạng dữ liệu. Việc xác thực GS1 từ chối các cấu trúc AI dị dạng và các check digit không hợp lệ trước khi mã hóa, điều này ngăn một chuỗi chuỗi-cung-ứng dị dạng tạo ra một ký hiệu có thể quét được nhưng không phù hợp. Bản thân các bộ mã hóa không ghi nhật ký payload nào; các ứng dụng phải làm sạch các payload nhạy cảm khỏi nhật ký của riêng họ.

Tính phù hợp

Mỗi bộ ký hiệu tuân theo tiêu chuẩn đã xuất bản liên quan của nó (ISO/IEC 24724 cho GS1 DataBar, ISO/IEC 24723 cho GS1 Composite, ISO/IEC 23941 cho rMQR, ISO/IEC 18004 Annex cho Micro QR, ISO/IEC 20830 cho Han Xin Code, ISO/IEC 23634 cho JabCode, USPS-B-3200 cho bộ ký hiệu bưu chính). Việc ánh xạ phù hợp ở mức điều khoản kèm các mã định danh trích dẫn render trên tài liệu tham chiếu chuyên sâu mã vạch.

Ranh giới xuất bản

Trang này chỉ tài liệu hóa hành vi có thể quan sát từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, các class trợ giúp, các bảng cơ chế, các tên file runbook, và các tiền tố ticket nằm ngoài phạm vi.

Xem thêm

• Module mã vạch Core
• Chart — NextPDF Pro
• Tài liệu tham chiếu chuyên sâu mã vạch