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를 사용하여 텍스트를 수정해야 하는 경우 모든 적절한 텍스트 요소를 명시적으로 만들 필요는 없습니다. 대신 Slides 편집기에서와 같이 텍스트를 삽입하고 범위를 삭제하고 범위의 스타일을 업데이트하여 텍스트 작업을 할 수 있습니다. 이러한 작업은 변경사항을 반영하는 데 필요한 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는 단락의 기존 글머리기호를 모두 삭제합니다.
상속된 스타일
placeholders라고 하는 일부 도형은 다른 상위 도형에서 텍스트 스타일을 상속받을 수 있습니다. 도형 상속에 관한 일반적인 내용은 placeholders를 참고하세요.
이 섹션에서는 스타일 상속이 작동하여 슬라이드에 표시되는 렌더링된 최종 텍스트 스타일을 만드는 방법을 중점적으로 설명합니다.
자리표시자의 스타일 표현
placeholders 섹션에서는 상위 도형과 하위 도형 간에 상속이 작동하는 방식을 설명합니다. 텍스트 스타일 상속은 상속 모델 내 추가 기능으로 처리됩니다.
- ParagraphMaker 텍스트 요소의 속성은 단락 서식을 정의합니다.
- TextRun 텍스트 요소의 속성은 문자 형식을 정의합니다.
- 상위 자리표시자의 콘텐츠에는 8개의 목록 중첩 수준을 지원하기 위해 이러한 ParagraphMarker/TextRun 쌍이 8개 포함됩니다.
- 하위 자리표시자는 상위 요소의 텍스트 콘텐츠에 있는 이러한 텍스트 요소에서 기본 텍스트 속성을 상속합니다.
다음 다이어그램은 이러한 관계를 시각화하는 한 가지 방법을 보여줍니다.
상위 도형의 첫 번째 ParagraphMarker/TextRun은 상속된 대부분의 텍스트 스타일 지정을 결정합니다. 나머지 7개 쌍의 스타일 지정은 점진적으로 더 깊이 중첩된 글머리기호 수준의 단락에만 영향을 미칩니다.
| 상위 텍스트 요소 쌍 | 하위 요소 서식 지정 |
|---|---|
처음 ParagraphMarker처음 TextRun |
수준 0 (가장 바깥쪽) 목록 단락 및 목록이 아닌 모든 단락의 텍스트 스타일입니다. |
두 번째 ParagraphMarker두 번째 TextRun |
나머지(중첩된) 목록 수준 1~7의 텍스트 스타일 |
세 번째 ParagraphMarker세 번째 TextRun |
|
네 번째 ParagraphMarker네 번째 TextRun |
|
다섯 번째 ParagraphMarker다섯 번째 TextRun |
|
여섯 번째 ParagraphMarker여섯 번째 TextRun |
|
일곱 번째 ParagraphMarker일곱 번째 TextRun |
|
여덟 번째 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포그라운드 색상으로 렌더링됩니다.
목록 단락의 스타일 상속
'This paragraph is in a list'라는 텍스트가 포함된 다음 단락은 중첩 수준 1의 글머리 기호 목록에 있습니다. 상응하는 ParagraphMarker에 이 수준으로 설정된 bullet 필드가 있기 때문입니다. 따라서 상위 요소의 중첩 수준 1에서 텍스트와 단락 스타일을 상속합니다. 이에 따라 다음과 같이 렌더링됩니다.
- 텍스트: '목록에 있는 단락입니다.'는 렌더링된 텍스트입니다. 텍스트 자체는 상속되지 않습니다.
- 정렬: 텍스트는 'END' 정렬로 렌더링되며 상위 요소의 두 번째
ParagraphMarker에서 상속됩니다. - 포그라운드 색상: 텍스트는 상위 요소의 두 번째
TextRun에서 상속되는LIGHT1텍스트 포그라운드 색상으로 렌더링됩니다.
텍스트 및 단락 스타일의 업데이트와 상속 간의 상호작용
하위 도형에 설정되지 않은 텍스트 스타일은 상위 도형에서 값을 상속합니다. 하위 요소에 설정된 텍스트 스타일은 일부 로컬 범위에서 상위 값을 '재정의'합니다.
UpdateTextStyleRequest를 사용하여 하위 도형의 텍스트 스타일을 설정 해제하여 더 이상 로컬 재정의를 포함하지 않고 상위 도형에서 스타일을 상속하도록 할 수 있습니다. 또한 하위 요소의 텍스트 스타일을 상위 요소에서 상속된 값과 일치하도록 업데이트하면 암시적으로 스타일이 설정 해제되어 상속된 값이 사용됩니다.
이는 업데이트 직후에 텍스트의 시각적 모양에 영향을 미치지 않지만 나중에 상위 자리표시자의 단락 또는 텍스트 스타일을 업데이트하는 경우 문제가 될 수 있습니다. 이 상속 동작은 Slides 편집기의 동작과 일치하므로 API를 사용하기 전에 스타일 변경 결과를 실험할 수 있습니다.
예
이전 예의 ChildPlaceholder 및 ParentPlaceholder 정의를 고려해 보세요.
이제 다음 UpdateTextStyleRequest를 제출한다고 가정합니다.
{ "updateTextStyle": {
"objectId": "ChildPlaceholder",
"style": {"foregroundColor": {"opaqueColor": {"themeColor": "DARK1"} }, },
"textRange": { "type": "ALL" },
"fields": "foregroundColor"
}
}
이 요청에서는 필드 마스크를 사용하여 요소의 포그라운드 색상만 변경되도록 지정함으로써 DARK1 focusColor를 모든 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에서 상속받습니다. - 마지막으로 나머지 상위 자리표시자 객체에서 상속하려고 합니다.