Slides API에서 텍스트는 도형이나 표 셀에 포함될 수 있습니다. 텍스트를 조작하고 스타일을 지정하려면 먼저 텍스트의 구조와 스타일 지정 작동 방식을 이해해야 합니다.
이 페이지에서는 Slides API에서 텍스트가 표현되는 방식을 설명합니다.
텍스트 요소 시퀀스
도형 또는 표 셀에 포함된 텍스트는 TextElement 구조의 시퀀스로 구성됩니다. 이 시퀀스는 텍스트의 구조를 처음부터 끝까지 표시되는 순서로 나타냅니다.
예를 들어 다음 슬라이드의 콘텐츠를 살펴보겠습니다. 모든 내용이 하나의 텍스트 상자에 포함되어 있습니다.
위 슬라이드에는 텍스트 상자가 하나 있는데, 이 텍스트 상자의 text 필드에는 다음 다이어그램과 같이 텍스트 요소의 시퀀스가 포함되어 있습니다.
더 구체적으로 이 텍스트 시퀀스는 Slides API에 다음과 같이 표시됩니다.
"textElements": [ {
"endIndex": 224,
"paragraphMarker": { "style": {} }
}, {
"endIndex": 130,
"textRun": { "content": "Li lingues differe in li grammatica e li vocabules. Omnicos directe al desirabilite de un nov ", "style": {} }
}, {
"endIndex": 143,
"startIndex": 130,
"textRun": { "content": "lingua franca", "style": { "italic": True } }
}, {
"endIndex": 224,
"startIndex": 143,
"textRun": { "content": ": solmen va esser necessi far:\n", "style": {} }
}, {
"endIndex": 243,
"startIndex": 224,
"paragraphMarker": {
"style": { "indentStart": { "magnitude": 36, "unit": "PT" }, "direction": "LEFT_TO_RIGHT", "indentFirstLine": { "magnitude": 18, "unit": "PT" }, "spacingMode": "COLLAPSE_LISTS" },
"bullet": { "listId": "foo123", "glyph": "\u25cf" }
}
}, {
"endIndex": 243,
"startIndex": 224,
"textRun": { "content": "uniform grammatica\n", "style": {} }
}, {
"endIndex": 257,
"startIndex": 243,
"paragraphMarker": {
"style": { "indentStart": { "magnitude": 36, "unit": "PT" }, "direction": "LEFT_TO_RIGHT", "indentFirstLine": { "magnitude": 18, "unit": "PT" }, "spacingMode": "COLLAPSE_LISTS" },
"bullet": { "listId": "foo123", "glyph": "\u25cf" }
}
}, {
"endIndex": 257,
"startIndex": 243,
"textRun": { "content": "Pronunciation\n", "style": {} }
}, {
"endIndex": 277,
"startIndex": 257,
"paragraphMarker": {
"style": { "indentStart": { "magnitude": 36, "unit": "PT" }, "indentFirstLine": { "magnitude": 18, "unit": "PT" }, "spacingMode": "COLLAPSE_LISTS" },
"bullet": { "listId": "foo123", "glyph": "\u25cf" }
}
}, {
"endIndex": 277,
"startIndex": 257,
"textRun": { "content": "plu sommun paroles.\n", "style": {} }
}, {
"endIndex": 500,
"startIndex": 277,
"paragraphMarker": { "style": {} }
}, {
"endIndex": 500,
"startIndex": 277,
"textRun": { "content": "Ka swu thefognay, tay waddeant varpa u inzo.\n", "style": {} }
}]
TextElement 콘텐츠
각 텍스트 요소에는 0 기반 시작 색인 및 끝 색인이 포함되며, 이는 페이지 요소의 전체 텍스트 내에서 요소의 위치를 나타내며 다음 유형의 텍스트 객체 중 하나와 함께 포함됩니다.
| 텍스트 종류 | 설명 |
|---|---|
| ParagraphMarker | 이 텍스트 요소는 새 단락의 시작을 나타냅니다. 텍스트 요소의 시작 색인과 끝 색인은 단락을 종료하는 줄바꿈 문자를 포함하여 단락의 전체 범위를 나타냅니다. 한 단락이 다른 단락과 겹치는 일은 없습니다. 단락은 항상 줄 바꿈 문자로 끝나므로 도형이나 표 셀의 텍스트 콘텐츠 끝에는 항상 줄 바꿈 문자가 있습니다. 단락은 글머리 기호 목록이나 번호 목록에 속할 수 있습니다. 이 경우 ParagraphMarker.bullet 필드 콘텐츠에 목록 ID가 포함됩니다. 이 ID는 TextElement 시퀀스와 함께 TextContent 내에 있는 목록 요소를 참조합니다. 동일한 논리 목록 내의 단락은 동일한 목록 ID를 참조합니다. |
| TextRun | 이 텍스트 요소는 모두 동일한 텍스트 스타일을 가진 연속된 텍스트 문자열을 나타냅니다. 텍스트 행은 단락 경계를 넘지 않습니다. 한 단락의 끝 텍스트가 다음 단락의 시작 텍스트와 스타일이 동일하더라도 내용은 줄바꿈 문자 뒤에서 분할되어 별도의 텍스트 행을 형성합니다. 페이지 요소 내에서 전체 텍스트 문자열을 처리해야 하는 경우 모든 텍스트 요소를 반복하면서 모든 텍스트 행에서 발견된 문자열을 연결합니다. |
| AutoText | 자동 텍스트는 텍스트에서 문맥에 따라 동적으로 변경되는 위치를 말합니다. Slides에서는 텍스트 내에서 현재 슬라이드 번호를 나타내는 데 사용됩니다. |
텍스트 콘텐츠 수정
Slides API를 사용하여 텍스트를 수정해야 하는 경우 적절한 텍스트 요소를 모두 명시적으로 만들 필요는 없습니다. 대신 텍스트를 삽입하고, 범위를 삭제하고, 범위의 스타일을 업데이트하는 등 슬라이드 편집기에서와 마찬가지로 텍스트를 처리할 수 있습니다. 이러한 작업은 변경사항을 반영하기 위해 필요에 따라 ParagraphMarker 및 TextRun 요소를 암시적으로 만듭니다.
텍스트 삽입
batchUpdate 호출에서 InsertTextRequest 요청을 사용하여 색인에 텍스트를 삽입할 수 있습니다. 이 메서드의 insertionIndex 필드는 텍스트를 삽입할 위치를 지정합니다. 텍스트 요소 내의 시작 및 끝 색인 필드를 사용하여 이 색인을 계산할 수 있습니다.
텍스트 삽입에는 Slides 편집기의 동작을 반영하는 몇 가지 부작용이 있습니다.
- 줄바꿈 문자를 삽입하면 새 단락이 암시적으로 생성되어 줄바꿈 인덱스에서 시작하고 다음 줄바꿈에서 끝나는
ParagraphMarker텍스트 요소가 생성됩니다. 글머리기호 및 목록 세부정보를 비롯한 문단 스타일이 현재 문단에서 새 문단으로 복사됩니다. - 삽입된 문자의 스타일은 일반적으로 삽입 인덱스에 있던 것과 동일한 텍스트 스타일을 유지하면서 자동으로 결정됩니다. 따라서 텍스트는 일반적으로 해당 색인의 기존
TextRun에 삽입됩니다. 나중에 UpdateTextStyle 요청을 사용하여 이 스타일을 업데이트할 수 있습니다.
텍스트 삭제
batchUpdate 호출에서 DeleteTextRequest 메시지를 사용하여 텍스트 범위를 삭제할 수 있습니다. 텍스트를 삭제할 때는 몇 가지 사항에 유의해야 합니다.
- 단락 경계를 넘는 삭제는 두 단락을 병합하여 구분하는
ParagraphMarker텍스트 요소를 삭제합니다. - 새로 병합된 단락은 Slides 편집기의 동작과 일치하는 결합된 단락 스타일을 사용합니다.
- 범위가 텍스트 런을 포함하는 삭제는 텍스트 런의 모든 콘텐츠를 삭제하고 텍스트 런 자체도 삭제합니다.
- 범위가
AutoText요소를 포함하는 삭제는AutoText요소를 삭제합니다.
텍스트 스타일 업데이트
슬라이드에서 텍스트의 렌더링된 모양은 텍스트 스타일 속성에 따라 결정됩니다.
- 들여쓰기, 정렬, 글머리기호 글리프와 같은 단락 스타일은 단락 마커의 속성으로 정의됩니다.
- 굵게, 기울임꼴, 밑줄과 같은 문자 스타일은 개별 텍스트 실행의 속성으로 정의됩니다.
캐릭터 스타일 업데이트
batchUpdate 호출에서 UpdateTextStyleRequest 메시지를 사용하여 문자 스타일을 업데이트할 수 있습니다.
다른 텍스트 작업과 마찬가지로 문자 스타일은 텍스트 범위에 적용되며 필요에 따라 새 TextRun 객체를 암시적으로 만듭니다.
일부 문자 스타일을 설정하면 Slides 편집기의 동작과 일치하도록 다른 관련 스타일이 암시적으로 업데이트됩니다. 예를 들어 링크를 추가하면 텍스트 전경 색상과 밑줄 속성이 자동으로 변경됩니다. 자세한 내용은 TextStyle 참조 문서를 참고하세요.
문단 스타일 업데이트
batchUpdate 호출에서 UpdateParagraphStyleRequest 메시지를 사용하여 문단 스타일을 업데이트할 수 있습니다.
Slides API는 글머리기호 목록과 번호 목록을 만들기 위해 Slides 편집기의 글머리기호 사전 설정 기능을 미러링하는 CreateParagraphBulletsRequest를 지원합니다. 마찬가지로 DeleteParagraphBulletsRequest는 문단의 기존 글머리기호를 삭제합니다.
상속된 스타일
자리표시자라고 하는 일부 도형은 다른 상위 도형에서 텍스트 스타일을 상속받을 수 있습니다. 일반적인 도형 상속은 자리표시자를 참고하세요.
이 섹션에서는 스타일 상속이 작동하여 슬라이드에 표시되는 최종 렌더링된 텍스트 스타일을 만드는 방법을 중점적으로 설명합니다.
자리표시자의 스타일 표현
자리표시자 섹션에서는 상위 도형과 하위 도형 간에 상속이 작동하는 방식을 설명합니다. 텍스트 스타일 상속은 상속 모델 내의 추가 기능으로 처리됩니다.
- ParagraphMaker 텍스트 요소의 속성은 단락 서식을 정의합니다.
- TextRun 텍스트 요소의 속성은 문자 서식을 정의합니다.
- 상위 자리표시자의 콘텐츠에는 이러한 ParagraphMarker/TextRun 쌍이 8개 포함되어 있습니다 (8단계의 목록 중첩을 지원하기 위함).
- 하위 자리표시자는 상위 텍스트 콘텐츠의 이러한 텍스트 요소에서 기본 텍스트 속성을 상속합니다.
다음 다이어그램은 이러한 관계를 시각화하는 한 가지 방법을 보여줍니다.
상위 도형의 첫 번째 ParagraphMarker/TextRun은 상속된 텍스트 스타일의 대부분을 결정합니다. 나머지 7개 쌍의 스타일은 점점 더 깊이 중첩된 글머리기호 수준의 단락에만 영향을 미칩니다.
| 상위 텍스트 요소 쌍 | 제어하는 하위 서식 |
|---|---|
첫 ParagraphMarker첫 TextRun |
수준 0 (가장 바깥쪽) 목록 단락 및 목록이 아닌 모든 단락의 텍스트 스타일입니다. |
두 번째 ParagraphMarker두 번째 TextRun |
나머지(중첩된) 목록 수준 1~7의 텍스트 스타일 |
세 번째 ParagraphMarker세 번째 TextRun |
|
4번째 ParagraphMarker4번째 TextRun |
|
5번째 ParagraphMarker5번째 TextRun |
|
여섯 번째 ParagraphMarker여섯 번째 TextRun |
|
일곱 번째 ParagraphMarker일곱 번째 TextRun |
|
8분음표 ParagraphMarker8분음표 TextRun |
이러한 텍스트 요소 쌍에 액세스하려면 아래 스니펫과 같이 textElements 필드 내에서 명시적 색인을 사용합니다. 이 스니펫에서는 수준 0 및 목록이 아닌 단락의 기본 (상속 가능) 스타일 설정을 보여줍니다.
"text": {
"textElements": [ {
"startIndex": 0,
"endIndex": 1,
"paragraphMarker": {
"style": { "alignment": "START", ... },
"bullet": { "nestingLevel": 0, ... }
}
},{
"startIndex": 0,
"endIndex": 1,
"textRun": {
"content": "\n",
"style": { "foregroundColor": { "opaqueColor": { "themeColor": "DARK1" } }, }
}
},{
...
} ]
}
상위 도형의 TextRun에 있는 content 필드는 항상 단일 줄바꿈 문자로 구성됩니다.
상속된 스타일은 재정의할 수 있습니다.
하위 도형은 콘텐츠의 ParagraphMarker 및 TextRun 요소에 스타일 속성을 지정할 수 있습니다. 이러한 로컬로 지정된 속성은 로컬 범위 내에서 상속된 모든 속성을 재정의합니다. 스타일을 지정하지 않는 요소는 상위 요소에서 상속된 해당 스타일을 사용합니다.
하위 도형에서 명시적 스타일 속성을 삭제하여 더 이상 설정되지 않도록 하면 상위 요소에서 상속됩니다.
예
위의 다이어그램에 표시된 상속을 고려할 때 도형 ParentPlaceholder에는 다음과 같은 텍스트 콘텐츠가 있다고 가정해 보겠습니다.
"text": {
"textElements": [
{ "startIndex": 0, "endIndex": 1,
"paragraphMarker": {
"style": {"alignment": "START", ...},
"bullet": {"nestingLevel": 0, ...}
}
},
{ "startIndex": 0, "endIndex": 1,
"textRun": {
"content": "\n",
"style": {"foregroundColor": {"opaqueColor": {"themeColor": "DARK1"} }, }
...
}
},
{ "startIndex": 1, "endIndex": 2,
"paragraphMarker": {
"style": {"alignment": "END", ...},
"bullet": {"nestingLevel": 1, ...}
}
},
{ "startIndex": 1, "endIndex": 2,
"textRun": {
"content": "\n",
"style": {"foregroundColor": {"opaqueColor": {"themeColor": "LIGHT1"} }, ...}
}
},
...
]
}
그리고 도형 ChildPlaceholder에 다음과 같은 텍스트 콘텐츠가 있다고 가정해 보겠습니다.
"text": {
"textElements": [
{ "startIndex": 0, "endIndex": 1,
"paragraphMarker": {
"style": {},
}
},
{ "startIndex": 0, "endIndex": 1,
"textRun": {
"content": "This is my first paragraph\n",
"style": {},
}
...
},
{ "startIndex": 1, "endIndex": 2,
"paragraphMarker": {
"style": {},
"bullet": {
"nestingLevel": 1,
"listId": "someListId",
"glyph": "●"
}
}
},
{ "startIndex": 1, "endIndex": 2,
"textRun": {
"content": "This paragraph is in a list\n",
"style": {},
...
}
}
]
}
이에 따라 다음 단락에 설명된 결과가 발생합니다.
일반 단락의 스타일 상속
'This is my first paragraph'라는 텍스트가 포함된 하위 도형의 첫 번째 단락은 목록에 포함되지 않은 일반 단락입니다. 텍스트 콘텐츠의 요소는 스타일 속성을 지정하지 않으므로 모든 문자 및 단락 스타일을 상위 요소에서 상속받습니다. 이로 인해 다음과 같은 렌더링이 발생합니다.
- 텍스트: 렌더링된 텍스트는 'This is my first paragraph'입니다. 텍스트 자체는 상속되지 않습니다.
- 정렬: 텍스트가 상위 요소의 첫 번째
ParagraphMarker에서 상속된START정렬로 렌더링됩니다. - 전경 색상: 텍스트가 상위 요소의 첫 번째
TextRun에서 상속된DARK1전경 색상으로 렌더링됩니다.
목록 단락의 스타일 상속
'이 단락은 목록에 있습니다'라는 텍스트가 포함된 다음 단락은 해당 ParagraphMarker의 bullet 필드가 이 수준으로 설정되어 있으므로 중첩 수준 1의 글머리기호 목록에 있습니다. 따라서 상위 요소의 중첩 수준 1에서 텍스트 및 단락 스타일을 상속받습니다. 그러면 다음과 같은 렌더링이 실행됩니다.
- 텍스트: '이 단락은 목록에 있습니다'라는 텍스트가 렌더링됩니다. 텍스트 자체는 상속되지 않습니다.
- 정렬: 텍스트가 상위 요소의 두 번째
ParagraphMarker에서 상속된 'END' 정렬로 렌더링됩니다. - 전경 색상: 텍스트가 상위 요소의 두 번째
TextRun에서 상속된LIGHT1텍스트 전경 색상으로 렌더링됩니다.
텍스트 및 단락 스타일 업데이트와 상속 간의 상호작용
하위 도형에 설정되지 않은 텍스트 스타일은 상위 요소에서 값을 상속합니다. 하위 요소에 설정된 텍스트 스타일은 일부 로컬 범위에서 상위 요소 값을 '재정의'합니다.
UpdateTextStyleRequest를 사용하여 하위 도형의 텍스트 스타일을 설정 해제하면 더 이상 로컬 재정의가 없으므로 상위 도형에서 스타일을 상속받습니다. 또한 상위 요소에서 상속된 값과 일치하도록 하위 요소의 텍스트 스타일을 업데이트하면 상속된 값을 사용하도록 스타일이 암시적으로 설정 해제됩니다.
이는 업데이트 직후 텍스트의 시각적 표시에는 영향을 미치지 않지만 나중에 상위 자리표시자에서 단락이나 텍스트 스타일을 업데이트하는 경우에는 문제가 될 수 있습니다. 이 상속 동작은 슬라이드 편집기의 동작과 일치하므로 API를 사용하기 전에 스타일 변경의 결과를 실험할 수 있습니다.
예
ChildPlaceholder 및 ParentPlaceholder에 관한 이전 예의 정의를 생각해 보세요.
이제 다음 UpdateTextStyleRequest를 제출한다고 가정해 보겠습니다.
{ "updateTextStyle": {
"objectId": "ChildPlaceholder",
"style": {"foregroundColor": {"opaqueColor": {"themeColor": "DARK1"} }, },
"textRange": { "type": "ALL" },
"fields": "foregroundColor"
}
}
이 요청은 필드 마스크를 사용하여 요소의 전경 색상만 변경되어야 한다고 지정하여 DARK1 foregroundColor를 ChildPlaceholder의 모든 텍스트에 설정하려고 시도합니다. 이 요청의 결과는 다음과 같습니다.
- 첫 번째 단락: 새
foregroundColor가 상속된foregroundColor와 일치하므로 이 스타일은 변경되지 않고 계속 상속됩니다. - 두 번째 단락: 새
foregroundColor가 상속된foregroundColor와 일치하지 않으므로 두 번째 단락의 전경 색상이DARK1로 업데이트됩니다.
ChildPlaceholder의 텍스트 콘텐츠는 이제 다음과 같습니다.
"text": {
"textElements": [
{ "startIndex": 0, "endIndex": 1,
"paragraphMarker": {
"style": {},
}
},
{ "startIndex": 0, "endIndex": 1,
"textRun": {
"content": "This is my first paragraph\n",
"style": {},
}
...
},
{ "startIndex": 1, "endIndex": 2,
"paragraphMarker": {
"style": {},
"bullet": {"nestingLevel": 1, "listId": "someListId", "glyph": "●" }
}
},
{ "startIndex": 1, "endIndex": 2,
"textRun": {
"content": "This paragraph is in a list\n",
"style": {"foregroundColor": {"opaqueColor": {"themeColor": "DARK1"} }, },
...
}
}
]
}
글머리기호 글리프 텍스트 스타일
글머리기호 글리프에는 일반 텍스트와 마찬가지로 글리프가 렌더링되는 방식을 제어하는 텍스트 스타일이 있습니다. 이러한 텍스트 스타일은 Slides API를 직접 사용하여 수정할 수 없습니다. 하지만 UpdateTextStyleRequest를 사용하여 글머리기호가 포함된 전체 문단을 업데이트하면 Slides API는 글머리기호 글리프의 텍스트 스타일을 일치하도록 업데이트합니다.
글꼴 글리프 텍스트 스타일은 일반 텍스트 스타일과 약간 다른 상속 계층 구조를 따릅니다.
- 특정 중첩 수준의 글머리기호는 먼저 글머리기호의
List객체 내NestingLevel.bullet_style필드에 있는TextStyle세트를 상속합니다. - 그런 다음 상위 자리표시자
List의 상응하는NestingLevel.bullet_style에서 상속합니다. - 마지막으로 나머지 상위 자리표시자 객체에서 상속하려고 합니다.