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

Nhúng trong 10 phút

Từ bản Docker DEV tới một trang HTML mở, sửa và lưu tệp docx, kèm cách mở tệp của chính bạn qua host.docker.internal.

Trong trang này

Mở tệp docx của bạn
Không chạy? Kiểm nhanh

Mục tiêu: trong khoảng 10 phút, một trang HTML của bạn mở được tệp docx trong trình soạn thảo O3O, lưu được, và bạn thấy callback máy chủ gửi đi. Mọi thứ chạy trên máy DEV với bản Docker v1.

Khởi động và kiểm tra
Chạy stack, rồi gọi /o3o/status: embed.enabled phải là true và upstream.coolwsd là "ok".
Thử trang mẫu
Mở http://localhost:8080/o3o/demo. Trang này dùng đúng api.js, có nút gọi từng phương thức và khung ghi sự kiện.
Viết trang của bạn
Lưu index.html bên dưới vào một thư mục trống.
Phục vụ trang
Chạy máy chủ tĩnh cổng 3000 rồi mở http://localhost:3000. Trang trên localhost cổng bất kỳ nhúng được khung soạn thảo mà không cần cấu hình thêm.
Sửa, lưu, xem callback
Gõ vài chữ, bấm Ctrl+S. Console in onSaved; /o3o/demo/callbacks liệt kê callback saved đã kiểm chữ ký.

BashBước 1 — khởi động

cd online
docker compose --env-file .env -f docker/compose.dev.yml up -d

# Lớp nhúng bật và gate thấy máy chủ soạn thảo
curl -s http://localhost:8080/o3o/status
#   "embed": {"enabled": true, ...}   "upstream": {"coolwsd": "ok", ...}

HTMLBước 3 — index.html

<!doctype html>
<html lang="vi">
<head>
  <meta charset="utf-8">
  <title>Thử O3O.Editor</title>
  <style>html, body { margin: 0; height: 100%; } #o3o-editor { height: 100vh; }</style>
</head>
<body>
  <div id="o3o-editor"></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",    // tệp mẫu có sẵn khi O3O_DEV_MODE=1
        title: "sample.docx",
        fileType: "docx",
        key: "quickstart-1"
      },
      editor: {
        mode: "edit",
        lang: "vi",
        user: { id: "dev-1", name: "Lập trình viên" },
        callbackUrl: "http://o3o-gate:8070/o3o/demo/callback"  // điểm nhận callback mẫu của gate
      },
      ui: { closeButton: true },
      events: {
        onReady: (e) => console.log("onReady", e),
        onDocumentLoaded: (e) => console.log("onDocumentLoaded", e),
        onModified: (e) => console.log("onModified", e.modified),
        onSaved: (e) => console.log("onSaved", e.version, e.url),
        onClose: () => document.body.textContent = "Đã đóng tài liệu.",
        onLimitReached: (e) => console.warn("onLimitReached", e.message),
        onError: (e) => console.error("onError", e.code, e.message)
      }
    });
    window.editor = editor;   // để gọi thử editor.save() trong console
  </script>
</body>
</html>

BashBước 4 và 5 — phục vụ trang, xem callback

# Trong thư mục chứa index.html
python -m http.server 3000
# Mở http://localhost:3000, gõ vài chữ, bấm Ctrl+S (hoặc gõ editor.save() trong console), rồi xem callback gate đã nhận:
curl -s http://localhost:8080/o3o/demo/callbacks

Mở tệp docx của bạn#

document.url do GATE tải, không phải trình duyệt. localhost bên trong container là chính container đó, và địa chỉ nội bộ bị chặn theo quy tắc chống SSRF. Trên Docker Desktop, máy của bạn là host.docker.internal; thêm tên này vào O3O_FETCH_ALLOW_HOSTS để gate được phép tải.

BashCho gate tải từ máy của bạn

# online/.env — cho gate tải tệp từ máy của bạn (Docker Desktop)
O3O_FETCH_ALLOW_HOSTS=host.docker.internal

# áp lại cho gate
cd online
docker compose --env-file .env -f docker/compose.dev.yml up -d o3o-gate

# đặt tệp cạnh index.html rồi chạy lại máy chủ tĩnh (lắng nghe mọi giao diện mạng)
cp ~/Documents/hop-dong.docx .
python -m http.server 3000 --bind 0.0.0.0

JavaScriptThay khối document trong index.html

document: {
  url: "http://host.docker.internal:3000/hop-dong.docx",   // gate tải từ máy của bạn, không phải trình duyệt
  title: "Hợp đồng mẫu.docx",
  fileType: "docx",
  key: "hopdong-42-v1"                                        // đổi khi nội dung tệp gốc đổi
},

Không chạy? Kiểm nhanh#

Dấu hiệu	Nguyên nhân	Cách sửa
`onError`: `url_not_allowed`	URL trỏ tới địa chỉ nội bộ chưa được cho phép	Dùng `host.docker.internal` và đặt `O3O_FETCH_ALLOW_HOSTS`.
`onError`: `download_failed`	Máy chủ tệp không chạy, sai đường dẫn, hoặc chỉ lắng nghe `127.0.0.1`	Chạy với `--bind 0.0.0.0`; thử `curl` URL đó từ máy.
`onError`: `embed_auth_not_configured`	Máy chủ không có khoá JWT và không bật chế độ không ký	Máy DEV: `O3O_EMBED_ALLOW_UNSIGNED=1`. Chạy thật: đặt `O3O_EMBED_JWT_SECRET` và ký config.
`onError`: `origin_not_allowed`	Origin của trang không nằm trong `O3O_EMBED_ALLOWED_ORIGINS`	Thêm origin, ví dụ `http://localhost:3000`.
Khung trống, trình duyệt từ chối nhúng	Trang không chạy trên `localhost` và origin chưa được phép nhúng	Đặt `O3O_ONLINE_FRAME_ANCESTORS`, xem lỗi và giới hạn.

Ký cấu hình bằng JWTBắt buộc trước khi chạy thật.Lưu và callbackNhận và kiểm bản đã sửa.Ví dụ tích hợpExpress, Laravel, Flask, ASP.NET Core.

Báo lỗi hoặc góp ý cho trang nàyO3O Office Online · API v1 · Phiên bản trang 26.8.6