Để 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á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 cách 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 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 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:
Để 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:
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.
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:
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.