Aby skutecznie korzystać z interfejsu Slides API, musisz poznać architekturę prezentacji i ich komponentów, a także interakcje między tymi komponentami. Na tej stronie znajdziesz szczegółowe omówienie tych tematów:
- Model koncepcyjny komponentów prezentacji
- Jak interfejs API reprezentuje te komponenty
- Właściwości stylów komponentów
Zapoznanie się z tym i innymi omówieniami pojęć ułatwi Ci zrozumienie i korzystanie z instrukcji, dokumentacji referencyjnej i przykładowego kodu.
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 itd.
Każda prezentacja zawiera różne typy stron. Jednym z typów stron jest slajd, czyli strona, którą użytkownicy widzą i między którymi się przełączają, gdy prezentacja jest wyświetlana na ekranie.
Każda strona zawiera szereg elementów strony, które razem tworzą jej zawartość, jak pokazano na tym diagramie:
Oprócz slajdów istnieją inne typy stron, które umożliwiają zastosowanie projektu do wielu różnych slajdów, co pozwala uzyskać 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 diagramie:
Strony wzorcowe – strona wzorcowa służy do 2 celów. Obiekty 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 dla wszystkich slajdów opartych na tym wzorcu. Jeśli masz logo firmy, które chcesz wyświetlać na każdym slajdzie prezentacji, umieść je we wzorcu.
Układy – szablony układów określają, jak treści są rozmieszczone na poszczególnych typach slajdów. Jeśli na przykład chcesz, aby wszystkie slajdy tytułowe wyglądały w określony sposób, możesz edytować szablon układu tytułu.
Istnieją jeszcze 2 rodzaje stron – strony notatek i wzorce notatek – które są przydatne głównie podczas pracy z notatkami.
Typy i struktura reprezentacji interfejsu API
W tej sekcji opisujemy, jak model koncepcyjny Prezentacji Google, opisany powyżej, jest reprezentowany w interfejsie Slides API.
Poniższy diagram przedstawia relacje między prezentacjami, stronami i elementami stron jako typami w interfejsie Slides API:
W sekcjach poniżej pokazujemy, jak te typy są reprezentowane w formacie JSON.
Prezentacje
Prezentacja zawiera szereg właściwości oraz strony, które się w niej znajdują:
{
"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 elementy strony, które się na niej znajdują:
{
"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 powyższej definicji. Te rodzaje elementów strony są opisane w tabeli poniżej:
| Rodzaj elementu | Opis |
|---|---|
| Grupa | Zestaw elementów strony, które są traktowane jako pojedyncza jednostka. Można je przenosić, skalować i obracać razem. |
| Kształt | Zwykły obiekt wizualny, taki jak prostokąt, elipsa czy pole tekstowe. Kształty mogą zawierać tekst, więc są najczęstszymi elementami strony, z których tworzy się slajdy. |
| Obraz | Grafika zaimportowana do Prezentacji. |
| Wideo | Film zaimportowany do Prezentacji. |
| Liniowy | Linia, krzywa lub łącznik. |
| Tabela | Siatka treści. |
| WordArt | Wizualny element tekstowy, który zachowuje się bardziej jak kształt. |
| SheetsChart | Wykres zaimportowany do Prezentacji z Arkuszy Google. |
Właściwości strony i elementów strony
Interfejs Slides API umożliwia odczytywanie i aktualizowanie wyglądu stron i elementów stron 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 aktualizacji właściwości, na przykład:
- Istnieje element strony typu Kształt.
- Jego pole właściwości to shapeProperties.
- Żądanie aktualizacji tych właściwości to UpdateShapePropertiesRequest.
Ten sam zestaw elementów, właściwości i żądań aktualizacji istnieje dla każdego typu elementu strony: Image/imageProperties/UpdateImageProperties itd.
Atrybut properties możesz odczytać wszędzie tam, gdzie napotkasz go podczas odczytywania elementu. Aby zmienić jego wartości, użyj go z odpowiednim typem żądania jako ładunkiem metody batchUpdate, co pozwoli Ci zmienić te wartości w prezentacji.
Rodzaje właściwości
Istnieje kilka właściwości, które są wspólne dla kilku rodzajów obiektów w interfejsie Slides API:
| Właściwość | Opis |
|---|---|
| Kolor | Kolory w interfejsie Slides API mogą być wartością RGB lub odwołaniem do koloru motywu. Kolory motywu są określane według nazwy (np. „DARK1”) i można je mapować na wartości RGB za pomocą schematu kolorów strony. Ten schemat kolorów jest zwykle aktualizowany podczas zmiany motywu prezentacji w edytorze Prezentacji. |
| Wypełnienie | Wypełnienie reprezentuje renderowanie pustej przestrzeni wewnątrz obiektu. Najczęściej obsługiwanym wypełnieniem w Prezentacjach jest wypełnienie jednolite, w którym wnętrze obiektu jest wypełnione jednym jednolitym kolorem. Wypełnienia można też stosować jako tła stron. |
| Kontur | Kontur reprezentuje zestaw linii otaczających element strony. Kolor linii jest kontrolowany za pomocą wypełnienia. Można też dostosować szerokość i styl kreski obramowania. |
| Cień | Cień to efekt wizualny, który ma naśladować fizyczny cień rzucany przez obiekt. Obecnie cienie w interfejsie Slides API są tylko do odczytu. |
Aktualizowanie właściwości
Aby zaktualizować właściwość, użyj odpowiedniego żądania Update...Properties w wywołaniu batchUpdate, np. UpdateShapeProperties w przypadku kształtów. Te żądania akceptują pełną wiadomość o właściwościach i mogą używać masek pól, aby określić, które pola w wiadomości o właściwościach powinny 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óre nie są na niej zdefiniowane, ale są zdefiniowane w układzie lub wzorcu, na którym jest oparta.
- Właściwości kształtu – kształt można oznaczyć jako obiekt zastępczy, co pozwala na bezpośrednie odwoływanie się do innego kształtu zastępczego (w układzie nadrzędnym strony lub w slajdzie wzorcowym), z którego mają być dziedziczone właściwości.
Te pomysły zostały szczegółowo opisane 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. Layout 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 odziedziczyć właściwość, strona podrzędna po prostu nie ustawia wartości tej właściwości w komunikacie PageProperties. Jeśli nie „zastąpisz” wartości zdefiniowanej przez element nadrzędny, strona zaakceptuje wartość odziedziczoną.
Na diagramie poniżej widać slajd dziedziczący właściwości z układu, który dziedziczy je z wzorca:
Właściwości używane do renderowania slajdu są kombinacją właściwości, które definiuje, i tych, które dziedziczy. W tym przykładzie wartości użyte do wyrenderowania slajdu 1 są następujące:
- WłaściwośćA to „Czerwony”.
- WłaściwośćB to „Orange”.
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 obiektem zastępczym, jeśli ustawione jest jego pole Shape.placeholder. Pole Shape.placeholder.parentObjectId obiektu zastępczego podrzędnego identyfikuje jego nadrzędny obiekt zastępczy. Gdy tworzysz nowy slajd na podstawie układu, wszystkie obiekty zastępcze w tym układzie pojawiają się jako kształty podrzędne na nowym slajdzie.
Podobnie obiekty zastępcze na stronach wzorcowych mogą działać jako obiekty nadrzędne obiektów zastępczych układów.
Po zdefiniowaniu tej hierarchii dziedziczenia strona podrzędna dziedziczy właściwość, nie ustawiając tej wartości w komunikacie ShapeProperties. Jeśli nie zastąpisz wartości zdefiniowanej przez element nadrzędny, kształt podrzędny zaakceptuje odziedziczoną wartość.
Poniższy diagram przedstawia dziedziczenie właściwości między 3 obiektami zastępczymi, które znajdują się w slajdzie, układzie i wzorcu:
Właściwości używane do renderowania kształtu obiektu zastępczego są kombinacją 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:
- Placeholder1: propertyA jest renderowana jako „Yellow”, a propertyB jako „Green”.
- Placeholder2: właściwośćA jest renderowana jako „Żółty”, a właściwośćB jako „Fioletowy”.
- Placeholder3: propertyA jest renderowana jako „Yellow”, a propertyB jako „Purple”.
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ć obiektami zastępczymi i nie mogą mieć elementów nadrzędnych.
„Ukrywanie” właściwości za pomocą PropertyState
Wyliczenie PropertyState określa, czy właściwość kształtu jest faktycznie używana do renderowania, czy też wartość jest używana tylko do dziedziczenia przez kształty podrzędne. Właściwość ze stanem 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ść.
Poniższy diagram przedstawia dziedziczenie właściwości między 3 obiektami 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 rozwiązane wartości tych kształtów są następujące:
- Placeholder1: propertyA jest renderowany jako „Red”.
- Placeholder2: propertyA is not rendered. Gdyby była to właściwość konturu, Placeholder2 nie miałby konturu.
- Placeholder3: propertyA is not rendered.
Istnieje jeszcze jedna możliwa wartość wyliczenia PropertyState: stan właściwości 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 właściwości INHERIT.