Hướng dẫn AI

Chuyển đổi tài liệu Office sang PDF và PNG trong Node.js với LibreOffice Kit

Tìm hiểu cách cài đặt @deepseek-ai/libreoffice-kit, chuyển đổi tệp Office sang PDF, kết xuất các trang thành PNG, tính toán lại bảng tính, cấu hình phông chữ và quản lý các engine theo nền tảng trong Node.js.

1 tháng 10, 2026Thời gian đọc khoảng 22 phút

Chuyển đổi tài liệu Office sang PDF và PNG trong Node.js với LibreOffice Kit

Tổng quan

@deepseek-ai/libreoffice-kit là một gói Node.js dùng để chuyển đổi và kết xuất tài liệu Office với các engine LibreOffice dựng sẵn, đã được tinh gọn. Gói này dành cho các ứng dụng cần bố cục tài liệu nhất quán, văn bản dễ đọc, khả năng kiểm soát phông chữ rõ ràng và thực thi ngoại tuyến mà không phụ thuộc vào một bản LibreOffice được cài đặt riêng.

Gói hỗ trợ chuyển đổi Office sang PDF, kết xuất trực tiếp sang PNG và tính toán lại bảng tính. Gói có thể được sử dụng trong dịch vụ Node.js, ứng dụng máy tính, tác vụ xử lý hàng loạt hoặc quy trình tài liệu khác. Ứng dụng phải tự chịu trách nhiệm về việc cấp quyền, lưu trữ tệp và giao diện xem trước.

Tính năng chính

Chuyển đổi Office: Xuất các tài liệu Writer, Calc và Impress được hỗ trợ sang PDF.
Kết xuất trang: Kết xuất trực tiếp tệp Office hoặc PDF thành các trang PNG.
Tính toán lại bảng tính: Tính toán lại sổ làm việc và lưu kết quả đã cập nhật.
Xử lý theo phông chữ: Phát hiện phông chữ hệ thống hoặc lập chỉ mục các thư mục phông chữ được cấu hình rõ ràng.
Thay thế có thể cấu hình: Sử dụng tùy chọn dự phòng cho các họ phông chữ Latin và tiếng Trung giản thể phổ biến.
Báo cáo phông chữ bị thiếu: Báo cáo các họ phông chữ không khả dụng được khai báo trong dữ liệu OOXML có thể đọc.
Engine ngoại tuyến: Sử dụng các engine gốc được đóng gói trên macOS và Windows được hỗ trợ hoặc engine WASM trên Linux.
Kiểm soát tài nguyên: Áp dụng thời gian chờ và giới hạn lập chỉ mục hoặc tải phông chữ.
API dòng lệnh và Node: Chạy chuyển đổi từ terminal hoặc tích hợp vào mã ứng dụng.

Lưu ý về tài liệu được hỗ trợ

Engine giữ lại các bộ lọc Writer, Calc, Impress, OOXML và Office nhị phân, cùng các thành phần biểu đồ, bố cục, bản vẽ và hỗ trợ xuất PDF. Các tệp nhị phân .doc, .xls và .ppt được hỗ trợ khi thực sự là tài liệu OLE dạng compound, chẳng hạn như các tệp Microsoft Office 97–2003.

Các tệp RTF hoặc HTML chỉ được đổi tên thành phần mở rộng Office nhị phân sẽ không được chấp nhận. Các tệp .wps cũng không được chấp nhận.

Đối với tài liệu OOXML, missingFonts báo cáo các họ phông chữ không khả dụng được tìm thấy trong XML tài liệu có thể đọc. Các định dạng nhị phân trả về danh sách rỗng dù LibreOffice vẫn thực hiện việc đối sánh phông chữ riêng. Vì vậy, kết quả này không phải là báo cáo đầy đủ về các glyph bị thiếu.

Điều kiện tiên quyết và cài đặt

Bạn cần Node.js 22.19.0 trở lên. Cài đặt phiên bản 0.1.3 từ npm:

npm install @deepseek-ai/libreoffice-kit@0.1.3

Gói sử dụng các dependency tùy chọn để cài đặt engine phù hợp với hệ điều hành và kiến trúc hiện tại. Gói không biên dịch LibreOffice trong quá trình cài đặt, không tải thêm engine và không tìm kiếm ứng dụng LibreOffice do người dùng cài đặt.

Lựa chọn engine theo nền tảng

macOS Apple Silicon: Sử dụng @deepseek-ai/libreoffice-kit-darwin-arm64.
macOS Intel: Sử dụng @deepseek-ai/libreoffice-kit-darwin-x64.
Windows ARM64: Sử dụng @deepseek-ai/libreoffice-kit-win32-arm64 và yêu cầu Node.js ARM64 cùng Microsoft Visual C++ v14 ARM64 Redistributable.
Windows x64: Sử dụng @deepseek-ai/libreoffice-kit-win32-x64 và yêu cầu Microsoft Visual C++ v14 x64 Redistributable.
Linux: Thông thường sử dụng engine dùng chung @deepseek-ai/libreoffice-kit-wasm.

macOS và Windows yêu cầu các gói gốc tương ứng và không chuyển sang WASM dự phòng. Nếu engine bắt buộc bị thiếu hoặc hỏng, createConverter sẽ từ chối với lỗi unavailable. Một lần chuyển đổi thất bại cũng không tự động kích hoạt việc chuyển sang engine khác.

Sử dụng giao diện dòng lệnh

Quá trình cài đặt thêm lệnh dsoffice. Khi được cài đặt cục bộ trong một dự án, hãy gọi lệnh thông qua npm exec.

Kết xuất một trang thành PNG

Lệnh sau kết xuất trang 1 của tài liệu DOCX vào thư mục đầu ra report-pages:

npm exec -- dsoffice render \
  --input report.docx \
  --output-dir report-pages \
  --pages 1

Chuyển đổi tài liệu Office sang PDF

npm exec -- dsoffice convert \
  --input report.docx \
  --output report.pdf

Tính toán lại bảng tính

Sử dụng lệnh tính toán lại khi cần đánh giá các công thức và lưu sổ làm việc đã cập nhật:

npm exec -- dsoffice recalculate \
  --input budget.xlsx \
  --output recalculated.xlsx

Chuyển đổi tài liệu thông qua API Node.js

Để tích hợp vào ứng dụng, hãy import createConverter, tạo converter, chạy thao tác và giải phóng converter trong khối finally.

import { createConverter } from '@deepseek-ai/libreoffice-kit';

const converter = await createConverter({
  timeoutMs: 120_000,
});

try {
  const result = await converter.render({
    inputPath: '/private/work/document.docx',
    outputPath: '/private/work/document.pdf',
  });

  console.log('Backend:', result.backend);
  console.log('Missing fonts:', result.missingFonts);
} finally {
  await converter.dispose();
}

Trong ví dụ này, tệp PDF được tạo sẽ được ghi vào outputPath. Kết quả trả về xác định backend được chọn và bao gồm tên các họ phông chữ bị thiếu được phát hiện trong tài liệu.

Yêu cầu về đường dẫn và đầu ra

Truyền vào các đường dẫn tuyệt đối cho tệp đầu vào và đầu ra.
Sử dụng các thư mục riêng tư do ứng dụng gọi sở hữu và kiểm soát.
Tệp đầu ra được yêu cầu không được tồn tại trước đó.
Đặt thao tác giải phóng trong khối finally để các tiến trình native, worker, profile và tài nguyên tạm thời được dọn dẹp.

Cấu hình phông chữ tùy chỉnh

Theo mặc định, gói sẽ tìm phông chữ trong các thư mục phông chữ hệ thống và người dùng theo quy ước. Bạn có thể cung cấp các thư mục gốc cụ thể thông qua fontDirectories:

import { createConverter } from '@deepseek-ai/libreoffice-kit';

const converter = await createConverter({
  timeoutMs: 120_000,
  fontDirectories: [
    '/absolute/path/to/company-fonts',
    '/absolute/path/to/cjk-fonts',
  ],
});

try {
  const result = await converter.render({
    inputPath: '/private/work/presentation.pptx',
    outputPath: '/private/work/presentation.pdf',
  });

  if (result.missingFonts.length > 0) {
    console.log('Unavailable families:', result.missingFonts);
  }
} finally {
  await converter.dispose();
}

Các thư mục gốc phông chữ tùy chỉnh sẽ thay thế danh sách tìm kiếm mặc định thay vì mở rộng danh sách đó. Gói sử dụng fontkit để kiểm tra siêu dữ liệu và phạm vi glyph, sau đó cung cấp các tệp đã chọn cho engine dưới dạng byte phông chữ gốc.

Không có bộ sưu tập phông chữ nào được đóng gói hoặc tải xuống. Bản triển khai của bạn phải cung cấp các phông chữ phù hợp và tuân thủ quyền phân phối lại của chúng. Các container tối giản thường cần cài đặt phông chữ hoặc cấu hình một thư mục phông chữ cụ thể.

Hành vi dự phòng

Mặc định, fontFallbacks bao gồm các tùy chọn ưu tiên cho những họ phông chữ Latin và tiếng Trung giản thể phổ biến. Các tùy chọn này bao gồm Carlito làm phương án thay thế khi Calibri không khả dụng và Caladea khi Cambria không khả dụng. Các nhóm phông chữ dự phòng do bên gọi cung cấp sẽ thay thế mặc định và chỉ có thể chọn những phông chữ thực sự khả dụng; chúng không cài đặt phông chữ.

Các họ phông chữ đã cài đặt chính xác được ưu tiên, bao gồm cả các họ phông chữ trang trí và viết tay. Các yêu cầu phông chữ WASM cũng truyền thông tin về độ đậm và kiểu nghiêng để hỗ trợ chọn kiểu chữ đã cài đặt phù hợp, trong khi danh mục phông chữ có thể cung cấp thêm phông chữ cho các glyph bị thiếu.

Mẹo vận hành nâng cao

Thận trọng khi tái sử dụng converter

Việc tái sử dụng converter có thể tận dụng các bộ nhớ đệm siêu dữ liệu phông chữ dùng chung trong bộ nhớ và trên ổ đĩa cục bộ của người dùng với dung lượng giới hạn đối với các phông chữ không thay đổi. Tuy nhiên, các thao tác trên cùng một converter được thực hiện tuần tự. Nếu dịch vụ của bạn cần một mô hình đồng thời cụ thể, hãy tính đến việc tuần tự hóa này thay vì giả định rằng nhiều lần render trên cùng một converter sẽ chạy đồng thời.

Mỗi lần render vẫn sở hữu một tiến trình native hoặc worker Node mới cùng một profile riêng tư. Việc hủy và giải phóng sẽ chờ engine thoát và hoàn tất dọn dẹp.

Thiết lập ngân sách tài nguyên phông chữ

Các thư mục phông chữ lớn hoặc không đáng tin cậy nên được giới hạn bằng các tùy chọn phông chữ hiện có:

maxFontFiles giới hạn số tệp phông chữ được lập chỉ mục.
maxFontFileBytes giới hạn kích thước của từng tệp phông chữ.
maxLoadedFontBytes giới hạn tổng lượng dữ liệu phông chữ được tải.

Mỗi thao tác đều tìm kiếm lại và xác thực lại các phông chữ. Siêu dữ liệu không thay đổi có thể được chia sẻ thông qua bộ nhớ đệm của factory converter. Hãy tham khảo tài liệu về bộ nhớ đệm siêu dữ liệu phông chữ để biết chi tiết cấu hình và vô hiệu hóa bộ nhớ đệm.

Lập kế hoạch khả dụng phông chữ trên Linux

Engine WASM trên Linux chỉ sử dụng các phông chữ được nhập vào. Nếu không có phông chữ khả dụng, quá trình chuyển đổi sẽ bị từ chối với lỗi unavailable. Vì vậy, container nên cài đặt các phông chữ phù hợp hoặc mount một thư mục phông chữ được kiểm soát, sau đó truyền đường dẫn tuyệt đối của thư mục đó vào fontDirectories.

Không giả định đầu ra Office giống hệt

Việc xử lý có nhận biết phông chữ giúp kiểm soát tốt hơn việc chọn họ phông chữ, nhưng không đảm bảo đầu ra giống hệt Microsoft Office hoặc giống hệt giữa các engine native và WASM. Chỉ số phông chữ có thể làm thay đổi ngắt dòng, phân trang, kích thước bảng và các chi tiết bố cục khác.

Để so sánh có ý nghĩa, hãy sử dụng cùng byte tài liệu, phông chữ và tùy chọn xuất. LibreOffice native có thể phân giải các họ phông chữ gốc đã cài đặt và các phương án thay thế tương thích về chỉ số trước các thay thế đã cấu hình, đồng thời tự thực hiện việc chọn kiểu chữ.

Coi quá trình chuyển đổi là một ranh giới xử lý tài liệu

Thư viện thực hiện chuyển đổi và kết xuất, nhưng không cung cấp tính năng phân quyền, lưu trữ hoặc giao diện xem trước. Ứng dụng nên xác thực quyền truy cập, cô lập các tệp do bên gọi sở hữu, chọn các thư mục làm việc riêng tư và áp dụng giới hạn thời gian cũng như tài nguyên phù hợp cho các tác vụ chuyển đổi.

Phát triển và xác minh

Nếu bạn đóng góp trực tiếp cho repository, có thể chạy các bước kiểm tra siêu dữ liệu, unit và đóng gói mà không cần build LibreOffice:

pnpm verify:metadata
pnpm test
pnpm test:packaging

Các bài kiểm tra engine thực tế cũng yêu cầu build adapter, các payload engine đã được chuẩn bị và LIBREOFFICE_RUNTIME_ENTRY trỏ đến đường dẫn tuyệt đối của packages/entry/lib/index.js. Bản build engine nên sử dụng các phiên bản mã nguồn và toolchain được repository ghim cố định.

Kết luận

@deepseek-ai/libreoffice-kit cung cấp một cách thực tế để tích hợp chuyển đổi Office, tính toán lại bảng tính và kết xuất PNG vào các ứng dụng Node.js hiện đại. Ưu điểm chính của gói là khả năng xử lý phông chữ rõ ràng, kết hợp với các engine native và WASM đã được chuẩn bị, có thể hoạt động ngoại tuyến. Để có kết quả đáng tin cậy, hãy cung cấp các phông chữ cần thiết, sử dụng các đường dẫn tuyệt đối riêng tư, thiết lập giới hạn phù hợp, kiểm tra missingFonts và luôn giải phóng converter sau khi sử dụng.

Để biết thêm về thao tác hủy, xử lý lỗi chi tiết và các tùy chọn kiểm soát tài nguyên bổ sung, hãy xem tài liệu Node API.