Nhúng trình soạn thảo

Lớp nhúng cho phép bất kỳ trang web nào mở trình soạn thảo O3O Office Online trong một <iframe>, không cần Nextcloud hay một hệ lưu trữ nói WOPI. Trang của bạn chỉ cần hai thứ: một URL để máy chủ O3O tải tệp gốc, và (nếu muốn nhận bản đã sửa) một URL nhận callback.

Các thành phần#

Một lần mở tài liệu diễn ra thế nào#

1. Trang của bạn nạp http://localhost:8080/o3o/api.js rồi gọi new O3O.Editor("id", config). api.js tự suy ra địa chỉ máy chủ từ thuộc tính src của chính thẻ script.
2. api.js gửi config (không kèm events) tới POST /o3o/embed/session.
3. Gate kiểm origin và JWT, tải document.url theo quy tắc chống SSRF, xét trần kết nối, rồi trả địa chỉ trình soạn thảo kèm access_token của phiên.
4. api.js dựng iframe và gửi form POST vào đó; token nằm trong thân form, không bao giờ lên URL.
5. Máy chủ soạn thảo đọc tệp từ gate qua mạng nội bộ. Khi lưu, gate ghi phiên bản mới, trả lời máy chủ soạn thảo ngay, rồi gửi callback về callbackUrl.
6. Trang của bạn nhận sự kiện qua postMessage: onReady, onDocumentLoaded, onModified, onSaved, onClose, onLimitReached, onError.
7. Mọi người rời tài liệu 30 giây: gate gửi callback closed, giữ bản làm việc 24 giờ rồi xoá.

Ví dụ ngắn nhất#

<!-- Trang HTML tối thiểu, chạy được trên máy DEV (O3O_DEV_MODE=1) -->
<div id="o3o-editor" style="height: 720px"></div>
<script src="http://localhost:8080/o3o/api.js"></script>
<script>
  const editor = new O3O.Editor("o3o-editor", {
    document: {
      url: "http://localhost:8080/o3o/demo/sample.docx",
      title: "sample.docx",
      fileType: "docx",
      key: "sample-1"
    },
    editor: { mode: "edit", lang: "vi", user: { id: "u-1001", name: "Nguyễn Văn A" } },
    events: {
      onDocumentLoaded: () => console.log("đã nạp"),
      onSaved: (e) => console.log("đã lưu phiên bản", e.version),
      onError: (e) => console.error(e.code, e.message)
    }
  });
</script>

Khi nào dùng lớp nhúng#

Có gì trong v1#

• O3O.Editor với 7 sự kiện và 5 phương thức.
• Ký cấu hình bằng JWT HS256; callback ký HMAC SHA-256.
• Hai chế độ edit và view; phiên view không tính kết nối.
• Chạm trần kết nối: phiên mới mở ở chế độ chỉ đọc kèm băng thông báo tiếng Việt, không bao giờ ngắt phiên đang sửa hay chặn lưu.
• Giữ 5 phiên bản gần nhất và bản gốc trong 24 giờ; URL tải có chữ ký.
• Quy tắc chống SSRF cho mọi URL mà máy chủ tự gọi; trang thử /o3o/demo trên máy DEV.