Lõi API

API cốt lõi

Hướng dẫn này cho thấy cách mở, chỉnh sửa, lắp ráp và lưu tài liệu PDF bằng các lớp Document và Page — các điểm vào cho mọi thao tác trong Aspose.PDF FOSS cho TypeScript. Document tải, tạo, lắp ráp và lưu toàn bộ tệp PDF; Page, truy cập qua doc.Pages, cung cấp các thao tác trên từng trang như văn bản, hình ảnh, chú thích và luồng nội dung.


Vòng đời Tài liệu

Document.OpenFile() mở một PDF từ đường dẫn tệp; Document.Open() chấp nhận một Uint8Array trong bộ nhớ. Các trang có thể được kiểm tra và chỉnh sửa tại chỗ, và Document.WriteTo() ghi lại kết quả — tùy chọn với nén xref-stream và object-stream.

import { Document } from '@asposefoss/pdf';

// Open from disk (or Document.Open(uint8array) for in-memory data)
const doc = Document.OpenFile('input.pdf');

// Inspect and edit pages
const pages = doc.Pages;
console.log(pages.length);
pages[0].Rotate = 90;
doc.RemovePage(2);                 // 1-based page number
doc.Reorder([3, 1, 2]);

// Metadata
doc.SetMetadata({ title: 'Report', author: 'Jane', custom: { Dept: 'R&D' } });

// Save
doc.WriteTo('output.pdf');         // or: const bytes = doc.Save();
doc.WriteTo('small.pdf', { compressed: true }); // xref stream + object streams

Tách, Gộp và Trích xuất Trang

Document.Split() trả về một Document cho mỗi trang. Document.ExtractPages() nhận một danh sách trang dựa trên chỉ số bắt đầu từ 1, cho phép lặp lại và trả về một Document mới chỉ chứa các trang đó. Document.Append() và Document.InsertPage() sao chép các trang giữa các tài liệu, và Document.Merge() kết hợp nhiều tài liệu thành một.

const parts = doc.Split();                       // one Document per page
const chapter = doc.ExtractPages([3, 4, 5]);     // subset (1-based, repeats allowed) as a new Document

docA.Append(docB);                               // copy all of docB's pages onto docA
docA.InsertPage(1, docB.Pages[0]);               // copy a single page across documents

Tạo Tài liệu Mới

Document.New() khởi tạo một tài liệu trống tại PageFormat cho trước. Page.AddText() đặt văn bản có vị trí, và Document.AddPage() thêm các trang tiếp theo, bao gồm một định dạng xoay như PageFormat.A4.landscape().

import { Document, PageFormat } from '@asposefoss/pdf';
const doc = Document.New(PageFormat.A4);          // one blank A4 page
doc.Pages[0].AddText('Hello', 72, 720, { fontSize: 14 });
doc.AddPage(PageFormat.A4.landscape());           // append more as you go
doc.WriteTo('scratch.pdf');

Đánh dấu và Số trang

Page.AddText() cũng hỗ trợ xoay, màu sắc và độ trong suốt, đủ để hiển thị số trang và dấu nước chéo mà không cần bất kỳ lớp bổ sung nào.

const doc = Document.OpenFile('in.pdf');
const page = doc.Pages[0];

// Page number, right-aligned near the bottom-right corner.
const w = page.Rect[2] - page.Rect[0];
page.AddText(`Page ${page.Number}`, w - 40, 20, { fontSize: 10, align: 'right' });

// Semi-transparent diagonal watermark, centered on the page.
page.AddText('DRAFT', page.Rect[2] / 2, page.Rect[3] / 2, {
  font: 'Times-Bold', fontSize: 64, color: [0.7, 0.7, 0.7], opacity: 0.4, rotate: 45, align: 'center',
});

doc.WriteTo('out.pdf');

Phân tích luồng nội dung

parseContentStream() giải mã luồng /Contents thô của một trang thành danh sách các cặp toán tử/ toán hạng, và serializeContentStream() chuyển danh sách toán tử đã chỉnh sửa trở lại thành byte.

import { parseContentStream, serializeContentStream } from '@asposefoss/pdf';

const ops = parseContentStream(doc.Pages[0].Contents);
// ops: { operator: string, operands: PdfObject[], inlineImage?: {...} }[]
for (const op of ops) {
  if (op.operator === 'Tj') console.log('text op:', op.operands);
}
const bytes = serializeContentStream(ops);       // round-trips operators + operands

Luồng văn bản đa cột

Page.AddTextBlock() chảy một chuỗi văn bản dài vào một vùng hình chữ nhật và trả về bất kỳ văn bản nào không vừa, có thể đưa vào lần gọi thứ hai để tiếp tục luồng vào cột khác.

const rest = page.AddTextBlock(longText, [72, 600, 200, 150], {
  font: 'Times-Roman', fontSize: 11, align: 'justify', valign: 'top', leading: 14,
});
if (rest) page.AddTextBlock(rest, [300, 600, 200, 150]); // continue into a 2nd column

Mẹo và Thực hành tốt nhất

  • Sử dụng Document.OpenFile() cho đường dẫn tệp và Document.Open() cho dữ liệu Uint8Array trong bộ nhớ.
  • Các số trang được truyền vào các phương thức như RemovePage() và ExtractPages() là dạng đánh số bắt đầu từ 1, trong khi doc.Pages là một mảng đánh số bắt đầu từ 0.
  • Gửi { compressed: true } tới Document.WriteTo() để bật nén xref-stream và object-stream trên đầu ra.
  • Document.ExtractPages() chấp nhận các số trang lặp lại, vì vậy cùng một trang nguồn có thể xuất hiện hơn một lần trong kết quả.
  • Đọc page.Rect để tính toán vị trí dựa trên chiều rộng và chiều cao thực tế của trang thay vì mã hóa cố định các tọa độ.

Các vấn đề thường gặp

Vấn đềNguyên nhânCách khắc phục
Document.Open() / OpenFile() báo lỗi InvalidPasswordErrorTệp PDF được bảo vệ bằng mật khẩu và không có mật khẩu nào được cung cấp (hoặc mật khẩu sai)Cung cấp { password: '...' } cho Document.OpenFile() / Document.Open()
RemovePage() xóa trang saiSố trang được truyền cho RemovePage() bắt đầu từ 1, không phải từ 0Chuyển một số trang bắt đầu từ 1, khác với chỉ mục mảng doc.Pages
Đầu ra WriteTo() lớn hơn mong đợiLưu mặc định không sử dụng nén xref/object-streamChuyển { compressed: true } tới Document.WriteTo()

FAQ

Document.Open() có chấp nhận cả đường dẫn tệp và dữ liệu trong bộ nhớ không?

Document.OpenFile() mở từ một đường dẫn tệp; Document.Open() chấp nhận một Uint8Array các byte trong bộ nhớ.

Đánh số trang là 0-based hay 1-based?

Cả hai, tùy thuộc vào API: doc.Pages là một mảng 0-based thuần túy, nhưng các phương thức như RemovePage() và ExtractPages() nhận số trang 1-based.

Tôi có thể mã hóa tài liệu khi lưu nó không?

Có — truyền tùy chọn encrypt cho WriteTo() / Save() cùng với algorithm: 'aes256' | 'aes128' | 'rc4' và mật khẩu người dùng/chủ sở hữu tùy chọn.

Làm thế nào để giảm kích thước tệp đầu ra?

Truyền { compressed: true } cho Document.WriteTo() để bật nén xref-stream và object-stream.

Tôi có thể kiểm tra các toán tử luồng nội dung thô của một trang không?

Có — parseContentStream(doc.Pages[0].Contents) trả về danh sách toán tử, và serializeContentStream() chuyển danh sách đã chỉnh sửa lại thành byte.


API Reference Tóm tắt

Lớp / Phương thứcMô tả
DocumentĐiểm vào trung tâm để tạo, tải và lưu tài liệu PDF
Document.OpenFile() / Document.Open()Tải PDF từ đường dẫn tệp hoặc từ byte trong bộ nhớ
Document.New()Bắt đầu một tài liệu trống với PageFormat cho trước
Document.WriteTo() / Document.Save()Ghi tài liệu vào đường dẫn tệp hoặc trả về byte
Document.Split() / Document.Merge() / Document.ExtractPages()Tách, hợp nhất và trích xuất các trang giữa các tài liệu
Document.Append() / Document.InsertPage()Sao chép các trang từ một tài liệu sang tài liệu khác
PageMột trang PDF đơn lẻ; cung cấp các phương thức văn bản, hình ảnh, chú thích và content-stream
Page.AddText() / Page.AddTextBlock()Thêm văn bản positioned hoặc flowed vào trang
parseContentStream() / serializeContentStream()Phân tích và tái tuần tự hoá các toán tử content-stream thô của một trang

Xem thêm

 Tiếng Việt