Bỏ qua, tới nội dung
Tài liệu APIv1

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

Tham chiếu cấu hình

Mọi trường của config: document, editor, ui, token và events, kèm kiểu, mặc định, quy tắc của document.key và lỗi invalid_config.

Trong trang này

new O3O.Editor(idPhanTu, config) nhận id của phần tử chứa (hoặc chính phần tử DOM) và một đối tượng config gồm bốn nhóm: document, editor, ui, token, cộng events chỉ nằm ở trình duyệt. Hàm tạo trả về ngay; việc tạo phiên chạy bất đồng bộ và lỗi đi qua onError.

  • Không tìm thấy phần tử: hàm tạo ném Error("O3O.Editor: không tìm thấy phần tử ...").
  • Mỗi phần tử chứa mang MỘT trình soạn thảo. Gọi hàm tạo lần hai trên cùng phần tử khi chưa destroy() thì ném lỗi.
  • Phần tử chứa phải có chiều cao thật (ví dụ height: 100vh), vì khung mặc định cao 100%.
JavaScriptCấu hình đầy đủ
const config = {
  document: {
    url: "https://files.example.com/contracts/42.docx",   // gate tải tệp gốc từ đây
    title: "Hợp đồng số 42.docx",
    fileType: "docx",
    key: "contract-42-v7"                                   // định danh PHIÊN BẢN nội dung
  },
  editor: {
    mode: "edit",                                           // "edit" | "view"
    lang: "vi",
    user: { id: "u-1001", name: "Nguyễn Văn A" },
    callbackUrl: "https://app.example.com/o3o/callback"
  },
  ui: {
    width: "100%",
    height: "100%",
    mode: "tabbed",                                         // "tabbed" | "compact"
    closeButton: true,
    saveButton: true,
    print: true,
    export: true,
    copy: true,
    userList: true,
    statusbar: true,
    menubar: false,
    limitBanner: true
  },
  token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",          // bắt buộc khi máy chủ đặt O3O_EMBED_JWT_SECRET
  events: {
    onSaved: (e) => console.log(e.version)
  }
};

const editor = new O3O.Editor("o3o-editor", config);

document#

document (bắt buộc)

  • document.urlstring (URL)bắt buộc
    URL http hoặc https để GATE tải tệp gốc. Chịu quy tắc chống SSRF. Trình duyệt không tải URL này.
  • document.titlestring, 1–255 ký tựbắt buộc
    Tên hiển thị. Thiếu đuôi thì gate thêm . + fileType. Chín ký tự cấm trong tên tệp Windows và ký tự điều khiển bị thay bằng _.
  • document.fileTypestringbắt buộc
    Một trong docx, doc, odt, rtf, txt, xlsx, xls, ods, csv, pptx, ppt, odp. Chữ thường, không có dấu chấm.
  • document.keystringbắt buộc
    Định danh PHIÊN BẢN nội dung, khớp ^[A-Za-z0-9._-]{1,128}$. Mọi người mở cùng key cùng sửa một tài liệu. Xem quy tắc bên dưới.

Quy tắc của document.key#

  • Gate chỉ tải document.url cho người ĐẦU TIÊN của một key; người sau dùng bản đang mở và url của họ bị bỏ qua.
  • Sau callback closed, lần mở kế tiếp PHẢI dùng key mới (thêm số phiên bản hoặc dấu thời gian sửa của tệp).
  • Dùng lại key cũ trong thời gian giữ (24 giờ) thì gate mở lại bản làm việc cuối cùng nó giữ, KHÔNG tải lại url.
  • Mã tài liệu nội bộ: doc_id = "doc_" + 32 ký tự hex đầu của SHA-256(key).

editor#

editor (bắt buộc)

  • editor.mode"edit" | "view"tuỳ chọnMặc định: "edit"
    view là chỉ đọc và KHÔNG tính kết nối.
  • editor.langstringtuỳ chọnMặc định: "vi"
    Mã ngôn ngữ giao diện, ví dụ vi, en-US.
  • editor.user.idstring, 1–64 ký tựbắt buộc
    Định danh người dùng ở hệ của bạn.
  • editor.user.namestring, 1–128 ký tựtuỳ chọnMặc định: "Khách"
    Tên hiển thị trong danh sách người cùng sửa.
  • editor.callbackUrlstring (URL)tuỳ chọn
    Nơi gate gửi callback khi có bản lưu mới (xem lưu và callback). Chịu quy tắc chống SSRF. Không có thì bản đã sửa chỉ nằm ở gate trong thời gian giữ và trang lấy qua onSaved.

ui#

Tuỳ chọn. Bỏ trống một trường là giữ mặc định của máy chủ soạn thảo. Bảng chỉ liệt kê những gì v1 thật sự cài đặt.

ui (tuỳ chọn)

  • ui.widthchuỗi CSStuỳ chọnMặc định: "100%"
    Chiều rộng khung.
  • ui.heightchuỗi CSStuỳ chọnMặc định: "100%"
    Chiều cao khung. Phần tử chứa phải có chiều cao thật.
  • ui.mode"tabbed" | "compact"tuỳ chọnMặc định: "tabbed"
    Thanh công cụ dạng thẻ hay dạng gọn.
  • ui.closeButtonbooleantuỳ chọnMặc định: false
    Hiện nút đóng; bấm thì phát onClose.
  • ui.saveButtonbooleantuỳ chọnMặc định: true
    false ẩn lệnh lưu khỏi giao diện (tự lưu vẫn chạy).
  • ui.printbooleantuỳ chọnMặc định: true
    false ẩn và chặn lệnh in.
  • ui.exportbooleantuỳ chọnMặc định: true
    false ẩn và chặn tải về dưới định dạng khác.
  • ui.copybooleantuỳ chọnMặc định: true
    false chặn chép nội dung ra ngoài khung.
  • ui.userListbooleantuỳ chọnMặc định: true
    Hiện danh sách người cùng sửa.
  • ui.statusbarbooleantuỳ chọnMặc định: mặc định máy chủ
    Thanh trạng thái, áp sau khi tài liệu nạp xong.
  • ui.menubarbooleantuỳ chọnMặc định: mặc định máy chủ
    Thanh trình đơn, chỉ có nghĩa với mode: "compact"; áp sau khi nạp.
  • ui.limitBannerbooleantuỳ chọnMặc định: true
    Băng thông báo tiếng Việt do api.js vẽ phía trên khung khi phiên bị hạ xuống chỉ đọc vì chạm trần.
Sắp có

theme (sáng, tối), logo, productName, primaryColor (nhãn trắng, bản doanh nghiệp với image O3O dựng từ nguồn), watermark, ẩn hiện từng nút lệnh, ruler, sidebar. v1 bỏ qua các trường này kèm một dòng cảnh báo ở console.

token và events#

Trường còn lại

  • tokenstring (JWT)tuỳ chọn
    Tuỳ chọn trên máy DEV, BẮT BUỘC khi máy chủ đặt O3O_EMBED_JWT_SECRET. Token hợp lệ thì gate dùng document, editor, ui TRONG token. Xem ký cấu hình.
  • eventsobjecttuỳ chọn
    Các hàm gọi lại, xem sự kiện. Không được gửi lên máy chủ.

Khi config sai#

Gate kiểm config trước mọi việc khác. Sai hay thiếu trường: 400 invalid_config, danh sách lỗi ở detail.errors theo dạng {path, message}, và onError phát với cùng mã. Câu chữ của message dưới đây chỉ để minh hoạ.

400invalid_config
{
  "error": {
    "code": "invalid_config",
    "message": "Cấu hình trình soạn thảo không hợp lệ.",
    "detail": {
      "errors": [
        {
          "path": "document.key",
          "message": "Chỉ gồm chữ, số, dấu chấm, gạch dưới, gạch nối; tối đa 128 ký tự."
        }
      ]
    },
    "request_id": "req_0123456789abcdef"
  }
}

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