텍스트 구조 및 스타일 지정

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 Autotext는 컨텍스트에 따라 동적으로 바뀌는 텍스트 위치를 나타냅니다. Slides에서 이를 사용하여 텍스트 내 현재 슬라이드 번호를 나타냅니다.

텍스트 콘텐츠 수정

Slides API를 사용하여 텍스트를 수정해야 하는 경우, 해당하는 모든 텍스트 요소를 명시적으로 만들 필요가 없습니다. 그 대신에, Slides 편집기에서 텍스트 삽입, 범위 삭제, 범위의 스타일 업데이트 등 원하는 텍스트 작업을 수행할 수 있습니다. 이러한 작업은 변경 사항을 반영하는 데 필요한 ParagraphMarkerTextRun 요소를 암시적으로 만듭니다.

텍스트 삽입

batchUpdate 호출 시 InsertTextRequest 요청을 사용하여 인덱스에 텍스트를 삽입할 수 있습니다. 이 메서드의 insertionIndex 필드는 텍스트를 삽입할 위치를 지정합니다. 텍스트 요소 내 시작 및 끝 인덱스 필드를 사용하여 이 인덱스를 계산할 수 있습니다.

텍스트 삽입은 Slides 편집기의 동작을 미러링하는 몇몇 부작용을 유발합니다.

  • 줄바꿈 문자를 암시적으로 삽입하는 경우, 줄바꿈 문자 인덱스에서 시작하고 다음 줄바꿈 문자에서 끝나는 ParagraphMarker 텍스트 요소를 생성하여 새 단락을 생성합니다. 글머리 기호 및 목록 세부정보를 비롯한 단락 스타일은 현재 단락에서 새 단락으로 복사됩니다.
  • 삽입한 문자의 스타일은 자동으로 결정되며, 일반적으로 삽입 인덱스와 동일한 텍스트 스타일을 유지합니다. 결과적으로, 해당 텍스트는 일반적으로 해당 인덱스의 기존 TextRun에 삽입됩니다. 해당 스타일은 UpdateTextStyle 요청을 사용하여 나중에 업데이트할 수 있습니다.

텍스트 삭제

batchUpdate 호출 시 DeleteTextRequest 메시지를 사용하여 텍스트 범위를 삭제할 수 있습니다. 텍스트 삭제 시 주의해야 할 몇몇 사항이 있습니다.

  • 단락 경계를 넘는 삭제는 분리된 ParagraphMarker 텍스트 요소를 삭제하여 두 단락을 병합합니다.
  • 병합된 새 단락은 Slides 편집기의 동작과 일치하도록 결합된 단락 스타일을 사용합니다.
  • 텍스트 런을 포함하는 범위의 삭제는 텍스트 런에서 모든 콘텐츠를 제거하고 텍스트 런 자체도 삭제합니다.
  • AutoText 요소를 포함하는 범위를 삭제하면 AutoText 요소가 삭제됩니다.

텍스트 스타일 업데이트

슬라이드에서 렌더링되는 텍스트 모양은 텍스트 스타일 속성에 의해 결정됩니다.

들여쓰기, 정렬 및 글머리 기호 글리프와 같은 * 단락 스타일은 단락 표식의 속성에서 정의합니다. 굵은 글꼴, 기울임꼴 및 밑줄과 같은 * 문자 스타일은 개별 텍스트 런 속성에서 정의합니다.

단락 스타일 업데이트

batchUpdate 호출 시 UpdateTextStyleRequest 메시지를 사용하여 단락 스타일을 업데이트할 수 있습니다.

다른 텍스트 작업과 마찬가지로 단락 스타일은 텍스트 범위에 적용되고, 필요한 경우 새 TextRun 객체를 암시적으로 만듭니다.

몇몇 단락 스타일을 설정하면 Slides 편집기의 동작과 일치하도록 다른 관련 스타일을 암시적으로 업데이트합니다. 예를 들어, 링크를 추가하면 자동으로 텍스트 전경색 및 밑줄 속성이 바뀝니다. 자세한 내용은 TextStyle 참조 문서를 참조하세요.

단락 스타일 업데이트

Slides API는 Slides 편집기에서 글머리 기호 목록 및 번호 매기기 목록 생성용 글머리 기호 미리 설정 기능을 미러링하는 CreateParagraphBulletsRequest를 지원합니다.

상속된 스타일

자리표시자로 알려져 있는 몇몇 도형은 다른 부모 도형에서 텍스트 스타일을 상속할 수 있습니다. 도형 상속에 대한 전반적인 내용은 자리표시자를 참조하세요.

이 섹션에서는 스타일 상속이 어떤 방식으로 작동하여 슬라이드에 표시되는 최종 렌더링된 텍스트 스타일을 만드는지에 대해 중점적으로 설명합니다.

자리표시자의 스타일 표현

자리표시자에 대한 섹션에서는 부모 도형과 자식 도형 사이에 상속이 어떤 방식으로 작동하는지에 대해 설명합니다. 텍스트 스타일 상속은 상속 모델 내 추가 기능이 처리합니다.

  • 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
여덟 번째 ParagraphMarker
여덟 번째 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"  }  },  }
     }
   },{
     ...
   } ]
 }

부모 도형의 TextRuncontent 필드는 항상 단일 줄바꿈 문자로 구성되어 있습니다.

상속된 스타일은 다시 정의 가능

자식 도형은 콘텐츠의 ParagraphMarkerTextRun 요소에 스타일 지정 속성을 지정할 수 있습니다. 이와 같은 로컬로 지정된 속성은 로컬 범위 내에서 상속된 속성을 다시 정의할 수 있습니다. 스타일을 지정하지 않는 요소는 부모로부터 상속된 해당 스타일을 사용합니다.

더 이상 설정되지 않도록 자식 도형에서 명시적인 스타일 속성을 제거하는 경우 부모로부터 상속합니다.

예시

위 다이어그램에 표시된 상속의 경우 도형 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"는 렌더링된 텍스트입니다. 텍스트 자체는 상속되지 않습니다.
  • 정렬: 텍스트는 START 정렬로 렌더링되며 부모의 첫 번째 ParagraphMarker에서 상속됩니다.
  • 전경색: 텍스트는 DARK1 전경색으로 렌더링되며 부모의 첫 번째 TextRun에서 상속됩니다.

목록 단락에 대한 스타일 상속

"This paragraph is in a list"라는 텍스트를 포함하는 그 다음 단락은 해당 ParagraphMarkerbullet 필드를 이 수준으로 설정하므로 중첩 수준 1에서 글머리 기호 목록에 있습니다. 결과적으로 부모의 중첩 수준 1에서 텍스트 및 단락 스타일을 상속합니다. 이는 다음 렌더링을 도출합니다.

  • 텍스트: "This paragraph is in a list"는 렌더링된 텍스트입니다. 텍스트 자체는 상속되지 않습니다.
  • 정렬: 텍스트는 "END" 정렬로 렌더링되며 부모의 두 번째 ParagraphMarker에서 상속됩니다.
  • 전경색: 텍스트는 LIGHT1 텍스트 전경색으로 렌더링되며 부모의 두 번째 TextRun에서 상속됩니다.

텍스트 및 단락 스타일의 업데이트와 상속 사이의 상호작용

자식 도형에 설정하지 않은 텍스트 스타일은 부모로부터 값을 상속합니다. 자식에 설정된 텍스트 스타일은 특정 로컬 범위에서 부모 값을 "재정의"합니다.

더 이상 로컬 재정의가 없고 부모 도형에서 스타일을 상속하도록 UpdateTextStyleRequest를 사용하여 자식 도형의 텍스트 스타일 설정을 해제할 수 있습니다. 또한 부모로부터 상속한 값과 일치하도록 자식의 텍스트 스타일을 업데이트하면 해당 스타일이 암시적으로 설정 해제되고 상속된 값이 사용됩니다.

이는 업데이트 직후에 텍스트의 시각적 모양에 영향을 미치지 않지만, 부모 자리표시자의 단락 또는 텍스트 스타일을 나중에 업데이트하는 경우 문제가 될 수 있습니다. 이 상속 동작은 Slides 편집기의 동작과 일치하므로, API에 악영향을 미치지 않도록 미리 스타일 변경 결과를 확인할 수 있습니다.

예시

ChildPlaceholderParentPlaceholder에 대한 이전 예시의 정의를 고려합니다.

다음 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가 글머리 기호 글리프의 텍스트 스타일을 일치하도록 업데이트합니다.

글머리 기호 글리프 텍스트 스타일은 일반 텍스트 스타일과 약간 다른 상속 계층을 따릅니다.

  1. 특정 중첩 수준의 글머리 기호는 먼저 글머리 기호의 List 객체 내에 있는 NestingLevel.bullet_style 필드의 TextStyle 집합에서 상속합니다.
  2. 그 다음으로 부모 자리표시자의 List에 있는 해당 NestingLevel.bullet_style에서 상속합니다.
  3. 마지막으로, 나머지 부모 자리표시자 객체에서 상속하려고 시도합니다.

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

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