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:
| Rodzaj elementu | Opis |
|---|---|
| Grupa | Zestaw elementów strony, które są traktowane jako pojedyncza jednostka. Można je razem przesuwać, 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. |
| 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 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:
| 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ługiwane wypełnienie w Prezentacjach to wypełnienie jednolite, w którym wnętrze obiektu jest wypełnione jednolitym kolorem. Wypełnienia można też używać jako tła stron. |
| Kontur | Kontur reprezentuje zestaw linii otaczających element strony. Kolor linii jest określany za pomocą wypełnienia. Wywołujący mogą też dostosować szerokość i styl kreskowania konturów. |
| 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ć 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.