페이지, 페이지 요소 및 속성

Slides API를 효과적으로 사용하려면 프레젠테이션의 구조와 구성 요소뿐만 아니라 해당 구성 요소 사이의 상호작용을 이해해야 합니다. 이 페이지에서는 다음 항목에 대한 세부 개요를 제공합니다.

  • 프레젠테이션 구성 요소의 개념적 모델
  • API가 해당 구성 요소를 나타내는 방법
  • 구성 요소의 스타일 지정 속성

이 페이지와 기타 개념 개요를 읽으면 사용법 가이드, 참조 문서레시피 샘플을 이해하고 사용하기가 훨씬 쉬워집니다.

프레젠테이션, 페이지 및 페이지 요소

Google Slides에서 가장 바깥쪽 컨테이너 요소는 프레젠테이션입니다. 프레젠테이션은 Google Drive에 저장하고 다른 사용자와 공유할 수 있는 단위입니다.

각 프레젠테이션은 다양한 유형의 페이지를 포함합니다. 페이지의 한 유형은 슬라이드인데, 슬라이드는 화면에서 프레젠테이션이 렌더링된 상태에서 사용자가 보고 넘기는 페이지입니다.

각 페이지는 다음 다이어그램에 표시된 것처럼 페이지 콘텐츠로 구성된 수많은 페이지 요소를 포함합니다.

슬라이드 구조 다이어그램

서로 다른 많은 슬라이드에 디자인을 적용하여 일관된 모양을 만들 수 있는, 슬라이드 외의 다른 페이지 유형이 있습니다. 이러한 다른 페이지 유형은 마스터레이아웃이며, 그 속성은 다음 다이어그램에 표시된 것처럼 슬라이드 렌더링 방법을 결정합니다.

테마 구조 다이어그램

마스터 — 마스터 페이지는 두 가지 목적을 제공합니다. 마스터에서 자리표시자는 프레젠테이션 전체에 사용되는 텍스트 스타일에 대한 기본값을 포함합니다. 마스터 슬라이드에서 배경 및 기타 도형은 해당 마스터에 기반한 모든 슬라이드에 대한 기본 배경을 구성합니다. 프레젠테이션의 모든 슬라이드에 회사 로고를 표시하려면 해당 로고를 마스터에 배치하면 됩니다.

레이아웃 — 레이아웃 템플릿은 각 슬라이드 유형에 대한 콘텐츠 정렬 방법을 결정합니다. 예를 들어, 모든 제목 슬라이드를 특정한 방식으로 표시하려면 제목 레이아웃 템플릿을 편집할 수 있습니다.

API 프레젠테이션 유형 및 구조

이 섹션에서는 위에서 설명한 Google Slides 개념 모델이 Slides API에 나타나는 방식을 설명합니다.

다음 다이어그램은 Slides API에서 프레젠테이션, 페이지 및 페이지 요소 등의 유형 사이의 관계를 나타냅니다.

erd 스타일 다이어그램

다음 섹션에서는 이러한 유형이 JSON에서 어떻게 나타나는지 보여줍니다.

프레젠테이션

프레젠테이션은 수많은 속성을 포함하며, 페이지들로 구성되어 있습니다.

{
  "presentationId": string,
  "pageSize": { object(Size) },
  "slides": [ { object(Page) } ],
  "title": string,
  "masters": [ { object(Page) } ],
  "layouts": [ { 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) },
  // 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.
}

상기 정의에서 union 필드 element_kind에 의해 정의된 것처럼, 여러 유형의 페이지 요소가 있습니다. 해당 유형의 페이지 요소는 다음 표에 설명되어 있습니다.

요소 유형 설명
Group 개별 단위로 취급되는 페이지 요소 집합입니다. 단체로 이동, 배율 조정 및 회전할 수 있습니다.
Shape 사각형, 타원 및 텍스트 상자와 같은 일반적인 시각적 객체입니다. 도형은 텍스트를 포함할 수 있으므로 프레젠테이션 제작을 위한 가장 일반적인 페이지 요소입니다.
Image Slides로 가져온 그래픽입니다.
Video Slides로 가져온 동영상입니다.
Line 시각적 선, 곡선 또는 연결선입니다.
Table 콘텐츠 그리드입니다.
WordArt 도형처럼 동작하는 시각적 텍스트 요소입니다.
SheetsChart Google Sheets에서 Slides로 가져온 차트입니다.

페이지 및 페이지 요소 속성

Slides API를 사용하여 프레젠테이션에서 페이지 및 페이지 요소의 모양을 읽고 업데이트할 수 있습니다. 서로 다른 페이지 요소는 페이지 요소가 렌더링되는 방법을 제어하는 서로 다른 속성을 지원합니다.

각 페이지 요소 유형에는 해당 속성 요소와 속성 업데이트 메시지가 있습니다. 예를 들면, 다음과 같습니다.

각 페이지 요소 유형에는 동일한 요소/속성 업데이트 요청 집합이 있습니다(Image/imageProperties/UpdateImageProperties 등).

요소를 읽을 때 속성 특성을 만나는 곳마다 속성 특성을 읽을 수 있습니다. 해당 값을 변경하려면 batchUpdate 메서드에 대한 페이로드와 일치하는 요청 유형과 함께 속성 특성을 사용하여 프레젠테이션에서 해당 값을 변경합니다.

속성 유형

Slides API에는 여러 유형의 객체 사이에 일반적인 몇몇 속성이 있습니다.

속성 설명
Color Slides API에서 색은 RGB 값이거나 테마 색에 대한 참조일 수 있습니다. 테마 색은 이름(예: "DARK1")으로 참조되며 페이지의 색 구성표를 사용하여 RGB 값에 매핑될 수 있습니다. 일반적으로 이 색 구성표는 Slides 편집기에서 프레젠테이션의 테마를 변경할 때 업데이트됩니다.
Fill 채우기(fill)는 객체 내 빈 공간 렌더링을 나타냅니다. Slides에서 가장 일반적으로 지원되는 채우기는 객체 내부를 단색으로 채우는 단색 채우기(solid fill)입니다. 채우기는 페이지 배경으로 사용할 수도 있습니다.
Outline 윤곽선(outline)은 페이지 요소를 감싸는 선 집합을 나타냅니다. 선의 색은 채우기(Fill)로 제어합니다. 호출자는 또한 윤곽선의 너비와 대시 스타일을 조절할 수 있습니다.
Shadow 그림자(shadow)는 객체의 물리적인 그림자를 모방하는 시각적 효과를 나타냅니다. 현재 Slides API에서 그림자는 읽기 전용입니다.

속성 업데이트

속성을 업데이트하려면 batchUpdate 호출에서 적절한 Update...Properties 요청을 사용합니다(예: 도형(Shape)의 경우 UpdateShapeProperties) 이러한 요청은 전체 속성 메시지를 수락하고 필드 마스크를 사용하여 속성 메시지에서 업데이트되어야 하는 필드를 판별할 수 있습니다.

* 필드 마스크는 와일드카드로 취급되고 메시지에서 모든 필드를 지정하는 간편한 방법입니다.

읽기 전용 필드 및 새로 추가된 필드가 나중에 오류를 유발할 수 있으므로 프로덕션 코드에 * 필드 마스크를 사용하지 마십시오.

속성 상속

페이지 또는 페이지 요소는 부모 객체의 속성을 상속할 수 있습니다. 정의한 속성 및 상속한 속성을 포함하는 객체의 속성은 시각적인 최종 모양을 결정합니다.

  • 페이지 속성 — 페이지는 자체로 정의하지 않았지만 페이지가 기반으로 하는 레이아웃 또는 마스터에 정의된 속성을 상속합니다.
  • 도형 속성 — 도형은 자리표시자로 표시하여 속성을 (페이지의 부모 레이아웃 또는 마스터에서) 참조할 다른 자리표시자 도형을 명시적으로 참조할 수 있습니다.

이러한 개념에 대해서는 다음 단락에서 설명합니다.

페이지 속성 상속

슬라이드, 레이아웃 및 마스터의 구조는 프레젠테이션 내에서 상속 계층을 정의합니다. 즉, 슬라이드는 레이아웃에서 상속하고 레이아웃은 마스터에서 상속합니다. 슬라이드의 부모 레이아웃 및 마스터는 슬라이드의 slideProperties 필드에 지정됩니다.

페이지는 부모 페이지의 배경색 구성표와 같은 속성을 상속합니다. 속성을 상속하기 위해 자식 페이지는 PageProperties 메시지에 해당 속성 값을 설정하지 않습니다. 부모가 정의한 값을 "재정의"하지 않음으로써 페이지가 상속된 값을 수락합니다.

다음 다이어그램은 레이아웃에서 속성을 상속하고 마스터에서 레이아웃을 상속하는 슬라이드를 보여줍니다.

슬라이드 속성 상속

슬라이드를 렌더링하는 데 사용되는 속성은 슬라이드가 정의한 속성과 상속한 속성의 조합입니다. 이 예시에서 Slide 1을 렌더링하는 데 사용되는 결정된 값은 다음과 같습니다.

  • PropertyA는 "Red"입니다.
  • PropertyB는 "Orange"입니다.

도형 속성 상속

도형은 다른 도형으로부터 채우기, 윤곽선 또는 그림자와 같은 속성을 상속할 수 있습니다. Shape.placeholder 필드를 설정한 경우 도형은 자리표시자(placeholder)입니다. 자식 자리표시자의 Shape.placeholder.parentObjectId 필드는 부모 자리표시자를 식별합니다. 레이아웃에 기반한 새 슬라이드를 만들 때 해당 레이아웃의 자리표시자는 새 슬라이드에서 자식 도형으로 나타납니다. 마찬가지로 자리표시자 또는 마스터 페이지는 레이아웃 자리표시자의 부모 역할을 할 수 있습니다.

상속 계층을 정의한 경우 ShapeProperties 메시지에 해당 값을 설정하지 않으면 자식 페이지가 속성을 설정합니다. 부모가 정의한 값을 재정의하지 않으면 자식 도형이 상속된 값을 수락합니다.

다음 다이어그램은 슬라이드, 레이아웃 및 마스터에 포함된 3개의 자리표시자 간 속성 상속을 보여줍니다.

도형 속성 상속

자리표시자 도형을 렌더링하는 데 사용되는 속성은 도형이 정의한 속성과 상속한 속성의 조합입니다. 이 예시에서 해당 도형에 대해 결정된 값은 다음과 같습니다.

  • Placeholder1: propertyA는 "Yellow"로, propertyB는 "Green"으로 렌더링됩니다.
  • Placeholder2: propertyA는 "Yellow"로, propertyB는 "Purple"로 렌더링됩니다.
  • Placeholder3: propertyA는 "Yellow"로, propertyB는 "Purple"로 렌더링됩니다.

도형은 부모를 가질 수 있는 유일한 페이지 요소 유형입니다. 이미지, 테이블 및 차트와 같은 다른 유형은 자리표시자일 수 없으며 부모를 가질 수 없습니다.

PropertyState을 사용하여 속성 "숨기기"

PropertyState 열거는 도형 속성이 실제로 렌더링에 사용되는지, 또는 해당 속성이 자식 도형이 상속하는 용도로만 사용되는지를 제어합니다. 속성 상태가 NOT_RENDERED인 속성은 도형을 페이지에 렌더링할 때 사용되지 않지만, 해당 속성 상태가 RENDERED인 자식은 해당 속성을 여전히 상속할 수 있습니다.

다음 다이어그램은 PropertyState 필드를 조작하는 3개의 자리표시자 간 속성 상속을 보여줍니다.

속성 상태 및 상속

도형 속성 렌더링은 PropertyState 필드의 영향을 받을 수 있습니다. 이 예시에서 해당 도형에 대해 결정된 값은 다음과 같습니다.

  • Placeholder1: propertyA는 "Red"로 렌더링됩니다.
  • Placeholder2: propertyA는 렌더링되지 않습니다. 윤곽선 속성인 경우 Placeholder2의 윤곽선은 없습니다.
  • Placeholder3: propertyA는 렌더링되지 않습니다.

PropertyState 열거의 또 하나의 가능한 값인 INHERIT 속성 상태는 해당 속성 상태 그 자체가 상속됨을 의미하므로 부모 값을 사용합니다. 부모가 없는 도형은 INHERIT 속성 상태를 가질 수 없습니다.

다음에 대한 의견 보내기...

도움이 필요하시나요? 지원 페이지를 방문하세요.