Để sử dụng API Google Tài liệu một cách hiệu quả, bạn phải nắm được cấu trúc của tài liệu trên Google Tài liệu và các thành phần tạo nên tài liệu, cũng như mối quan hệ giữa các thành phần đó. Trang này cung cấp thông tin tổng quan chi tiết về những chủ đề sau:
- Mô hình khái niệm về các thành phần của tài liệu
- Cách API Tài liệu trình bày các phần tử 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à đơ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 Body, Header, Footer và nhiều thuộc tính khác:
document: {
body: ... ,
documentStyle: ... ,
lists: ... ,
documentId: ... ,
namedStyles: ... ,
revisionId: ... ,
title: ...
}
Để thao tác với các tính năng tài liệu chung bên ngoài nội dung Body, tốt hơn hết là bạn nên sử dụng một hoặc nhiều mẫu tài liệu để 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 phần 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 tài liệu. Hầu hết các mục bạn có thể hoặc có thể 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:
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ư trong sơ đồ sau:
Các phần tử cấu trúc và đối tượng nội dung của các phần tử đó chứa tất cả các thành phần hình ảnh trong tài liệu. Điề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à StructuralElement đại diện cho một đoạn. Lớp này có một loạt nội dung được kết thúc bằng một ký tự dòng mới. Lớp này bao gồm các đối tượng sau:
ParagraphElement: Mô tả nội dung trong một đoạn.ParagraphStyle: Một phần tử không bắt buộc đặt rõ ràng các thuộc tính kiểu cho đoạn.Bullet: Nếu đoạn nằm trong danh sách, thì đây là một phần tử không bắt buộc cung cấp thông số kỹ thuật của 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 riêng như minh hoạ trong sơ đồ sau:
Để biết ví dụ về cấu trúc hoàn chỉnh của tài liệu, hãy xem ví dụ về tài liệu ở định dạng JSON. Trong dữ liệu đầu ra, bạn có thể thấy nhiều thành phần chính về cấu trúc và nội dung, cũng như cách sử dụng các chỉ mục bắt đầu và kết thúc như mô tả trong phần sau.
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ề có cùng tất cả kiểu văn bản. Một đoạn có thể chứa nhiều dòng văn bản nhưng văn bản không bao giờ chạy vượt qua ranh giới của các đoạn. Nội dung được phân tách sau một ký tự dòng mới để tạo thành các lần chạy 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ơ đồ dưới đây cho thấy cách bạn có thể hình dung trình tự các đoạn văn trong tài liệu trước, mỗi đoạn có các chế độ cài đặt TextRun và Bullet không bắt buộc riêng.
AutoText
AutoText là ParagraphElement đại diện cho một điểm 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, tham số này dùng cho số trang.
Chỉ số bắt đầu và kết thúc
Khi bạn cập nhật nội dung của một tài liệu, mỗi lần cập nhật sẽ diễn ra tại một vị trí hoặc trên một phạm vi 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, đại diện cho độ 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 cuối trang chứa các thành phần cấu trúc hoặc nội dung. Chỉ số của các phần tử trong một phân đoạn tương ứng với điểm bắt đầu của phân đoạn đó.
Hầu hết phần tử trong nội dung đề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 độ chênh lệch giữa phần đầu và phần cuối của một phần tử, so với phần đầu của phân đoạn bao bọc. Để biết thêm thông tin 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 Cập nhật theo lô.
Các chỉ số được đo bằng đơn vị mã UTF-16. Điều này có nghĩa là các cặp thay thế sử dụng 2 chỉ mục. Ví dụ: biểu tượng cảm xúc "KHUYẾT MẶT" 😄 được biểu thị dưới dạng \uD83D\uDE00 và sử dụng hai chỉ số.
Đối với các phần tử trong phần nội dung tài liệu, chỉ mục biểu thị các độ lệch so với phần đầu của nội dung phần thân là phần tử "gốc".
Các loại "cá nhân hoá" cho các phần tử có 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 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 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 thành phần của tài liệu, hãy sử dụng phương thức 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 Nội dung tài liệu xuất dưới dạng JSON.
Việc phân tích cú pháp nội dung có thể giúp í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ê các 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ã sửa đổi và số trang bắt đầu của một tài liệu, như minh hoạ trong sơ đồ sau:
Vì không có phương thức 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.
Các quyền truy cập được kế thừa từ thuộc tính
StructuralElement có thể kế thừa các thuộc tính của đối tượng mẹ. Các thuộc tính của một đối tượng, bao gồm cả các thuộc tính mà đối tượng xác định và các thuộc tính kế thừa của đối tượng, sẽ xác định giao diện hình ảnh 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 một 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 kế thừa từ TextStyle của đoạn cơ bản. Ngược lại, mọi ký tự có định dạng mà bạn không đặt sẽ tiếp tục kế thừa từ các kiểu của đoạn.
Định dạng đoạn xác định cách các khối văn bản hiển thị 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 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 thiết lập sẽ tiếp tục kế thừa từ kiểu đoạn văn bản.