Cấu trúc của tài liệu Google Tài liệu

Để sử dụng hiệu quả API Google Tài liệu, bạn phải hiểu rõ cấu trúc của một tài liệu Google Tài liệu và các phần tử tạo nên tài liệu, cũng như mối quan hệ giữa chúng. Trang này cung cấp tổng quan chi tiết về các chủ đề này:

  • Mô hình khái niệm của các thành phần trong tài liệu
  • Cách API Tài liệu biểu thị những thành phần này
  • Thuộc tính định kiểu của các phần tử

Phần tử cấp cao nhất

Phần tử vùng chứa ngoài cùng trong Google Tài liệu là một tài liệu. Đây là có thể được lưu trong Google Drive, chia sẻ với những người dùng khác và được cập nhật có văn bản và hình ảnh.

Các phần tử cấp cao nhất của documents bao gồm Tab, SuggestionsViewMode! và các thuộc tính khác:

document: {
    title: ... ,
    revisionId: ... ,
    documentId: ... ,
    suggestionsViewMode: ... ,
    tabs: ...
}

Tab

Một tài liệu có thể chứa nhiều thẻ có nội dung cấp văn bản khác nhau. Thuộc tính tabs của tài liệu là chuỗi đối tượng Tab. Tab bao gồm các trường sau:

  • TabProperties: Chứa các thuộc tính của một thẻ như mã nhận dạng, tiêu đề và chỉ mục.
  • childTabs: Hiển thị các thẻ con của một thẻ (các thẻ được lồng trực tiếp bên dưới).
  • DocumentTab: Đại diện cho nội dung văn bản của thẻ.
Cấu trúc các thẻ của một tài liệu.
Hình 1. Cấu trúc các thẻ của một tài liệu.

Các phần sau sẽ cung cấp thông tin tổng quan ngắn gọn về hệ phân cấp thẻ trong tài liệu; thời gian Biểu diễn JSON cho thẻ cũng vậy sẽ cung cấp thông tin chi tiết hơn. Xem bài viết Làm việc với thẻ để biết thêm thông tin về tính năng thẻ.

Để thao túng các tính năng của thẻ tài liệu chung bên ngoài nội dung Body, hầu như luôn tốt hơn khi sử dụng một hoặc nhiều mẫu tài liệu mà bạn có thể sử dụng làm cơ sở để tạo tài liệu mới theo phương thức lập trình. Để biết thêm thông tin, hãy xem Hợp nhất văn bản vào tài liệu.

Nội dung

Body thường chứa toàn bộ nội dung trên thẻ của một tài liệu. Hầu hết các mục mà bạn có thể hoặc muốn sử dụng theo phương thức lập trình là các phần tử trong nội dung Body:

Cấu trúc của nội dung.
Hình 2. Cấu trúc của nội dung.

Phần tử kết cấu

StructuralElement mô tả nội dung tạo nên cấu trúc cho tài liệu. Nội dung Body là một chuỗi các đối tượng StructuralElement. Một thành phần nội dung sẽ cá nhân hoá từng Đối tượng StructuralElement, như minh hoạ trong sơ đồ sau:

Phần tử cấu trúc.
Hình 3. Phần tử cấu trúc.

Phần tử cấu trúc và đối tượng nội dung của chúng chứa tất cả các thành phần hình ảnh trong tài liệu. Dữ liệu này bao gồm văn bản, hình ảnh cùng dòng và định dạng.

Cấu trúc đoạn

Paragraph là một StructuralElement đại diện cho một đoạn văn bản. Trang này có nhiều dạng nội dung kết thúc bằng một ký tự dòng mới. Đối tượng này được tạo thành từ các đối tượng sau:

  • ParagraphElement: Mô tả nội dung trong một đoạn.
  • ParagraphStyle: Một phần tử tùy chọn xác định rõ ràng các thuộc tính kiểu cho đoạn.
  • Bullet: Nếu đoạn là một phần của danh sách, một phần tử không bắt buộc cung cấp dấu đầu dòng đặc điểm kỹ thuật.

ParagraphElement hoạt động giống như StructuralElement. Tập hợp loại phần tử nội dung (chẳng hạn như ColumnBreak và Equation) cá nhân hoá ParagraphElement riêng, như được thể hiện trong sơ đồ sau:

Cấu trúc của các phần tử đoạn.
Hình 4. Cấu trúc của các phần tử đoạn.

Để xem ví dụ về một cấu trúc tài liệu hoàn chỉnh, hãy xem tài liệu ví dụ ở định dạng JSON. Trong dữ liệu đầu ra, bạn có thể xem nhiều yếu tố chính về cấu trúc và nội dung, cũng như cách sử dụng đoạn mở đầu và chỉ mục kết thúc như được mô tả trong phần sau.

Lần chạy văn bản

TextRun là một ParagraphElement đại diện cho một chuỗi văn bản liền kề với cùng một kiểu văn bản. Đáp đoạn có thể chứa nhiều lần chạy văn bản nhưng văn bản không bao giờ chạy trên đoạn văn ranh giới. Nội dung được phân tách sau một ký tự dòng mới để tạo thành văn bản riêng chạy. Ví dụ: hãy xem xét một tài liệu nhỏ như sau:

Tài liệu nhỏ có các đoạn văn và danh sách có dấu đầu dòng.
Hình 5. Một tài liệu nhỏ.

Sơ đồ sau đây trình bày cách bạn có thể trực quan hoá trình tự các đoạn trong tài liệu trước, mỗi đường dẫn có TextRun riêng và Bullet không bắt buộc phần cài đặt.

Cấu trúc của một lần chạy văn bản.
Hình 6. Cấu trúc của một lần chạy văn bản.

AutoText

AutoText là một ParagraphElement đại diện cho một điểm trong văn bản được thay thế động với nội dung có thể thay đổi theo thời gian. Trong Tài liệu, tuỳ chọn này được dùng cho số trang.

Chỉ mục bắt đầu và chỉ mục kết thúc

Khi bạn cập nhật nội dung trên thẻ của tài liệu, mỗi lần cập nhật sẽ mất đặt tại một vị trí hoặc trên một dải ô trong tài liệu. Các vị trí này và phạm vi được chỉ định bằng chỉ_mục, thể hiện độ lệch trong có chứa phân đoạn tài liệu. Phân đoạn là phần nội dung, tiêu đề, chân trang hoặc chú thích cuối trang có chứa yếu tố cấu trúc hoặc nội dung. Chỉ mục của các phần tử trong một phân đoạn so với đầu phân đoạn đó.

Hầu hết các phần tử trong nội dung nội dung đều có startIndex (dựa trên giá trị 0) và Thuộc tính endIndex. Các số này cho biết phần chênh lệch giữa phần đầu và phần tử so với phần đầu của phân đoạn đính kèm. Thông tin khác về cách sắp xếp các lệnh gọi API Tài liệu theo lô, hãy xem phần Hàng loạt các bản cập nhật.

Các chỉ số được đo bằng đơn vị mã UTF-16. Điều này có nghĩa là cặp thay thế sử dụng hai chỉ mục. Ví dụ: "MẶT CƯỜI TO" biểu tượng cảm xúc 😄, được biểu thị là \uD83D\uDE00 và sử dụng hai chỉ mục.

Đối với các phần tử trong nội dung tài liệu, chỉ mục biểu thị độ lệch của phần tử phần đầu của nội dung phần thân, là "gốc" .

"Cá nhân hoá" các loại cụm từ tìm kiếm có cấu trúc phần tử – SectionBreak, TableOfContents! Table và Paragraph—không có các chỉ mục này vì bao gồm chúng StructuralElement có các trường này. Điều này cũng đúng với việc cá nhân hoá các loại có trong ParagraphElement, chẳng hạn như TextRun, AutoText và PageBreak.

Truy cập các phần tử

Nhiều yếu tố có thể sửa đổi bằng documents.batchUpdate . Ví dụ: sử dụng InsertTextRequest! bạn có thể thay đổi nội dung của bất kỳ phần tử nào chứa văn bản. Tương tự, bạn có thể sử dụng UpdateTextStyleRequest để áp dụng định dạng cho một dải văn bản có trong một hoặc nhiều phần tử.

Để đọc các thành phần của tài liệu, hãy sử dụng documents.get để có được Tệp kết xuất JSON của tài liệu hoàn chỉnh. Sau đó, bạn có thể phân tích cú pháp JSON thu được để tìm giá trị của từng phần tử. Để biết thêm thông tin, hãy xem phần Đầu ra nội dung tài liệu dưới dạng JSON.

Việc phân tích cú pháp nội dung có thể mang lại lợi ích cho nhiều trường hợp sử dụng. Cân nhắc, đối với ví dụ: một ứng dụng lập danh mục liệt kê các tài liệu tìm thấy. Ứng dụng này có thể trích xuất tiêu đề, ID bản sửa đổi và số trang bắt đầu của một tài liệu như được minh hoạ trong sơ đồ dưới đây:

Cấu trúc của một danh mục tài liệu.
Hình 7. Cấu trúc của một danh mục tài liệu.

Vì không có phương pháp nào để đọc các chế độ cài đặt này một cách rõ ràng, nên ứng dụng của bạn cần để lấy toàn bộ tài liệu rồi phân tích cú pháp JSON để trích xuất các giá trị này.

Thừa kế thuộc tính

StructuralElement có thể kế thừa các thuộc tính của đối tượng mẹ. Một các thuộc tính của đối tượng, bao gồm các thuộc tính mà đối tượng xác định và những thuộc tính mà đối tượng kế thừa, xác định hình ảnh trực quan cuối cùng.

Định dạng ký tự văn bản xác định cách hiển thị văn bản trong tài liệu, chẳng hạn như in đậm, in nghiêng và gạch chân. Định dạng mà bạn áp dụng sẽ ghi đè định dạng mặc định định dạng được kế thừa từ định dạng của đoạn cơ bản TextStyle. Ngược lại, bất kỳ các ký tự có định dạng bạn không thiết lập sẽ tiếp tục kế thừa từ kiểu của đoạn văn bản.

Định dạng đoạn xác định cách hiển thị các khối văn bản trong một tài liệu, chẳng hạn như căn chỉnh, đường viền và thụt lề. Định dạng mà bạn áp dụng ghi đè định dạng mặc định kế thừa từ ParagraphStyle cơ bản. Ngược lại, mọi tính năng định dạng mà bạn không thiết lập sẽ tiếp tục kế thừa kiểu đoạn văn bản.