Textstruktur und -stil

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

In der Google Präsentationen API kann Text in Formen oder in Tabellenzellen enthalten sein. Bevor Sie Text bearbeiten und formatieren können, müssen Sie seine Struktur und die Funktionsweise von Formatierungen verstehen.

Auf dieser Seite wird beschrieben, wie Text in der Google Präsentationen API dargestellt wird.

Sequenzen von Textelementen

Der Text in einer Form oder Tabellenzelle besteht aus einer Sequenz von TextElement-Strukturen. Diese Sequenz stellt die Struktur des Textes in der Reihenfolge dar, in der er von Anfang bis Ende erscheint.

Sehen wir uns beispielsweise den Inhalt dieser Folie an, der sich in einem einzigen Textfeld befindet:

Die obige Folie enthält ein Textfeld, dessen text-Feld eine Sequenz von Textelementen enthält, wie im folgenden Diagramm dargestellt:

Konkret wird diese Textsequenz in der Google Präsentationen API so dargestellt:

"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-Inhalte

Jedes Textelement enthält einen nullbasierten Startindex und einen Endindex, die die Position des Elements im vollständigen Text des Seitenelements beschreiben, sowie einen der folgenden Textobjekttypen:

Textinhalte ändern

Wenn Sie Text mit der Google Präsentationen API ändern möchten, müssen Sie nicht alle entsprechenden Textelemente explizit erstellen. Stattdessen können Sie Text wie im Editor von Google Präsentationen bearbeiten: Text einfügen, Bereiche löschen und Stile für Bereiche aktualisieren. Bei diesen Vorgängen werden nach Bedarf ParagraphMarker- und TextRun-Elemente erstellt, um Ihre Änderungen widerzuspiegeln.

Text einfügen

Sie können Text an einem Index einfügen, indem Sie die InsertTextRequest-Anfrage in einen batchUpdate-Aufruf einfügen. Im Feld insertionIndex dieser Methode wird angegeben, wo der Text eingefügt werden soll. Sie können diesen Index mithilfe der Start- und Endindexfelder in Textelementen berechnen.

Das Einfügen von Text hat einige Nebenwirkungen, die dem Verhalten des Google Präsentationen-Editors entsprechen:

• Wenn Sie ein Zeilenumbruchzeichen einfügen, wird implizit ein neuer Absatz erstellt. Dabei wird ein ParagraphMarker-Textelement erstellt, das am Index des Zeilenumbruchs beginnt und am nächsten Zeilenumbruch endet. Der Absatzstil, einschließlich Aufzählungszeichen und Listendetails, wird aus dem aktuellen Absatz in den neuen Absatz kopiert.
• Der Stil der eingefügten Zeichen wird automatisch bestimmt. In der Regel wird der Textstil beibehalten, der am Einfügeindex vorhanden war. Daher wird der Text in der Regel an dieser Stelle in die vorhandene TextRun eingefügt. Sie können diesen Stil später mit einer UpdateTextStyle-Anfrage aktualisieren.

Text löschen

Sie können einen Textbereich mit der Nachricht DeleteTextRequest in einem Aufruf von batchUpdate löschen. Beim Löschen von Text gibt es einige Feinheiten:

• Wenn Sie Text löschen, der eine Absatzgrenze überschreitet, werden die beiden Absätze zusammengeführt und das trennende Textelement ParagraphMarker wird gelöscht.
• Für den neuen zusammengeführten Absatz wird ein kombinierter Absatzstil verwendet, der dem Verhalten im Editor von Google Präsentationen entspricht.
• Wenn Sie einen Bereich löschen, der einen Textabsatz umfasst, werden der gesamte Inhalt des Textabsatzes und der Textabsatz selbst gelöscht.
• Wenn ein Löschvorgang einen Bereich umfasst, der ein AutoText-Element enthält, wird das AutoText-Element gelöscht.

Textstil aktualisieren

Das Aussehen von Text auf einer Folie wird durch die Eigenschaften des Textstils bestimmt:

• Absatzstile wie Einzug, Ausrichtung und Aufzählungszeichen werden durch Eigenschaften von Absatzmarkierungen definiert.
• Zeichenstile wie Fettdruck, Kursivschrift und Unterstreichung werden durch Eigenschaften für einzelne Textabsätze definiert.

Schriftstil aktualisieren

Sie können Zeichenstile mit der Nachricht UpdateTextStyleRequest in einem Aufruf von batchUpdate aktualisieren.

Wie bei anderen Textoperationen wird der Zeichenstil auf einen Textbereich angewendet und es werden bei Bedarf implizit neue TextRun-Objekte erstellt.

Wenn Sie einige Zeichenstile festlegen, werden andere zugehörige Stile implizit aktualisiert, damit sie dem Verhalten im Editor von Google Präsentationen entsprechen. Wenn Sie beispielsweise einen Link hinzufügen, werden automatisch die Text-Vordergrundfarbe und die Unterstricheigenschaften geändert. Weitere Informationen finden Sie in der Referenzdokumentation zu TextStyle.

Absatzstil aktualisieren

Sie können Absatzstile mit der Nachricht UpdateParagraphStyleRequest in einem Aufruf von batchUpdate aktualisieren.

Die Google Präsentationen API unterstützt die Funktion CreateParagraphBulletsRequest, die die Funktion der Aufzählungsvorlagen im Editor von Google Präsentationen zum Erstellen von Aufzählungs- und nummerierten Listen widerspiegelt. Ebenso werden mit DeleteParagraphBulletsRequest alle vorhandenen Aufzählungspunkte in Absätzen entfernt.

Übernommene Stile

Einige Formen, sogenannte Platzhalter, können Textstile von anderen übergeordneten Formen übernehmen. Weitere Informationen zur Formübernahme im Allgemeinen finden Sie unter Platzhalter.

In diesem Abschnitt geht es darum, wie die Stilübernahme funktioniert, um die endgültigen, gerenderten Textstile zu erstellen, die auf einer Folie angezeigt werden.

Stildarstellung in Platzhaltern

Im Abschnitt zu Platzhaltern wird beschrieben, wie die Überschreibung zwischen übergeordneten und untergeordneten Formen funktioniert. Die Übernahme von Textstilen wird durch zusätzliche Funktionen im Vererbungsmodell gesteuert:

• Die Eigenschaften von Textelementen vom Typ ParagraphMaker definieren die Absatzformatierung.
• Die Eigenschaften von Textelementen vom Typ TextRun definieren die Zeichenformatierung.
• Der Inhalt der übergeordneten Platzhalter enthält acht solcher Paare aus ParagraphMarker und TextRun, um acht Listenebenen zu unterstützen.
• Die Standardtexteigenschaften eines untergeordneten Platzhalters werden von diesen Textelementen im Textinhalt des übergeordneten Elements übernommen.

Das folgende Diagramm zeigt eine Möglichkeit, diese Beziehungen zu visualisieren:

Der erste ParagraphMarker/TextRun in der übergeordneten Form bestimmt den Großteil des übernommenen Textstils. Das Format der verbleibenden sieben Paare wirkt sich nur auf Absätze auf zunehmend verschachtelten Aufzählungsebenen aus:

Um auf diese Textelementpaare zuzugreifen, verwenden Sie ihren expliziten Index im Feld textElements, wie im folgenden Snippet gezeigt. Hier wird die Standardformatierung (vererbbar) für Paragrafen der Ebene 0 und nicht für Listen festgelegt:

"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"  }  },  }
     }
   },{
     ...
   } ]
 }

Das Feld content des TextRun einer übergeordneten Form besteht immer aus einem einzelnen Zeilenumbruchzeichen.

Übernommene Stile können überschrieben werden

Für eine untergeordnete Form können Stileigenschaften für die Elemente ParagraphMarker und TextRun im Inhalt angegeben werden. Diese lokal angegebenen Properties überschreiben alle übernommenen Properties in ihrem lokalen Gültigkeitsbereich. Für Elemente, für die kein Stil angegeben ist, wird der entsprechende Stil verwendet, der von der übergeordneten Instanz übernommen wurde.

Wenn Sie eine explizite Stileigenschaft aus einer untergeordneten Form entfernen, sodass sie nicht mehr festgelegt ist, wird sie vom übergeordneten Element übernommen.

Beispiel

Angenommen, die im Diagramm oben dargestellte Vererbung gilt und die Form ParentPlaceholder hat den folgenden Textinhalt:

"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"} }, ...}
      }
    },
   ...
  ]
}

Angenommen, die Form ChildPlaceholder hat den folgenden Textinhalt:

"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": {},
        ...
      }
    }
  ]
}

Dies führt zu den in den folgenden Abschnitten beschriebenen Ergebnissen.

Stilübernahme für einen einfachen Absatz

Der erste Absatz der untergeordneten Form, der den Text „Das ist mein erster Absatz“ enthält, ist ein einfacher Absatz (nicht in einer Liste). Für keines der Elemente im Textinhalt sind Stileigenschaften angegeben. Daher werden alle Zeichen- und Absatzstile vom übergeordneten Element übernommen. Das führt zu folgendem Rendering:

• Text: „Das ist mein erster Absatz“ ist der gerenderte Text. Text wird nie übernommen.
• Ausrichtung: Der Text wird mit der Ausrichtung START gerendert, die vom ersten ParagraphMarker des übergeordneten Elements übernommen wird.
• Vordergrundfarbe: Der Text wird mit der DARK1-Vordergrundfarbe gerendert, die vom ersten TextRun des übergeordneten Elements übernommen wird.

Stilübernahme für einen Listenabsatz

Der nächste Absatz, der den Text „Dieser Absatz ist in einer Liste“ enthält, befindet sich in einer Aufzählungsliste auf Verschachtelungsebene 1, da das Feld bullet des entsprechenden ParagraphMarker auf diese Ebene gesetzt ist. Daher werden Text und Absatzstil von der Verschachtelungsebene 1 im übergeordneten Element übernommen. Das führt zu folgendem Rendering:

• Text: „Dieser Absatz ist in einer Liste“ ist der gerenderte Text. Text wird nie übernommen.
• Ausrichtung: Der Text wird mit der Ausrichtung „END“ gerendert, die vom zweiten ParagraphMarker des übergeordneten Elements übernommen wurde.
• Vordergrundfarbe: Der Text wird mit der Text-Vorgrundfarbe LIGHT1 gerendert, die vom zweiten TextRun des übergeordneten Elements übernommen wird.

Interaktionen zwischen Aktualisieren und Übernehmen von Text- und Absatzstilen

Textstile, die nicht in einer untergeordneten Form festgelegt sind, übernehmen die Werte des übergeordneten Elements. Textstile, die im untergeordneten Element festgelegt sind, überschreiben die übergeordneten Werte in einem lokalen Gültigkeitsbereich.

Mit einer UpdateTextStyleRequest können Sie den Textstil einer untergeordneten Form zurücksetzen, sodass sie keine lokale Überschreibung mehr hat und die Stile von der übergeordneten Form übernimmt. Wenn Sie den Textstil des untergeordneten Elements so aktualisieren, dass er mit dem Wert übereinstimmt, der von einem übergeordneten Element übernommen wurde, wird der Stil implizit aufgehoben, sodass der übernommene Wert verwendet wird.

Das hat zwar keinen Einfluss auf das visuelle Erscheinungsbild von Text direkt nach einer Aktualisierung, kann aber wichtig sein, wenn Sie später einen Absatz oder Textstil in einem übergeordneten Platzhalter aktualisieren. Dieses Vererbungsverhalten entspricht dem Verhalten des Google Präsentationen-Editors. So können Sie die Auswirkungen von Stiländerungen ausprobieren, bevor Sie mit der API arbeiten.

Beispiel

Sehen Sie sich die Definitionen für ChildPlaceholder und ParentPlaceholder im vorherigen Beispiel an.

Angenommen, Sie reichen diese UpdateTextStyleRequest ein:

{ "updateTextStyle": {
    "objectId": "ChildPlaceholder",
    "style": {"foregroundColor": {"opaqueColor": {"themeColor": "DARK1"} }, },
    "textRange": { "type": "ALL" },
    "fields": "foregroundColor"
  }
}

Bei dieser Anfrage wird versucht, dem gesamten Text von „ChildPlaceholder“ die Vordergrundfarbe DARK1 zuzuweisen. Dabei wird mithilfe einer Feldmaske angegeben, dass sich nur die Vordergrundfarbe des Elements ändern soll. Diese Anfrage hat folgende Auswirkungen:

• Erster Absatz: Der neue foregroundColor stimmt mit dem übernommenen foregroundColor überein. Dieser Stil bleibt also unverändert und wird weiterhin übernommen.
• Zweiter Absatz: Da die neue foregroundColor nicht mit der übernommenen foregroundColor übereinstimmt, wird die Vordergrundfarbe des zweiten Absatzes auf DARK1 aktualisiert.

Der Textinhalt von „ChildPlaceholder“ ist jetzt:

"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"} }, },
        ...
      }
    }
  ]
}

Textstil für Aufzählungszeichen

Wie bei normalem Text haben auch Aufzählungszeichen einen Textstil, der die Darstellung des Zeichens steuert. Diese Textstile können nicht direkt über die Google Präsentationen API geändert werden. Wenn Sie jedoch mit einer UpdateTextStyleRequest einen ganzen Absatz mit einem Aufzählungspunkt aktualisieren, aktualisiert die Google Präsentationen API den Textstil des Aufzählungszeichens entsprechend.

Textstile für Aufzählungszeichen folgen einer etwas anderen Vererbungshierarchie als normale Textstile.

1. Ein Aufzählungspunkt auf einer bestimmten Verschachtelungsebene erbt zuerst von den TextStyle-Elementen, die im Feld NestingLevel.bullet_style im List-Objekt des Aufzählungspunkts festgelegt sind.
2. Anschließend wird es von der entsprechenden NestingLevel.bullet_style in List des übergeordneten Platzhalters übernommen.
3. Schließlich wird versucht, von den verbleibenden übergeordneten Platzhalterobjekten zu übernehmen.