Thư viện html-to-docx cung cấp giải pháp hiệu quả để chuyển đổi nội dung HTML thành tài liệu Word định dạng DOCX, duy trì đầy đủ định dạng và kiểu dáng ban đầu.

Tổng quan về thư viện chuyển đổi

html-to-docx là một thư viện JavaScript chuyên dụng giúp xử lý việc chuyển đổi từ mã HTML sang định dạng Office Open XML. Thư viện này phân tích cấu trúc HTML và ánh xạ các thuộc tính CSS thành các định dạng tương ứng trong Word, đảm bảo tài liệu đầu ra giữ nguyên bố cục gốc.

Lợi ích chính của giải pháp

• Bảo toàn định dạng: Duy trì các thuộc tính như phông chữ, màu sắc, căn chỉnh và cấu trúc bảng biểu
• Tính tương thích cao: Tương thích với Microsoft Word 2007+, Google Docs, LibreOffice Writer
• Cấu hình linh hoạt: Hỗ trợ tùy chỉnh kích thước trang, lề, tiêu đề/chân trang
• Không phụ thuộc bên ngoài: Hoạt động độc lập, không cần dịch vụ web bổ sung

Đối tượng sử dụng phù hợp

Giải pháp này đặc biệt hữu ích cho các nhóm phát triển doanh nghiệp, nhà phát triển CMS, giảng viên và chuyên gia phân tích dữ liệu cần tạo báo cáo tự động hoặc xuất nội dung sang định dạng có thể chỉnh sửa.

Ví dụ ứng dụng thực tế

Hệ thống báo cáo tự động

Một nền tảng phân tích dữ liệu có thể sử dụng thư viện để tạo báo cáo định kỳ bằng cách thiết kế mẫu HTML, điền dữ liệu động và chuyển đổi thành tài liệu Word chuyên nghiệp.

Chức năng xuất trong CMS

const { HTMLtoDOCX } = require('html-to-docx');

async function xuatBaiViet(baiVietId) {
  const baiViet = await layBaiVietTuDB(baiVietId);
  const buffer = await HTMLtoDOCX(baiViet.noiDung);
  return buffer;
}

Công cụ chuyển đổi hàng loạt

const fs = require('fs');
const path = require('path');
const { HTMLtoDOCX } = require('html-to-docx');

async function chuyenDoiHangLoat(thuMucGoc, thuMucDich) {
  const danhSachTep = fs.readdirSync(thuMucGoc);
  
  for (const tep of danhSachTep) {
    if (path.extname(tep) === '.html') {
      const noiDungHTML = fs.readFileSync(path.join(thuMucGoc, tep), 'utf8');
      const bufferDOCX = await HTMLtoDOCX(noiDungHTML);
      const duongDanXuat = path.join(thuMucDich, tep.replace('.html', '.docx'));
      fs.writeFileSync(duongDanXuat, bufferDOCX);
    }
  }
}

Hướng dẫn bắt đầu nhanh

Bước 1: Cài đặt thư viện

npm install html-to-docx

Bước 2: Tạo script chuyển đổi

const { HTMLtoDOCX } = require('html-to-docx');
const fs = require('fs');

async function taoTaiLieu() {
  const html = `
    <h1 style="color: #2c3e50;">Báo cáo tiến độ dự án</h1>
    <p style="font-size: 14pt;">Tóm tắt tình hình hiện tại của dự án.</p>
    <ul>
      <li>Hoàn thành phân tích yêu cầu</li>
      <li>Đang thực hiện thiết kế hệ thống</li>
      <li>Dự kiến bắt đầu phát triển tuần tới</li>
    </ul>
  `;
  
  try {
    const buffer = await HTMLtoDOCX(html);
    fs.writeFileSync('bao-cao-du-an.docx', buffer);
    console.log('Tạo tài liệu thành công!');
  } catch (loi) {
    console.error('Chuyển đổi thất bại:', loi);
  }
}

taoTaiLieu();

Bước 3: Chạy và kiểm tra kết quả

Sau khi thực thi script, bạn sẽ nhận được tệp "bao-cao-du-an.docx" với định dạng hoàn chỉnh có thể mở bằng bất kỳ phần mềm văn phòng nào.

Tùy chỉnh cấu hình tài liệu

Thiết lập trang in

const tuyChinh = {
  orientation: 'portrait',
  pageSize: { width: 12240, height: 15840 },
  margins: { top: 1440, right: 1800, bottom: 1440, left: 1800 },
  title: 'Báo cáo tài chính quý',
  font: 'Arial',
  fontSize: 24
};

const buffer = await HTMLtoDOCX(noiDungHTML, null, tuyChinh);

Kiểm soát kiểu dáng nâng cao

<!-- Phân trang -->
<div style="page-break-after: always;"></div>

<!-- Bảng biểu -->
<table style="border-collapse: collapse; width: 100%;">
  <tr style="background-color: #f2f2f2;">
    <th style="border: 1px solid #ddd; padding: 8px;">Tên</th>
    <th style="border: 1px solid #ddd; padding: 8px;">Phòng ban</th>
  </tr>
  <tr>
    <td style="border: 1px solid #ddd; padding: 8px;">Nguyễn Văn A</td>
    <td style="border: 1px solid #ddd; padding: 8px;">Kỹ thuật</td>
  </tr>
</table>

Thực hành tối ưu hiệu suất

Xử lý nội dung lớn

async function xuLyNoiDungLon(htmlLon) {
  const cacDoan = chiaDoanHTML(htmlLon, 5000);
  const ketQua = [];
  
  for (const doan of cacDoan) {
    const buffer = await HTMLtoDOCX(doan);
    ketQua.push(buffer);
  }
  
  return hopNhatBuffer(ketQua);
}

Xử lý lỗi và gỡ rối

async function chuyenDoiAnToan(html, tuyChinh = {}) {
  try {
    if (!html || typeof html !== 'string') {
      throw new Error('Nội dung HTML không hợp lệ');
    }
    
    const buffer = await HTMLtoDOCX(html, null, tuyChinh);
    
    if (!buffer || buffer.length === 0) {
      throw new Error('Kết quả chuyển đổi rỗng');
    }
    
    return buffer;
  } catch (loi) {
    console.error('Lỗi chuyển đổi:', loi);
    return taoTaiLieuLoi(loi.message);
  }
}

Kiến trúc hệ thống

Thư viện được tổ chức theo mô-đun gồm các thành phần chính:

• Mô-đun chuyển đổi chính: Xử lý logic phân tích HTML
• Bộ xây dựng tài liệu: Tạo cấu trúc XML theo chuẩn Office Open
• Xử lý định dạng: Ánh xạ CSS sang định dạng Word
• Tiện ích hỗ trợ: Chuyển đổi màu sắc, đơn vị đo lường, danh sách

Câu hỏi thường gặp

Thư viện có chạy được trên trình duyệt không?

Chủ yếu được thiết kế cho môi trường Node.js nhưng có thể tích hợp vào trình duyệt với một số hạn chế về xử lý ảnh và hệ thống tệp.

Cách xử lý ký tự Unicode?

Hoàn toàn hỗ trợ ký tự Unicode. Nên thiết lập phông chữ phù hợp như "Microsoft YaHei" hoặc "Arial Unicode MS" để hiển thị tốt nhất.

Ảnh trong HTML được xử lý thế nào?

Hỗ trợ ảnh base64 nhúng trực tiếp và URL ảnh từ xa. Ảnh cục bộ cần chuyển sang base64 trước khi xử lý.

Làm sao kiểm soát ngắt trang?

.ngat-trang {
  page-break-after: always;
}

Các kiểu danh sách được hỗ trợ?

Bao gồm: số thứ tự, chữ cái Latin, chữ số La Mã (hoa/thường) và các biến thể đánh dấu ngoặc đơn/kép.

Tích hợp vào dự án

git clone https://github.com/gh_mirrors/ht/html-to-docx
cd html-to-docx
npm install

Sau đó tích hợp vào dự án hiện có:

const { HTMLtoDOCX } = require('html-to-docx');

async function taoTaiLieuTuNoiDung(noiDung, tuyChinh) {
  return await HTMLtoDOCX(noiDung, null, tuyChinh);
}