Để 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 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 thông tin tổng quan chi tiết về các chủ đề sau:
- 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à đơn vị có thể được lưu trong Google Drive, chia sẻ với những người dùng khác và cập nhật văn bản cũng như 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 của tài liệu chung bên ngoài nội dung Body, tốt hơn hết 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 mẫu này 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 mà bạn có thể hoặc 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 giúp định hình cấu trúc của 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 các phần tử đó 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à StructuralElement đại diện cho một đoạn văn bản. Nó có một loạt nội dung được 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ử không bắt buộc giúp đặt rõ các thuộc tính kiểu cho đoạn văn bản.Bullet: Nếu đoạn thuộc danh sách, thì đó là một phần tử không bắt buộc cung cấp thông số kỹ thuật cho dấu đầu dòng.
ParagraphElement hoạt động giống như StructuralElement. Một nhóm các loại phần tử nội dung (chẳng hạn như ColumnBreak và Equation) cá nhân hoá ParagraphElement riêng, như minh hoạ trong sơ đồ sau:
Để biết ví dụ về một 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 thành phần nội dung và thành phần cấu trúc chính, cũng như cách sử dụng chỉ mục bắt đầu và chỉ mục kết thúc như 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 nhau có cùng một kiểu văn bản. Một đ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ờ vượt qua ranh giới của đ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 đ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ể trực quan hoá trình tự các đoạn trong tài liệu trước, mỗi đoạn có TextRun riêng và chế độ cài đặt Bullet không bắt buộc.
AutoText
AutoText là ParagraphElement đại diện cho một điểm trong văn bản được thay thế linh động bằng nội dung có thể thay đổi theo thời gian. Trong Tài liệu, tham số 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 của 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 dải ô trong tài liệu. Các vị trí và dải ô này được chỉ định bằng chỉ mục, thể hiện độ lệch trong phân đoạn tài liệu chứa. Phân đoạn là phần nội dung, đầu trang, chân trang hoặc chú thích cuối trang có chứa các yếu tố cấu trúc hoặc nội dung. Các chỉ mục của các phần tử trong một phân đoạn tương ứng 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ó thuộc tính startIndex và endIndex dựa trên giá trị 0. Các thuộc tính này cho biết độ lệch giữa đầu và cuối của một phần tử, so với đầu phân đoạn bao gồm phần tử đó. Để 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. Tức 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" 😄 đượ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 nội dung tài liệu, chỉ mục biểu thị các phần chênh lệch so với phần đầu của nội dung phần 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ì bao quanh chúng
StructuralElement có các trường này. Điều này cũng đúng với các kiểu cá nhân hoá có trong ParagraphElement, chẳng hạn như TextRun, AutoText và PageBreak.
Truy cập 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ụ: 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 phần tử của tài liệu, hãy sử dụng phương thức documents.get để lấy 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ạ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ê các tài liệu tìm thấy. Ứng dụng này có thể trích xuất tiêu đề, mã bản 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 sau đó 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 đố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, 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 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 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 thiết lập sẽ tiếp tục kế thừa các 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 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 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.