Aby skutecznie korzystać z interfejsu Slides API, musisz poznać architekturę prezentacji i ich komponentów oraz interakcje między tymi komponentami. Na tej stronie znajdziesz szczegółowe omówienie tych tematów:
- Model koncepcyjny komponentów prezentacji
- Sposób reprezentowania tych komponentów w interfejsie API
- Właściwości stylu komponentów
Zapoznanie się z tym i innymi omówieniami koncepcji ułatwi Ci zrozumienie i korzystanie z przewodników, dokumentacji i przykładowych przepisów.
prezentacje, strony i elementy stron,
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 rodzaje stron. Jednym z rodzajów stron jest slajd, czyli strona, którą użytkownicy widzą i przełączają, gdy prezentacja jest wyświetlana na ekranie.
Każda strona zawiera szereg elementów strony, które razem tworzą zawartość strony, jak pokazano na poniższym diagramie:
Oprócz slajdów istnieją inne rodzaje stron, które umożliwiają zastosowanie projektu do wielu różnych slajdów, co zapewnia spójny wygląd. 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:
Wzorce – strona wzorcowa służy do dwóch celów. Symbole zastępcze w wzorcu zawierają domyślne style tekstu używane w całej prezentacji. Tło i inne kształty na slajdzie wzorcowym stanowią domyślne tło wszystkich slajdów opartych na tym wzorcu. Jeśli masz logo firmy, które chcesz wyświetlać na każdym slajdzie prezentacji, umieść je na slajdzie wzorcowym.
Układy – szablony układów określają sposób rozmieszczenia treści na poszczególnych typach slajdów. 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 podczas 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.
Na poniższym diagramie przedstawiono 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 wiele właściwości i 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:
{
"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 wiele 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 typu union element_kind w powyższej definicji. Rodzaje elementów strony zostały opisane w tej tabeli:
| Rodzaj elementu | Opis |
|---|---|
| Grupa | Zestaw elementów strony traktowanych jako pojedyncza jednostka. Można je razem przenosić, skalować i obracać. |
| Kształt | Prosty obiekt wizualny, np. prostokąty, elipsy i pola tekstowe. Kształty mogą zawierać tekst, dlatego są najczęściej używanymi elementami strony do tworzenia slajdów. |
| Obraz | Grafika zaimportowana do Prezentacji. |
| Wideo | Film zaimportowany do Prezentacji. |
| Linia | linia, krzywa lub łącznik. |
| Tabela | siatkę treści, |
| WordArt | Element tekstowy, który zachowuje się bardziej jak kształt. |
| SheetsChart | Wykres zaimportowany do Prezentacji z Arkuszy Google. |
Właściwości strony i elementu 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 kontrolują sposób renderowania elementu strony.
Każdy rodzaj elementu strony ma odpowiedni element właściwości i wiadomość o aktualizacji właściwości, np.:
- Istnieje typ elementu strony Kształt.
- 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/żądań aktualizacji istnieje dla każdego typu elementu strony: Image/imageProperties/UpdateImageProperties itd.
Atrybut properties możesz odczytać w dowolnym miejscu, w którym występuje podczas odczytywania elementu. Aby zmienić jego wartości, użyj go z odpowiednim typem żądania jako ładunku metody batchUpdate, co pozwoli Ci zmienić te wartości w prezentacji.
Rodzaje usług
Istnieją właściwości 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 za pomocą nazwy (np. „DARK1”) i można je przypisać do 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 pustego miejsca w obiekcie. Najczęściej obsługiwanym wypełnieniem w Prezentacjach Google jest wypełnienie jednolite, w którym wnętrze obiektu jest wypełnione jednym kolorem. Wypełnienia można też stosować jako tła stron. |
| Kontur | Obramowanie reprezentuje zestaw linii otaczających element strony. Kolor linii jest kontrolowany przez wypełnienie. Dzwoniący mogą też dostosować szerokość i styl linii. |
| Cień | Cień to efekt wizualny, który ma imitować fizyczny cień rzucany przez obiekt. Obecnie cienie w interfejsie Slides API są tylko do odczytu. |
Aktualizowanie właściwości
Aby zaktualizować usługę, użyj odpowiedniego żądania Update...Properties w wywołaniu batchUpdate, np. UpdateShapeProperties w przypadku kształtów. Te żądania akceptują pełną wiadomość o usłudze i mogą używać masek pól, aby określić, które pola w wiadomości o usłudze 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óre nie są zdefiniowane na stronie, 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 symbol zastępczy, co pozwala wyraźnie odwołać się do innego kształtu symbolu zastępczego (w układzie nadrzędnym strony lub wzorcu), z którego można dziedziczyć właściwości.
Te pomysły są bardziej szczegółowo opisane w kolejnych akapitach.
Dziedziczenie właściwości strony
Struktura slajdów, układów i wzorców określa 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 odziedziczyć usługę, strona podrzędna po prostu nie ustawia wartości tej usługi w wiadomości PageProperties. Nie „zastępując” wartości zdefiniowanej przez element nadrzędny, strona akceptuje odziedziczoną wartość.
Na poniższym diagramie 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 to połączenie właściwości zdefiniowanych przez niego i właściwości dziedziczonych. W tym przykładzie wartości użyte do wyrenderowania slajdu 1 są następujące:
- Wartość usługi A to „Red”.
- Wartość usługi 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 symbolem zastępczym, jeśli ustawione jest pole Shape.placeholder. Pole Shape.placeholder.parentObjectId w obiekcie zastępczym podrzędnym
określa jego obiekt zastępczy nadrzędny. Gdy utworzysz nowy slajd na podstawie układu, wszystkie symbole zastępcze w tym układzie będą widoczne jako kształty podrzędne na nowym slajdzie.
Podobnie obiekty zastępcze na stronach wzorcowych mogą pełnić rolę elementów nadrzędnych 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 wiadomości ShapeProperties. Nie zastępując wartości zdefiniowanej przez element nadrzędny, kształt podrzędny przyjmuje odziedziczoną wartość.
Poniższy diagram przedstawia dziedziczenie właściwości między 3 elementami zastępczymi znajdującymi się na slajdzie, w układzie i na slajdzie wzorcowym:
Właściwości używane do renderowania kształtu zastępczego to połączenie właściwości zdefiniowanych przez ten kształt i właściwości dziedziczonych. W tym przykładzie rozwiązane 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: 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ć obiektami zastępczymi ani nie mogą mieć elementów nadrzędnych.
„Ukrywanie” usług 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ść o stanie NOT_RENDERED nie będzie używana podczas renderowania kształtu na stronie, ale elementy podrzędne o stanie RENDERED mogą nadal dziedziczyć tę właściwość.
Poniższy diagram przedstawia dziedziczenie właściwości między 3 symbolami zastępczymi, które modyfikują pole 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: usługa A nie jest renderowana. Jeśli byłaby to właściwość outline, Placeholder2 nie miałby obramowania.
- Placeholder3: właściwośćA nie jest renderowana.
Istnieje jeszcze jedna możliwa wartość wyliczenia PropertyState: stan właściwości INHERIT oznacza, że 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.