docai-sdk

DocAI SDK là core library dùng để làm việc với PDF (load, render) và các khả năng DocAI cao hơn sau này (annotation, AI, compare), tách biệt hoàn toàn UI. Có thể dùng trong React, Angular, Vue hoặc bất kỳ framework nào hỗ trợ JavaScript/TypeScript.

Cài đặt

npm install docai-sdk
# hoặc
yarn add docai-sdk
# hoặc
pnpm add docai-sdk

SDK yêu cầu pdfjs-dist và chạy trong môi trường browser (có HTMLCanvasElement).

API chính

Hiện tại SDK tập trung vào module PDF:

• DocAI.init(options?) → khởi tạo SDK
• docai.openPdf(source) → mở một tài liệu PDF
• docai.renderPdfPage({ document, pageNumber, target, viewportOptions }) → render một trang PDF lên canvas

Khởi tạo DocAI

import { DocAI } from 'docai-sdk';

async function createClient() {
  const docai = await DocAI.init({
    pdfWorkerSrc: `https://cdnjs.cloudflare.com/ajax/libs/pdf.js/5.3.31/pdf.worker.min.mjs`,
  });

  return docai;
}

DocAIOptions:

• pdfWorkerSrc?: string – URL tới file pdf.worker.min.mjs của pdf.js. Nên set rõ để tránh lỗi worker trong các bundler.

PdfSource

openPdf chấp nhận nhiều loại source:

import type { PdfSource } from 'docai-sdk/dist/index';

// Các dạng PdfSource hỗ trợ:
// { url: string }
// { data: Uint8Array }
// { file: File | Blob }

Ví dụ:

const fromUrl = { url: 'https://example.com/sample.pdf' };
const fromData = { data: new Uint8Array(arrayBuffer) };
const fromFile = { file: fileInput.files[0] };

const pdfDoc = await docai.openPdf(fromUrl);

Render 1 trang PDF lên canvas

const canvas = document.getElementById('pdf-canvas') as HTMLCanvasElement;

const pdfDoc = await docai.openPdf({ url: '/sample.pdf' });

await docai.renderPdfPage({
  document: pdfDoc,
  pageNumber: 1,
  target: {
    type: 'canvas',
    canvas,
  },
  viewportOptions: {
    scale: 1.5,
  },
});

viewportOptions:

• scale?: number – hệ số zoom (mặc định 1).
• width?/height? – hiện tại chưa dùng, nhưng được để sẵn cho future API (tính scale theo kích thước mong muốn).

Interop với pdf.js viewer

SDK sử dụng pdfjs-dist bên trong, nhưng bạn vẫn có thể dùng pdf.js viewer cao cấp (như PDFViewer từ pdfjs-dist/web/pdf_viewer.mjs) bằng cách lấy native document:

const sdkDocument = await docai.openPdf({ url: '/sample.pdf' });
const pdfjsDocument = sdkDocument.getNativeDocument(); // PDFDocumentProxy của pdf.js

pdfLinkService.setDocument(pdfjsDocument);
pdfViewer.setDocument(pdfjsDocument);

Cách này cho phép bạn:

• Dùng DocAI để chuẩn hoá cách mở PDF, cấu hình worker…
• Nhưng vẫn tái sử dụng toàn bộ UI viewer pdf.js hiện tại.

Sử dụng trong React (ví dụ đơn giản)

import React, { useEffect, useRef } from 'react';
import { DocAI } from 'docai-sdk';

export function SimplePdfCanvas() {
  const canvasRef = useRef<HTMLCanvasElement | null>(null);

  useEffect(() => {
    (async () => {
      const docai = await DocAI.init({
        pdfWorkerSrc:
          'https://cdnjs.cloudflare.com/ajax/libs/pdf.js/5.3.31/pdf.worker.min.mjs',
      });

      const pdfDoc = await docai.openPdf({ url: '/sample.pdf' });

      if (canvasRef.current) {
        await docai.renderPdfPage({
          document: pdfDoc,
          pageNumber: 1,
          target: { type: 'canvas', canvas: canvasRef.current },
          viewportOptions: { scale: 1.2 },
        });
      }
    })();
  }, []);

  return <canvas ref={canvasRef} />;
}

Định hướng mở rộng

Kế hoạch các module tiếp theo trong SDK:

• annotation – quản lý store annotation, logic chọn/sửa/xoá, export/import JSON, tách khỏi UI (SVG/canvas-agnostic).
• ai – gọi các API DocAI (review, auto-label, suggest annotations…).
• compare – so sánh 2 PDF theo pixel/text.

Khi các module này sẵn sàng, API sẽ mở rộng quanh class DocAI (ví dụ docai.annotation, docai.ai, docai.compare), nhưng phần PDF core ở trên sẽ giữ backward-compatible.