Strony, elementy strony i właściwości

Aby skutecznie korzystać z interfejsu Slides API, musisz zrozumieć architekturę prezentacji i jej komponentów oraz interakcje między nimi. Na tej stronie znajdziesz szczegółowe omówienie tych tematów:

• Model koncepcyjny komponentów prezentacji
• Sposób reprezentowania tych komponentów przez interfejs API
• Właściwości stylów komponentów

Zapoznanie się z tymi i innymi omówieniami koncepcji ułatwi Ci zrozumienie i korzystanie z przewodników, z dokumentacji referencyjnej i z przykładowych kodów.

Prezentacje, strony i elementy strony

Najbardziej zewnętrznym elementem kontenera w Prezentacjach Google jest prezentacja. Jest to jednostka, którą można zapisać na Dysku Google, udostępnić innym użytkownikom itp.

Każda prezentacja zawiera różne typy stron. Jednym z typów stron jest a slajd, czyli strony, które użytkownicy widzą i między którymi się przełączają, gdy prezentacja jest renderowana na ekranie.

Każda strona zawiera szereg elementów strony, które razem tworzą zawartość strony, jak pokazano na tym schemacie:

Oprócz slajdów istnieją też inne typy stron, które pozwalają stosować projekt do wielu różnych slajdów, tworząc spójny wygląd. Te inne typy stron to wzorce i układy, a ich właściwości określają sposób renderowania slajdów, jak pokazano na tym schemacie:

Wzorce – strona wzorcowa służy do 2 celów. Symbole zastępcze we wzorcu zawierają domyślne style tekstu używane w całej prezentacji. Tło i inne kształty na slajdzie wzorcowym tworzą domyślne tło wszystkich slajdów opartych na tym wzorcu. Jeśli chcesz, aby logo firmy pojawiało się na każdym slajdzie w prezentacji, umieść je we wzorcu.

Układy – szablony układów określają sposób rozmieszczenia treści na każdym typie slajdu. Jeśli chcesz, aby wszystkie slajdy tytułowe wyglądały w określony sposób, możesz na przykład edytować szablon układu tytułu.

Istnieją jeszcze 2 rodzaje stron – strony notatek i wzorce notatek – które są przydatne głównie do pracy z notatkami prelegenta.

Typy i struktura reprezentacji interfejsu API

W tej sekcji opisujemy, jak model koncepcyjny Prezentacji Google opisany powyżej jest reprezentowany w interfejsie Slides API.

Ten schemat przedstawia relacje między prezentacjami, stronami i elementami strony jako typami w interfejsie Slides API:

W kolejnych sekcjach pokazujemy, jak te typy są reprezentowane w formacie JSON.

Prezentacje

Prezentacja zawiera szereg właściwości i stron:

{
  "presentationId": string,
  "pageSize": { object(Size) },
  "slides": [ { object(Page) } ],
  "title": string,
  "masters": [ { object(Page) } ],
  "layouts": [ { object(Page) } ],
  "notesMaster": object(Page),
  "locale": string,
}

Strony

Strona zawiera zestaw właściwości i elementów strony:

{
  "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.
}

Elementy strony

Elementy strony to komponenty wizualne umieszczane na stronach. Element strony w interfejsie API zawiera szereg właściwości, w tym pole, które różni się w zależności od rodzaju elementu strony:

{
  "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.
}

Istnieje kilka rodzajów elementów strony, które są zdefiniowane przez pole unii element_kind w definicji powyżej. Te rodzaje elementów strony opisujemy w tej tabeli:

Właściwości strony i elementów strony

Interfejs Slides API umożliwia odczytywanie i aktualizowanie wyglądu stron i elementów strony w prezentacji. Różne elementy strony obsługują różne właściwości, które określają sposób renderowania elementu strony.

Każdy rodzaj elementu strony ma odpowiadający mu element właściwości i komunikat o aktualizacji właściwości, np.:

• Istnieje typ elementu strony Kształt.
• Jego pole właściwości to shapeProperties.
• Żądanie aktualizacji tych właściwości to UpdateShapePropertiesRequest.

Ten sam zestaw elementu, właściwości i żądania aktualizacji istnieje dla każdego typu elementu strony: Obraz/imageProperties/UpdateImageProperties, itd.

Atrybut properties możesz odczytać wszędzie, gdzie go napotkasz podczas odczytywania elementu. Aby zmienić jego wartości, użyj go z pasującym typem żądania jako ładunku metody batchUpdate, co pozwoli Ci zmienić te wartości w prezentacji.

Rodzaje właściwości

Niektóre właściwości są wspólne dla kilku rodzajów obiektów w interfejsie Slides API:

Aktualizowanie właściwości

Aby zaktualizować właściwość, użyj odpowiedniego Update...Properties żądania w wywołaniu batchUpdate, np. UpdateShapeProperties w przypadku kształtów. Te żądania akceptują pełny komunikat o właściwościach i mogą używać masek pól do określania, które pola w komunikacie o właściwościach mają zostać zaktualizowane.

Dziedziczenie w usługach

Strona lub element strony może dziedziczyć właściwości z obiektów nadrzędnych. Właściwości obiektu, w tym te, które definiuje, i te, które dziedziczy, określają jego ostateczny wygląd.

• Właściwości strony – strona dziedziczy wszystkie właściwości, których nie definiuje, ale które są zdefiniowane w układzie lub wzorcu, na którym jest oparta.
• Właściwości kształtu – kształt można oznaczyć jako symbol zastępczy, co pozwala na wyraźne odwoływanie się do innego kształtu symbolu zastępczego (w układzie nadrzędnym lub wzorcu strony), z którego mają być dziedziczone właściwości.

Te pomysły są dokładniej wyjaśnione w kolejnych akapitach.

Dziedziczenie właściwości strony

Struktura slajdów, układów i wzorców definiuje hierarchię dziedziczenia w prezentacji: slajdy dziedziczą z układów, a układy dziedziczą ze wzorców. Układ nadrzędny i wzorzec slajdu są określone w polu slideProperties slajdu.

Strona może dziedziczyć właściwości, takie jak tło i schemat kolorów, ze strony nadrzędnej. Aby dziedziczyć właściwość, strona podrzędna po prostu nie ustawia wartości tej właściwości w PageProperties. Nie „zastępując” wartości zdefiniowanej przez element nadrzędny, strona akceptuje odziedziczoną wartość.

Ten schemat przedstawia slajd dziedziczący właściwości z układu, który dziedziczy ze wzorca:

Właściwości używane do renderowania slajdu to połączenie właściwości, które definiuje, i tych, które dziedziczy. W tym przykładzie wartości używane do renderowania slajdu 1 są następujące:

• PropertyA to „Czerwony”.
• PropertyB to „Pomarańczowy”.

Dziedziczenie właściwości kształtu

Kształty mogą dziedziczyć właściwości, takie jak wypełnienie, kontur lub cień, z innych kształtów. Kształt jest symbolem zastępczym , jeśli ustawione jest jego Shape.placeholder. Pole Shape.placeholder.parentObjectId podrzędnego symbolu zastępczego identyfikuje jego nadrzędny symbol zastępczy. Gdy tworzysz nowy slajd na podstawie układu, wszystkie symbole zastępcze w tym układzie pojawiają się jako kształty podrzędne na nowym slajdzie. Podobnie symbole zastępcze na stronach wzorcowych mogą pełnić rolę elementów nadrzędnych symboli zastępczych układów.

Po zdefiniowaniu tej hierarchii dziedziczenia strona podrzędna dziedziczy właściwość, nie ustawiając jej wartości w komunikacie ShapeProperties. Nie zastępując wartości zdefiniowanej przez element nadrzędny, kształt podrzędny akceptuje odziedziczoną wartość.

Ten schemat przedstawia dziedziczenie właściwości między 3 symbolami zastępczymi, które znajdują się na slajdzie, w układzie i we wzorcu:

Właściwości używane do renderowania kształtu symbolu zastępczego to połączenie właściwości, które definiuje, i tych, które dziedziczy. W tym przykładzie wartości tych kształtów są następujące:

• Symbol zastępczy 1: właściwośćA jest renderowana jako „Żółty”, a właściwośćB jako „Zielony”.
• Symbol zastępczy 2: właściwośćA jest renderowana jako „Żółty”, a właściwośćB jako „Fioletowy”.
• Symbol zastępczy 3: właściwośćA jest renderowana jako „Żółty”, a właściwośćB jako „Fioletowy”.

Kształty to jedyny typ elementu strony, który może mieć elementy nadrzędne. Inne typy, takie jak obrazy, tabele i wykresy, nie mogą być symbolami zastępczymi ani mieć elementów nadrzędnych.

„Ukrywanie” właściwości za pomocą PropertyState

Wyliczenie PropertyState określa, czy właściwość kształtu jest rzeczywiście używana do renderowania, czy też wartość jest używana tylko do dziedziczenia przez kształty podrzędne. Właściwość ze stanem właściwości NOT_RENDERED nie będzie używana podczas renderowania kształtu na stronie, ale elementy podrzędne, które mają odpowiedni stan właściwości RENDERED mogą nadal dziedziczyć tę właściwość.

Ten schemat przedstawia dziedziczenie właściwości między 3 symbolami zastępczymi, które manipulują polem PropertyState:

Na renderowanie właściwości kształtu może mieć wpływ pole PropertyState. W tym przykładzie wartości tych kształtów są następujące:

• Symbol zastępczy 1: właściwośćA jest renderowana jako „Czerwony”.
• Symbol zastępczy 2: właściwośćA nie jest renderowana. Jeśli byłaby to właściwość konturu, symbol zastępczy 2 nie miałby konturu.
• Symbol zastępczy 3: właściwośćA nie jest renderowana.

Istnieje jeszcze jedna możliwa wartość wyliczenia PropertyState: stan INHERIT oznacza, że sam stan właściwości jest dziedziczony i należy użyć wartości elementu nadrzędnego. Kształty bez elementów nadrzędnych nie mogą mieć stanu INHERIT.