Để sử dụng API Google Tài liệu một cách hiệu quả, bạn phải hiểu rõ cấu trúc của một tài liệu trên Google Tài liệu và các phần tử tạo nên một tài liệu, cũng như mối quan hệ giữa các phần tử đó. Trang này cung cấp thông tin tổng quan chi tiết về các chủ đề sau:
- Mô hình khái niệm về các phần tử trong tài liệu
- Cách Docs API biểu thị các phần tử này
- Các thuộc tính tạo kiểu của 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à đơn vị có thể được lưu trong Google Drive, chia sẻ với người dùng khác và cập nhật bằng văn bản và hình ảnh.
Các phần tử cấp cao nhất của tài nguyên 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à một chuỗi các đối tượng Tab. Tab bao gồm các trường sau:
TabProperties: Chứa các thuộc tính của thẻ, chẳng hạn 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 thẻ đó).DocumentTab: Đại diện cho nội dung văn bản của một thẻ.
Các phần sau này sẽ cung cấp thông tin tổng quan ngắn gọn về hệ thống phân cấp thẻ tài liệu; biểu thị JSON của thẻ cũng cung cấp thông tin chi tiết hơn. Hãy 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ác các tính năng của thẻ tài liệu chung bên ngoài nội dung Body, bạn nên sử dụng một hoặc nhiều mẫu tài liệu (bạn có thể 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 bài viết 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 của một thẻ trong tài liệu. Hầu hết các mục mà bạn có thể hoặc có khả năng muốn sử dụng theo phương thức lập trình đều là các phần tử trong nội dung Body:
Phần tử kết cấu
StructuralElement
mô tả nội dung cung cấp 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 phần tử nội dung sẽ cá nhân hoá từng đối tượng StructuralElement, như minh hoạ trong sơ đồ sau:
Cá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 trực quan trong tài liệu. Nội dung này bao gồm văn bản, hình ảnh nội tuyến 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. Nội dung này có một dải nội dung được kết thúc bằng ký tự dòng mới. Thư viện này bao gồm các đối tượng sau:
ParagraphElement: Mô tả nội dung trong một đoạn văn.ParagraphStyle: Một phần tử không bắt buộc giúp đặt rõ ràng các thuộc tính kiểu cho đoạn văn.Bullet: Nếu đoạn văn là một phần của danh sách, thì đây là một phần tử không bắt buộc cung cấp quy cách dấu đầu dòng.
ParagraphElement hoạt động tương tự như StructuralElement. Một tập hợp các loại phần tử nội dung (chẳng hạn như ColumnBreak và Equation) sẽ cá nhân hoá ParagraphElement của riêng mình, như minh hoạ trong sơ đồ sau:
Để xem ví dụ về cấu trúc tài liệu hoàn chỉnh, hãy xem ví dụ về tài liệu ở định dạng JSON. Trong đầu ra, bạn có thể thấy nhiều phần tử nội dung và cấu trúc chính, cũng như việc sử dụng chỉ mục bắt đầu và chỉ mục kết thúc như mô tả trong phần sau.
Đoạn văn bản
TextRun là một ParagraphElement biểu thị một chuỗi văn bản liền mạch có cùng kiểu văn bản. Một đoạn văn có thể chứa nhiều đoạn văn bản nhưng các đoạn văn bản không bao giờ vượt quá ranh giới đoạn văn. Nội dung được chia sau ký tự dòng mới để tạo thành các đoạn văn bản riêng biệt. Ví dụ: hãy xem xét một tài liệu nhỏ như sau:
Sơ đồ sau đây cho thấy cách bạn có thể hình dung chuỗi đoạn văn trong tài liệu trước đó, mỗi đoạn văn có chế độ cài đặt TextRun và Bullet riêng (không bắt buộc).
AutoText
AutoText là một ParagraphElement biểu thị một vị trí trong văn bản được thay thế linh hoạt bằng nội dung có thể thay đổi theo thời gian. Trong Tài liệu, giá trị này được dùng cho số trang.
Chỉ mục bắt đầu và kết thúc
Khi bạn cập nhật nội dung của một thẻ tài liệu, mỗi nội dung cập nhật sẽ diễn ra tại một vị trí hoặc trên một dải ô trong tài liệu. Các vị trí và dải ô này được chỉ định bằng cách sử dụng chỉ mục, biểu thị độ lệch trong một phân đoạn tài liệu chứa. Phân đoạn là phần nội dung, tiêu đề, chân trang hoặc chú thích chứa các phần tử cấu trúc hoặc nội dung. Chỉ mục của các phần tử trong một đoạn tương ứng với điểm bắt đầu của đoạn đó.
Hầu hết các phần tử trong nội dung chính đều có các thuộc tính startIndex và endIndex dựa trên 0. Các giá trị này cho biết độ lệch của điểm bắt đầu và điểm kết thúc của một phần tử, tương ứng với điểm bắt đầu của đoạn đường bao quanh. Để biết thêm thông tin về cách sắp xếp các lệnh gọi theo lô của Docs API, hãy xem phần Cập nhật theo lô.
Chỉ mục được đo bằng đơn vị mã UTF-16. Điều này có nghĩa là các cặp thay thế sẽ sử dụng 2 chỉ mục. Ví dụ: biểu tượng cảm xúc "MẶT CƯỜI TƯƠI" 😄 được biểu thị dưới dạng \uD83D\uDE00 và sử dụng 2 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 so với phần đầu của nội dung, tức là phần tử "gốc".
Các loại "cá nhân hoá" cho các phần tử cấu trúc (SectionBreak, TableOfContents, Table và Paragraph) không có các chỉ mục này vì StructuralElement bao quanh chúng có các trường này. Điều này cũng đúng với các loại cá nhân hoá có trong ParagraphElement, chẳng hạn như TextRun, AutoText và PageBreak.
Truy cập vào các phần tử
Bạn có thể sửa đổi nhiều phần tử bằng phương thức documents.batchUpdate. Ví dụ: bằng cách sử dụng InsertTextRequest, bạn có thể thay đổi nội dung của bất kỳ phần tử nào có chứa văn bản. Tương tự, bạn có thể 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 phần tử của tài liệu, hãy sử dụng phương thức documents.get để lấy một bản kết xuất JSON của toàn bộ tài liệu. Sau đó, bạn có thể phân tích cú pháp JSON kết quả để tìm giá trị của từng phần tử. Để biết thêm thông tin, hãy xem phần Nội dung tài liệu đầu ra 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. Ví dụ: hãy xem xét một ứng dụng lập danh mục tài liệu liệt kê những tài liệu mà ứng dụng tìm thấy. Ứng dụng này có thể trích xuất tiêu đề, mã nhận dạng bản sửa đổi và số trang bắt đầu của các thẻ trong tài liệu, như minh hoạ trong sơ đồ sau:
Vì không có phương thức nào để đọc rõ ràng các chế độ cài đặt này, 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
Một StructuralElement có thể kế thừa các thuộc tính từ các đối tượng gốc của nó. Các thuộc tính của đối tượng, bao gồm cả những 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, sẽ quyết định giao diện trực quan cuối cùng của đối tượng.
Định dạng ký tự văn bản xác định cách văn bản được hiển thị trong tài liệu, chẳng hạn như in đậm, in nghiêng và gạch dưới. Định dạng mà bạn áp dụng sẽ ghi đè định dạng mặc định được kế thừa từ TextStyle của đoạn văn bản cơ bản.
Ngược lại, mọi ký tự mà bạn không đặt định dạng sẽ tiếp tục kế thừa từ kiểu của đoạn văn.
Định dạng đoạn văn xác định cách hiển thị các khối văn bản trong 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 sẽ ghi đè định dạng mặc định được 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 đặt sẽ tiếp tục kế thừa từ kiểu đoạn văn.