Để sử dụng API Trang trình bày một cách hiệu quả, bạn cần hiểu rõ cấu trúc của bản trình bày và các thành phần của bản trình bày, cũng như hoạt động tương tác giữa các thành phần này. 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 trình bày
- Cách API biểu thị các thành phần này
- Thuộc tính tạo kiểu của các thành phần
Việc đọc bài viết này và các thông tin tổng quan khác về khái niệm sẽ giúp bạn dễ dàng hiểu và sử dụng hướng dẫn cách thực hiện, tài liệu tham khảo và mã mẫu.
Bản trình bày, trang và phần tử trang
Phần tử vùng chứa ngoài cùng trong Google Trang trình bày là một bản trình bày. Đây là đơn vị có thể lưu trong Google Drive, chia sẻ với người dùng khác, v.v.
Mỗi bản trình bày chứa nhiều loại trang. Một loại trang là trang trình bày, đây là các trang mà người dùng nhìn thấy và lật qua lại khi bản trình bày được hiển thị trên màn hình.
Mỗi trang chứa một số phần tử trang, cùng nhau tạo nên nội dung của trang, như trong sơ đồ sau:
Ngoài trang trình bày, còn có các loại trang khác cho phép bạn áp dụng thiết kế cho nhiều trang trình bày khác nhau, tạo nên một giao diện nhất quán. Các loại trang khác này là trang chính và bố cục, và các thuộc tính của chúng xác định cách hiển thị trang trình bày, như minh hoạ trong sơ đồ sau:
Trang chính – Trang chính phục vụ hai mục đích. Phần giữ chỗ trên trang trình bày chính chứa các kiểu văn bản mặc định được dùng trong toàn bộ bản trình bày. Nền và mọi hình dạng khác trên trang trình bày chính tạo nên nền mặc định cho tất cả các trang trình bày dựa trên trang trình bày chính đó. Nếu bạn có biểu trưng công ty mà bạn muốn xuất hiện trên mọi trang trình bày trong bản trình bày, hãy đặt biểu trưng đó trên trang trình bày chính.
Bố cục — Mẫu bố cục xác định cách sắp xếp nội dung trên từng loại trang trình bày. Ví dụ: nếu muốn tất cả các trang trình bày tiêu đề đều có một giao diện nhất định, bạn có thể chỉnh sửa mẫu bố cục tiêu đề.
Có thêm hai loại trang nữa là trang ghi chú và trang ghi chú chính. Hai loại trang này chủ yếu liên quan đến việc làm việc với ghi chú của người thuyết trình.
Các loại và cấu trúc biểu diễn API
Phần này mô tả cách mô hình khái niệm của Google Trang trình bày (như mô tả ở trên) được thể hiện trong API Trang trình bày.
Sơ đồ sau đây mô tả mối quan hệ giữa bản trình bày, trang và phần tử trang dưới dạng các loại trong API Trang trình bày:
Các phần sau đây cho biết cách biểu thị các loại này trong JSON.
Bản trình bày
Một bản trình bày bao gồm một số thuộc tính và chứa các trang trong đó:
{
"presentationId": string,
"pageSize": { object(Size) },
"slides": [ { object(Page) } ],
"title": string,
"masters": [ { object(Page) } ],
"layouts": [ { object(Page) } ],
"notesMaster": object(Page),
"locale": string,
}
Pages
Trang bao gồm một tập hợp các thuộc tính và chứa các phần tử trang trong đó:
{
"objectId": string,
"pageType": enum(PageType),
"pageElements": [ { object(PageElement) } ],
"pageProperties": { object(PageProperties) },
// Union field properties can be only one of the following:
"slideProperties": { object(SlideProperties) },
"layoutProperties": { object(LayoutProperties) },
"notesProperties": { object(NotesProperties) },
// End of list of possible types for union field properties.
}
Phần tử trang
Phần tử trang là các thành phần hình ảnh được đặt trên trang. Một phần tử trang trong API chứa một số thuộc tính, bao gồm cả một trường thay đổi tuỳ theo loại phần tử trang:
{
"objectId": string,
"size": { object(Size) },
"transform": { object(AffineTransform) },
"title": string,
"description": string,
// Union field element_kind can be only one of the following:
"elementGroup": { object(Group) },
"shape": { object(Shape) },
"image": { object(Image) },
"video": { object(Video) },
"line": { object(Line) },
"table": { object(Table) },
"wordArt": { object(WordArt) },
"sheetsChart": { object(SheetsChart) },
// End of list of possible types for union field element_kind.
}
Có một số loại phần tử trang, được xác định bằng trường hợp nhất element_kind trong định nghĩa ở trên. Các loại phần tử trang này được mô tả trong bảng sau:
| Loại phần tử | Mô tả |
|---|---|
| Nhóm | Một tập hợp các phần tử trang được coi là một đơn vị riêng lẻ. Bạn có thể di chuyển, điều chỉnh tỷ lệ và xoay các đối tượng này cùng nhau. |
| Hình dạng | Một đối tượng hình ảnh đơn giản, chẳng hạn như hình chữ nhật, hình elip và hộp văn bản. Hình dạng có thể chứa văn bản, vì vậy, đây là phần tử trang phổ biến nhất để tạo trang trình bày. |
| Hình ảnh | Một hình ảnh được nhập vào Trang trình bày. |
| Video | Một video được nhập vào Trang trình bày. |
| Line | Đường thẳng, đường cong hoặc đường nối trực quan. |
| Bảng | Một lưới nội dung. |
| WordArt | Một phần tử văn bản trực quan hoạt động giống như một hình dạng. |
| SheetsChart | Một biểu đồ được nhập vào Trang trình bày từ Google Trang tính. |
Thuộc tính của trang và phần tử trang
Slides API cho phép bạn đọc và cập nhật giao diện của các trang và phần tử trang trong bản trình bày. Các phần tử trang khác nhau hỗ trợ các thuộc tính khác nhau để kiểm soát cách hiển thị phần tử trang.
Mỗi loại phần tử trang đều có một phần tử thuộc tính tương ứng và một thông báo cập nhật thuộc tính, ví dụ:
- Có một loại phần tử trang Hình dạng
- Trường thuộc tính của nó là shapeProperties
- Yêu cầu cập nhật các thuộc tính này là UpdateShapePropertiesRequest
Tập hợp phần tử/thuộc tính/yêu cầu cập nhật tương tự tồn tại cho từng loại phần tử trang: Image/imageProperties/UpdateImageProperties, vân vân.
Bạn có thể đọc thuộc tính properties bất cứ khi nào bạn gặp thuộc tính này khi đọc một phần tử; để thay đổi các giá trị trong đó, hãy sử dụng thuộc tính này với loại yêu cầu phù hợp làm tải trọng cho phương thức batchUpdate, cho phép bạn thay đổi các giá trị này trong bản trình bày.
Các loại thuộc tính
Có một số thuộc tính chung giữa một số loại đối tượng trong API Trang trình bày:
| Thuộc tính | Mô tả |
|---|---|
| Màu | Màu sắc trong API Trang trình bày có thể là giá trị RGB hoặc tham chiếu đến màu của giao diện. Màu giao diện được gọi theo tên (ví dụ: "DARK1") và có thể được liên kết với các giá trị RGB bằng bảng phối màu của trang. Bảng phối màu này thường được cập nhật khi thay đổi giao diện của bản trình bày trong trình chỉnh sửa Trang trình bày. |
| Fill | Phần tử tô màu (fill) thể hiện việc kết xuất không gian trống bên trong một đối tượng. Kiểu tô màu phổ biến nhất được hỗ trợ trong Trang trình bày là tô màu đồng nhất, trong đó phần bên trong của một đối tượng được tô bằng một màu đồng nhất. Bạn cũng có thể dùng màu nền cho nền của Trang. |
| Đường viền | Đường viền đại diện cho tập hợp các đường bao quanh phần tử trang. Màu của đường kẻ được kiểm soát bằng Fill. Người gọi cũng có thể điều chỉnh chiều rộng và kiểu nét đứt của đường viền. |
| Shadow | Bóng đổ thể hiện hiệu ứng hình ảnh nhằm mô phỏng bóng đổ vật lý của đối tượng. Hiện tại, bóng trong API Trang trình bày ở chế độ chỉ đọc. |
Đang cập nhật cơ sở lưu trú
Để cập nhật một thuộc tính, hãy sử dụng yêu cầu Update...Properties thích hợp trong lệnh gọi batchUpdate, ví dụ: UpdateShapeProperties cho Hình dạng. Các yêu cầu này chấp nhận thông báo thuộc tính đầy đủ và có thể sử dụng mặt nạ trường để xác định trường nào trong thông báo thuộc tính cần được cập nhật.
Thừa kế thuộc tính
Một trang hoặc phần tử trang có thể kế thừa các thuộc tính từ đối tượng mẹ. Các thuộc tính của một đố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ẽ xác định giao diện trực quan cuối cùng của đối tượng đó.
- Thuộc tính trang — Trang kế thừa mọi thuộc tính mà trang không xác định, nhưng được xác định trong bố cục hoặc trang chính mà trang dựa vào.
- Thuộc tính hình dạng — Bạn có thể đánh dấu một hình dạng là phần giữ chỗ, cho phép bạn tham chiếu rõ ràng đến một hình dạng phần giữ chỗ khác (trên bố cục mẹ hoặc trang chính của trang) để kế thừa các thuộc tính.
Những ý tưởng này được giải thích thêm trong các đoạn sau.
Kế thừa thuộc tính trang
Cấu trúc của trang trình bày, bố cục và trang trình bày chính xác định hệ phân cấp kế thừa trong bản trình bày: trang trình bày kế thừa từ bố cục và bố cục kế thừa từ trang trình bày chính. Bố cục mẹ và trang trình bày chính của một trang trình bày được chỉ định trong trường slideProperties của trang trình bày.
Một trang có thể kế thừa các thuộc tính, chẳng hạn như nền và bảng phối màu, từ một trang mẹ. Để kế thừa một thuộc tính, trang con chỉ cần không đặt giá trị cho thuộc tính đó trong thông báo PageProperties. Bằng cách không "ghi đè" giá trị do phần tử mẹ xác định, trang sẽ chấp nhận giá trị kế thừa.
Sơ đồ sau đây cho thấy một trang trình bày kế thừa các thuộc tính từ một bố cục, bố cục này kế thừa từ một trang trình bày chính:
Các thuộc tính dùng để kết xuất một trang trình bày là sự kết hợp giữa các thuộc tính mà trang trình bày đó xác định và các thuộc tính mà trang trình bày đó kế thừa. Trong ví dụ này, các giá trị đã phân giải dùng để hiển thị Trang trình bày 1 như sau:
- PropertyA là "Đỏ".
- Thuộc tính B là "Cam".
Kế thừa các thuộc tính hình dạng
Hình dạng có thể kế thừa các thuộc tính, chẳng hạn như màu nền, đường viền hoặc bóng, từ các hình dạng khác. Hình dạng là một phần giữ chỗ nếu trường Shape.placeholder của hình dạng đó được đặt. Trường Shape.placeholder.parentObjectId của phần giữ chỗ con xác định phần giữ chỗ mẹ. Khi bạn tạo một trang trình bày mới dựa trên một bố cục, mọi phần giữ chỗ trong bố cục đó sẽ xuất hiện dưới dạng hình dạng con trong trang trình bày mới.
Tương tự, phần giữ chỗ trên trang chính có thể đóng vai trò là phần giữ chỗ mẹ của bố cục.
Khi bạn xác định hệ phân cấp kế thừa này, trang con sẽ kế thừa một thuộc tính bằng cách không đặt giá trị đó trong thông báo ShapeProperties. Bằng cách không ghi đè giá trị do thành phần mẹ xác định, hình dạng con sẽ chấp nhận giá trị kế thừa.
Sơ đồ sau đây cho thấy tính kế thừa của các thuộc tính giữa ba phần giữ chỗ có trong một trang trình bày, một bố cục và một trang trình bày chính:
Các thuộc tính dùng để hiển thị hình dạng phần giữ chỗ là sự kết hợp giữa các thuộc tính mà hình dạng đó xác định và các thuộc tính mà hình dạng đó kế thừa. Trong ví dụ này, các giá trị được phân giải cho những hình dạng này như sau:
- Phần giữ chỗ 1: propertyA được hiển thị là "Vàng", propertyB là "Xanh lục".
- Phần giữ chỗ 2: propertyA được hiển thị dưới dạng "Vàng", propertyB dưới dạng "Tím".
- Phần giữ chỗ 3: propertyA được hiển thị là "Vàng", propertyB là "Tím".
Hình dạng là loại phần tử trang duy nhất có thể có phần tử mẹ. Các loại khác, chẳng hạn như hình ảnh, bảng và biểu đồ, không thể là phần giữ chỗ và không thể có phần tử mẹ.
"Ẩn" thuộc tính bằng PropertyState
Bảng liệt kê PropertyState kiểm soát việc thuộc tính của hình dạng có thực sự được dùng để kết xuất hay không, hoặc liệu giá trị chỉ được dùng để kế thừa bởi các hình dạng con hay không. Một thuộc tính có trạng thái thuộc tính NOT_RENDERED sẽ không được dùng khi hiển thị hình dạng trên trang của thuộc tính đó, tuy nhiên, các phần tử con có trạng thái thuộc tính tương ứng là RENDERED vẫn có thể kế thừa thuộc tính này.
Sơ đồ sau đây cho thấy tính kế thừa của các thuộc tính giữa ba phần giữ chỗ thao tác với trường PropertyState:
Việc hiển thị các thuộc tính hình dạng có thể chịu ảnh hưởng của trường PropertyState. Trong ví dụ này, các giá trị được phân giải cho những hình dạng này như sau:
- Phần giữ chỗ 1: propertyA được hiển thị dưới dạng "Red".
- Phần giữ chỗ 2: propertyA không được hiển thị. Nếu đây là thuộc tính đường viền, thì phần giữ chỗ 2 sẽ không có đường viền.
- Phần giữ chỗ 3: propertyA không được hiển thị.
Có thêm một giá trị có thể có của kiểu liệt kê PropertyState: trạng thái thuộc tính INHERIT có nghĩa là chính trạng thái thuộc tính được kế thừa và giá trị của thành phần mẹ sẽ được sử dụng. Hình dạng không có hình dạng mẹ không thể có trạng thái thuộc tính là INHERIT.