Trang, phần tử trang và thuộc tính

Để sử dụng Slides API 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ư các hoạt động tương tác giữa những 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 về các thành phần trình bày
• Cách API biểu thị các thành phần này
• Các thuộc tính tạo kiểu của thành phần

Việc đọc thông tin 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, tài liệu tham khảo và các mẫu công thức.

Bản trình bày, trang và các phần tử trên 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ể được lưu trong Google Drive, chia sẻ với những người dùng khác, v.v.

Mỗi bản trình bày đều chứa nhiều loại trang. Một loại trang là trang trình bày. Đây là những trang mà người dùng nhìn thấy và lật qua 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ác phần tử này kết hợp với nhau để tạo nên nội dung của trang, như minh hoạ 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 ra một giao diện nhất quán. Các loại trang khác này là mẫu và Layouts, đồng thời 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 có hai mục đích. Các phần giữ chỗ trên trang trình bày mẫu chứa các giá trị mặc định cho kiểu văn bản được dùng trong 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 sẽ tạo thành 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ó một biểu trưng công ty mà bạn muốn xuất hiện trên mọi trang chiếu trong bản trình bày, hãy đặt biểu trưng đó trên trang chiếu cái.

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. Nếu muốn tất cả các trang tiêu đề đều có một kiểu nhất định, chẳng hạn 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 mẫu ghi chú. Đây là những trang chủ yếu liên quan đến việc sử dụng ghi chú của diễn giả.

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 biểu thị trong Slides API.

Sơ đồ sau đây mô tả mối quan hệ giữa bản trình bày, trang và các phần tử trên trang dưới dạng các loại trong Slides API:

Các phần sau đây cho biết cách các loại này được biểu thị trong JSON.

Bản trình bày

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

Một 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 có 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 trực quan đượ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, như được xác định bằng trường hợp kết hợp 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:

Thuộc tính 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 phần tử trang được hiển thị.

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 là 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

Cùng một nhóm yêu cầu về phần tử/thuộc tính/nội dung cập nhật tồn tại cho từng loại phần tử trang: Image/imageProperties/UpdateImageProperties, v.v.

Bạn có thể đọc thuộc tính properties bất cứ khi nào gặp thuộc tính này khi đọc một phần tử; để thay đổi các giá trị trong thuộc tính này, 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 tài sản

Có một số thuộc tính chung giữa nhiều loại đối tượng trong Slides API:

Đang cập nhật tài sản

Để 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 một thông báo đầy đủ về tài sản và có thể sử dụng mặt nạ trường để xác định những trường nào trong thông báo về tài sản 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ừ các đối tượng mẹ của nó. 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 – Một trang sẽ 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 mẫu 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 một hình dạng phần giữ chỗ khác (trên bố cục mẹ hoặc bố cục 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 các thuộc tính trang

Cấu trúc của các trang trình bày, bố cục và mẫu xác định một hệ phân cấp kế thừa trong bản trình bày: các trang trình bày kế thừa từ bố cục và bố cục kế thừa từ mẫu. Bố cục mẹ và mẫu của 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ị được 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ị được phân giải dùng để hiển thị Trang trình bày 1 như sau:

• PropertyA là "Đỏ".
• PropertyB là "Cam".

Kế thừa các thuộc tính hình dạng

Các 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ẹ của phần giữ chỗ đó. 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 các 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ỗ gốc của bố cục.

Khi hệ thống phân cấp kế thừa này được xác định, 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 phần tử mẹ xác định, hình dạng con sẽ chấp nhận giá trị được kế thừa.

Sơ đồ sau đây cho thấy sự kế thừa các thuộc tính giữa 3 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 mẫu:

Các thuộc tính dùng để kết xuất một 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:

• Placeholder1: propertyA được hiển thị là "Vàng", propertyB là "Xanh lục".
• Placeholder2: propertyA được hiển thị là "Vàng", propertyB là "Tím".
• Placeholder3: 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" các thuộc tính bằng PropertyState

Liệt kê PropertyState để kiểm soát xem 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 nếu giá trị chỉ được dùng để kế thừa bởi các hình dạng con. Thuộc tính có trạng thái thuộc tính NOT_RENDERED sẽ không được dùng khi kết xuất hình dạng trên trang của thuộc tính đó. Tuy nhiên, các thành phần 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 sự kế thừa các thuộc tính giữa 3 phần giữ chỗ thao tác với trường PropertyState:

Việc kết xuất các thuộc tính hình dạng có thể bị ảnh hưởng bởi 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:

• Placeholder1: propertyA được hiển thị là "Đỏ".
• Placeholder2: propertyA không được hiển thị. Nếu đây là thuộc tính đường viền, thì Placeholder2 sẽ không có đường viền.
• Placeholder3: propertyA không được hiển thị.

Có thêm một giá trị có thể có của phép liệt kê PropertyState: trạng thái thuộc tính INHERIT có nghĩa là trạng thái thuộc tính đó được kế thừa và giá trị của thành phần mẹ sẽ được dùng. Các hình dạng không có đối tượng mẹ không thể có trạng thái thuộc tính là INHERIT.