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ệuUint8Arraytrong 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 khidoc.Pageslà một mảng đánh số bắt đầu từ 0. - Gửi
{ compressed: true }tớiDocument.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ân | Cách khắc phục |
|---|---|---|
Document.Open() / OpenFile() báo lỗi InvalidPasswordError | Tệ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 sai | Số trang được truyền cho RemovePage() bắt đầu từ 1, không phải từ 0 | Chuyể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 đợi | Lưu mặc định không sử dụng nén xref/object-stream | Chuyể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ức | Mô 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 |
Page | Mộ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 |