Tham chiếu khối

Trang này ghi lại mọi loại khối mà trình soạn thảo đi kèm. Mỗi khối có một cấu trúc JSON, một trình hiển thị và một đường chèn bằng mã qua editor.blocks.insert.

Tất cả các khối dùng chung một lớp bao bọc khi được tuần tự hóa: id, type, data và một bản ghi tunes tùy chọn.

Cấu trúc của khối

Mọi khối đều được tuần tự hóa vào cùng một phong bì JSON. id được chỉ định bởi trình soạn thảo và có thể bỏ qua khi xây dựng dữ liệu theo lập trình.

{
  "id": "abc123",
  "type": "paragraph",
  "data": { "html": "Hello <b>world</b>" },
  "tunes": {}
}

alert

Hộp chú thích được tô sáng với 4 biến thể.

{
  "type": "alert",
  "data": { "html": "Your session will expire in 5 minutes.", "variant": "warning" }
}

audio

Khối âm thanh. Được xử lý qua callback audioUploader trên Editor.create.

{
  "type": "audio",
  "data": { "url": "/media/podcast.mp3", "caption": "Episode 12", "alignment": "center" }
}

checklist

Danh sách hộp kiểm tương tác với trạng thái đã chọn cho từng mục.

{
  "type": "checklist",
  "data": {
    "items": [
      { "text": "Install the package", "checked": true },
      { "text": "Mount the editor", "checked": false }
    ]
  }
}

code

Khối mã có tô sáng cú pháp. Hỗ trợ 50 ngôn ngữ, bao gồm typescript, python, rust, go, ruby, swift và kotlin.

{
  "type": "code",
  "data": { "code": "const x = 42;", "language": "typescript", "theme": "github-dark", "showCopy": true }
}

collapsible

Một mục có thể thu gọn với tiêu đề và các khối con lồng nhau. Các loại khối con không xác định được giữ nguyên vẹn, nên tài liệu mới hơn vẫn hoạt động trên trình hiển thị cũ hơn.

{
  "type": "collapsible",
  "data": {
    "html": "Details",
    "open": true,
    "children": [{ "type": "paragraph", "data": { "html": "Hidden until opened." } }]
  }
}

collection

Nhúng một khung xem bộ sưu tập trực tiếp theo id. Khối chỉ lưu danh tính của bộ sưu tập; máy chủ sở hữu cấu trúc và dữ liệu.

{
  "type": "collection",
  "data": { "collectionId": "c-42" }
}

columns

Bố cục nhiều cột từ 2 đến 4 cột, mỗi cột giữ danh sách khối con của riêng nó.

{
  "type": "columns",
  "data": {
    "columns": [
      [{ "type": "paragraph", "data": { "html": "Left" } }],
      [{ "type": "paragraph", "data": { "html": "Right" } }]
    ]
  }
}

date

Một ngày trên lịch, được lưu không kèm múi giờ để mọi cộng tác viên đều thống nhất.

{
  "type": "date",
  "data": { "date": "2026-08-31" }
}

delimiter

Dấu phân cách trực quan giữa các phần.

{
  "type": "delimiter",
  "data": { "variant": "line" }
}

doc_card

Một thẻ liên kết phong phú trỏ đến tài liệu khác. Nó lưu id của trang được tham chiếu cùng một ảnh chụp hiển thị mà máy chủ làm mới khi đổi tên.

{
  "type": "doc_card",
  "data": { "pageId": "p-7", "title": "Release notes", "icon": "📄" }
}

embed

Một liên kết được nhúng. Khối lưu URL; nhà cung cấp và mã nhúng được suy ra lúc hiển thị, các trường unfurl làm thẻ dự phòng.

{
  "type": "embed",
  "data": { "url": "https://www.youtube.com/watch?v=abc123" }
}

file

Một tệp đính kèm với liên kết tải xuống, tên, cùng kích thước và loại nội dung tùy chọn.

{
  "type": "file",
  "data": { "url": "/files/notes.pdf", "name": "notes.pdf", "size": 2048, "contentType": "application/pdf" }
}

glance

Một bảng tóm tắt nhãn và giá trị: các hàng dữ kiện đọc được trong nháy mắt, với chú thích và biến thể nền tùy chọn.

{
  "type": "glance",
  "data": {
    "caption": "Facts",
    "rows": [{ "label": "Version", "html": "<b>1.0</b>" }],
    "variant": "plain"
  }
}

header

Tiêu đề cấp cao nhất và tiêu đề mục (h1 đến h6). Các công cụ nội tuyến hoạt động bên trong payload html.

{
  "type": "header",
  "data": { "html": "Getting started", "level": "h2" }
}

image

Khối hình ảnh với chú thích và văn bản alt. Được xử lý qua callback imageUploader trên Editor.create.

{
  "type": "image",
  "data": { "url": "/img/hero.jpg", "caption": "Hero image", "alt": "A hero", "alignment": "center" }
}

issues

Bảng các issue được liên kết, suy ra lúc hiển thị từ các chip và thẻ issue trên trang (issue, tiêu đề, trạng thái, người phụ trách). Nó không lưu dữ liệu riêng.

Khối này không lưu trường nào; các hàng được suy ra từ các chip và thẻ issue trên trang lúc hiển thị.

{
  "type": "issues",
  "data": {}
}

latex

Toán LaTeX, được lưu dưới dạng mã nguồn và sắp chữ lúc hiển thị. Một trình hiển thị tốt hơn sau này sẽ cải thiện mọi tài liệu đã tồn tại.

{
  "type": "latex",
  "data": { "source": "\\frac{a}{b}" }
}

list

Danh sách có thứ tự hoặc không có thứ tự. Mỗi mục là html.

{
  "type": "list",
  "data": { "type": "unordered", "items": ["First item", "Second item"] }
}

mermaid

Một sơ đồ Mermaid, được lưu dưới dạng mã nguồn và vẽ lúc hiển thị, không bao giờ là ảnh raster.

{
  "type": "mermaid",
  "data": { "source": "flowchart TD\n  A --> B" }
}

openapi

Hiển thị tài liệu tham chiếu API tương tác từ một tài liệu OpenAPI 3.x, nội tuyến hoặc tải từ URL, với bộ chọn máy chủ và đoạn mã.

{
  "type": "openapi",
  "data": { "url": "/api/openapi.json", "defaultServer": "https://api.example.com" }
}

paragraph

Đoạn văn bản định dạng phong phú. Chấp nhận đánh dấu công cụ nội tuyến như bold, italic, code, link, marker và tooltip.

{
  "type": "paragraph",
  "data": { "html": "This is a <b>paragraph</b> with inline markup." }
}

quote

Khối trích dẫn với phần ghi nguồn tác giả tùy chọn.

{
  "type": "quote",
  "data": { "html": "The best way to predict the future is to invent it.", "author": "Alan Kay" }
}

sketch

Một bản vẽ tay được lưu dưới dạng nét vẽ, không bao giờ là ảnh raster, nên luôn chỉnh sửa được và phóng to sắc nét.

{
  "type": "sketch",
  "data": { "strokes": [{ "points": [0, 0, 10, 10], "color": "#ff0000", "width": 3 }] }
}

table

Lưới dữ liệu. Hàng đầu tiên có thể được dùng làm tiêu đề; mỗi ô là html.

{
  "type": "table",
  "data": {
    "data": [["Name", "Type"], ["html", "string"], ["variant", "AlertVariant"]],
    "caption": "AlertData fields",
    "showDownload": false
  }
}

toc

Mục lục được suy ra từ các tiêu đề của tài liệu lúc hiển thị. Nó không lưu dữ liệu riêng.

Khối này không lưu trường nào; danh sách được suy ra từ các tiêu đề của tài liệu lúc hiển thị.

{
  "type": "toc",
  "data": {}
}

updates

Một nguồn cấp hoạt động trực tiếp cho tài liệu. Nó lưu danh tính, không bao giờ là ảnh chụp, nên luôn hiển thị hoạt động hiện tại.

{
  "type": "updates",
  "data": { "pageId": "p-7" }
}

video

Khối video. Được xử lý qua callback videoUploader trên Editor.create.

{
  "type": "video",
  "data": { "url": "/media/demo.mp4", "caption": "Product demo", "alignment": "center" }
}