Для эффективного использования API Slides необходимо понимать архитектуру презентаций и их компонентов, а также взаимодействие между этими компонентами. На этой странице представлен подробный обзор этих тем:
- Концептуальная модель компонентов презентации
- Как API представляет эти компоненты
- Свойства оформления компонентов
Ознакомление с этим и другими обзорами концепций облегчит понимание и использование руководств по применению , справочной документации и примеров рецептов .
Презентации, страницы и элементы страниц
В Google Slides самым внешним элементом-контейнером является презентация . Это тот элемент, который можно сохранить в Google Диск, поделиться им с другими пользователями и так далее.
Каждая презентация содержит различные типы страниц . Один из типов страниц — это слайды , то есть страницы, которые пользователи видят и между которыми переключаются во время отображения презентации на экране.
Каждая страница содержит ряд элементов , которые вместе составляют содержимое страницы, как показано на следующей диаграмме:
Помимо слайдов, существуют и другие типы страниц, позволяющие применять дизайн ко множеству различных слайдов, создавая единый стиль. Этими другими типами страниц являются шаблоны и макеты , и их свойства определяют способ отображения слайдов, как показано на следующей диаграмме:
Мастер-слайды — Мастер-страница выполняет две функции. Заполнители на мастер-слайде содержат значения по умолчанию для стилей текста, используемых во всей презентации. Фон и любые другие фигуры на мастер-слайде составляют фон по умолчанию для всех слайдов, основанных на этом мастер-слайде. Если у вас есть логотип компании, который вы хотите отображать на каждом слайде презентации, разместите его на мастер-слайде.
Макеты — Шаблоны макетов определяют, как контент располагается на каждом типе слайда. Например, если вы хотите, чтобы все ваши титульные слайды выглядели определенным образом, вы можете отредактировать шаблон макета титульного слайда.
Существуют еще два типа страниц — страницы для заметок и шаблоны заметок, — которые в основном актуальны для работы с заметками докладчика .
Типы и структура представления API
В этом разделе описывается, как концептуальная модель Google Slides, описанная выше, представлена в API Slides.
На следующей диаграмме показана взаимосвязь между презентациями, страницами и элементами страниц как типами данных в API Slides:
В следующих разделах показано, как эти типы представлены в формате JSON.
Презентации
Презентация включает в себя ряд свойств и содержит страницы, которые в неё входят:
{
"presentationId": string,
"pageSize": { object(Size) },
"slides": [ { object(Page) } ],
"title": string,
"masters": [ { object(Page) } ],
"layouts": [ { object(Page) } ],
"notesMaster": object(Page),
"locale": string,
}
Страницы
Страница содержит набор свойств и включает в себя элементы страницы, которые на ней находятся:
{
"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.
}
Элементы страницы
Элементы страницы — это визуальные компоненты, размещаемые на страницах. В API элемент страницы содержит ряд свойств, включая поле, которое изменяется в зависимости от типа элемента страницы:
{
"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.
}
Существует несколько типов элементов страницы, как определено в приведенном выше определении полем объединения element_kind . Эти типы элементов страницы описаны в следующей таблице:
| Тип элемента | Описание |
|---|---|
| Группа | Набор элементов страницы, рассматриваемых как единое целое. Их можно перемещать, масштабировать и вращать одновременно. |
| Форма | Простые визуальные объекты, такие как прямоугольники, эллипсы и текстовые поля. Фигуры могут содержать текст, поэтому они являются наиболее распространенными элементами страниц для создания слайдов. |
| Изображение | Графическое изображение, импортированное в Slides. |
| Видео | Видео, импортированное в Slides. |
| Линия | Визуальная линия, кривая или соединительный элемент. |
| Стол | Сетка контента. |
| WordArt | Визуальный текстовый элемент, который ведёт себя скорее как фигура. |
| Таблица | Диаграмма, импортированная в Slides из Google Sheets. |
Свойства страницы и элементов страницы
API Slides позволяет считывать и обновлять внешний вид страниц и элементов страниц в вашей презентации. Различные элементы страниц поддерживают разные свойства, которые управляют тем, как элемент страницы отображается.
Для каждого типа элемента страницы существует соответствующий элемент свойств и сообщение об обновлении свойств, например:
- На странице присутствует элемент типа «Форма».
- Его поле свойств — shapeProperties.
- Запрос на обновление этих свойств имеет вид UpdateShapePropertiesRequest.
Для каждого типа элементов страницы существует один и тот же набор запросов на обновление элементов/свойств: Изображение / Свойства изображения / Обновление Свойства изображения и так далее.
Атрибут properties можно прочитать везде, где он встречается при чтении элемента; чтобы изменить его значения, используйте его с соответствующим типом запроса в качестве полезной нагрузки для метода batchUpdate , что позволит изменять эти значения в представлении.
Виды недвижимости
В API Slides есть ряд свойств, общих для нескольких типов объектов:
| Свойство | Описание |
|---|---|
| Цвет | В API Slides цвета могут быть либо значением RGB, либо ссылкой на цвет темы. Цвета темы обозначаются именем (например, "DARK1") и могут быть сопоставлены со значениями RGB с помощью цветовой схемы страницы . Эта цветовая схема обычно обновляется при изменении темы презентации в редакторе Slides. |
| Наполнять | Заливка представляет собой отображение пустого пространства внутри объекта. Наиболее распространенный тип заливки в Slides — это сплошная заливка, при которой внутренняя часть объекта заполняется одним сплошным цветом. Заливки также можно использовать для фона страниц. |
| Контур | Контур представляет собой набор линий, окружающих элемент страницы. Цвет линий регулируется параметром «Заливка». Пользователи также могут настраивать ширину и стиль пунктирной линии контура. |
| Тень | Тень представляет собой визуальный эффект, призванный имитировать физическую тень, отбрасываемую объектом. В настоящее время тени в API слайдов доступны только для чтения. |
Обновление свойств
Для обновления свойства используйте соответствующий запрос Update ... Properties в вызове batchUpdate — например, UpdateShapeProperties для фигур. Эти запросы принимают полное сообщение о свойствах и могут использовать маски полей для определения того, какие поля в сообщении о свойствах следует обновить.
наследство имущества
Страница или элемент страницы могут наследовать свойства от своих родительских объектов. Свойства объекта, включая те, которые он определяет, и те, которые он наследует, определяют его окончательный визуальный вид.
- Свойства страницы — страница наследует любые свойства, которые она не определяет сама, но которые определены в макете или шаблоне, на котором она основана.
- Свойства фигуры — Фигуру можно пометить как заполнитель , что позволяет явно ссылаться на другую фигуру-заполнитель (в родительском макете или шаблоне страницы), от которой будут наследоваться свойства.
Эти идеи более подробно изложены в следующих параграфах.
Наследование свойств страницы
Структура слайдов, макетов и шаблонов определяет иерархию наследования внутри презентации: слайды наследуют свойства от макетов, а макеты наследуют свойства от шаблонов. Родительский макет и шаблон слайда указываются в поле slideProperties этого слайда.
Страница может наследовать свойства, такие как фон и цветовая схема , от родительской страницы. Чтобы унаследовать свойство, дочерняя страница просто не устанавливает значение для этого свойства в своем сообщении PageProperties . Не "переопределяя" значение, определенное родительской страницей, страница принимает унаследованное значение.
На следующей диаграмме показан слайд, наследующий свойства от макета, который, в свою очередь, наследует свойства от основного макета:
Свойства, используемые для отображения слайда, представляют собой комбинацию тех, которые он определяет, и тех, которые он наследует. В этом примере для отображения слайда 1 используются следующие значения:
- Объект A обозначен красным цветом.
- Объект недвижимости B имеет оранжевый цвет.
Наследование свойств формы
Фигуры могут наследовать свойства, такие как заливка, контур или тень, от других фигур. Фигура является заполнителем, если у нее задано поле Shape.placeholder . Поле Shape.placeholder.parentObjectId дочернего заполнителя идентифицирует его родительский заполнитель. При создании нового слайда на основе макета любые заполнители в этом макете отображаются как дочерние фигуры на новом слайде. Аналогично, заполнители на мастер-страницах могут выступать в качестве родителей заполнителей макета.
При такой иерархии наследования дочерняя страница наследует свойство, не устанавливая это значение в сообщении ShapeProperties . Не переопределяя значение, определенное родительской страницей, дочерняя фигура принимает унаследованное значение.
На следующей диаграмме показано наследование свойств между тремя элементами-заполнителями, которые содержатся в слайде, макете и главном файле:
Свойства, используемые для отображения фигуры-заполнителя, представляют собой комбинацию тех, которые она определяет, и тех, которые она наследует. В этом примере разрешенные значения для этих фигур следующие:
- Placeholder1: свойство A отображается желтым цветом, свойство B — зеленым.
- Placeholder2: свойство A отображается как "желтое", свойство B как "фиолетовое".
- Placeholder3: свойство A отображается как "желтое", свойство B как "фиолетовое".
Фигуры — единственный тип элементов страницы, который может иметь родительские элементы. Другие типы, такие как изображения, таблицы и диаграммы, не могут быть заполнителями и не могут иметь родительских элементов.
«Скрытие» свойств с помощью PropertyState
Перечисление PropertyState определяет, используется ли свойство фигуры фактически для отрисовки, или же его значение используется только для наследования дочерними фигурами. Свойство со значением состояния NOT_RENDERED не будет использоваться при отрисовке фигуры на странице, однако дочерние фигуры со значением состояния RENDERED могут наследовать это свойство.
На следующей диаграмме показано наследование свойств между тремя заполнителями, которые изменяют поле PropertyState:
На отображение свойств фигур может влиять поле PropertyState. В этом примере для этих фигур вычисляются следующие значения:
- Placeholder1: свойство A отображается как "Красный".
- Placeholder2: свойство A не отображается. Если бы это было свойство контура, у Placeholder2 не было бы контура.
- Placeholder3: свойство A не отображается.
Существует еще одно возможное значение перечисления PropertyState : состояние свойства INHERIT означает, что состояние свойства наследуется, и следует использовать значение родительского элемента. Фигуры без родителей не могут иметь состояние свойства INHERIT .