Struktura tekstu i jego styl

W interfejsie Prezentacji API tekst może znajdować się w kształtach i komórkach tabeli. Zanim zaczniesz modyfikować tekst i zmieniać jego styl, musisz poznać jego strukturę i styl.

Na tej stronie opisaliśmy, jak tekst jest prezentowany w interfejsie Prezentacji API.

Sekwencje elementów tekstu

Tekst w kształtie lub komórce tabeli składa się z sekwencji struktur TextElement. Ta sekwencja reprezentuje strukturę tekstu w kolejności, w jakiej występuje od początku do końca.

Przyjrzyjmy się na przykład zawartości tego slajdu – wszystkiej zawartej w jednym polu tekstowym:

Na powyższym slajdzie znajduje się jedno pole tekstowe, którego pole text zawiera sekwencję elementów tekstowych, tak jak na tym diagramie:

Mówiąc bardziej szczegółowo, ta sekwencja tekstu jest reprezentowana w interfejsie Prezentacji API w ten sposób:

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

Zawartość elementu TextElement

Każdy element tekstowy zawiera liczony od zera indeks początkowy i indeks końcowy, które opisują lokalizację elementu w pełnym tekście elementu strony, wraz z jednym z tych typów obiektu tekstowego:

Rodzaj tekstu	Opis
ParagraphMarker	Ten element tekstowy reprezentuje początek nowego akapitu. Indeks początkowy i końcowy elementu tekstowego reprezentuje cały fragment akapitu, w tym znak nowego wiersza, który kończy akapit. Akapit nigdy nie nachodzi na drugi. Akapit zawsze kończy się znakiem nowego wiersza, dlatego na końcu treści kształtu lub komórki tabeli zawsze jest znak nowego wiersza. Akapity mogą należeć do list punktowanych lub numerowanych. Jeśli tak jest, zawartość pola ParagraphMarker.bullet będzie zawierać identyfikator listy. Ten identyfikator odwołuje się do elementu listy, który istnieje w elemencie TextContent razem z sekwencją TextElement. Akapit na tej samej liście logicznej będzie odwoływać się do tego samego identyfikatora listy.
TextRun	Ten element tekstowy jest ciągłym ciągiem znaków o tym samym stylu. Tekst nigdy nie przekracza granic akapitów. Nawet jeśli tekst, który kończy się jednym akapitem, ma taki sam styl jak tekst rozpoczynający się od następnego akapitu, treść jest dzielona po znaku nowego wiersza, aby utworzyć oddzielny tekst. Jeśli chcesz przetworzyć pełny ciąg tekstowy w elemencie strony, powtórz wszystkie elementy tekstowe, łącząc ze sobą ciągi znaków występujące we wszystkich tekstach.
AutoText	Autotekst odnosi się do miejsc w tekście, które zmieniają się dynamicznie w zależności od kontekstu. W Prezentacjach oznacza to numer bieżącego slajdu w tekście.

W przyszłości interfejs Prezentacji Google może uwzględniać więcej rodzajów elementów tekstowych. Kod przetwarzający tekst powinien z łatwością radzić sobie z nowymi rodzajami elementów tekstowych, zazwyczaj poprzez ignorowanie nieznanych rodzajów.

modyfikowanie treści tekstu,

Jeśli chcesz zmodyfikować tekst za pomocą interfejsu Prezentacji API, nie musisz tworzyć bezpośrednio wszystkich odpowiednich elementów tekstowych. Zamiast tego możesz pracować na tekście tak samo jak w edytorze Prezentacji: wstawiać tekst, usuwać zakresy i aktualizować style w zakresach. Te operacje pośrednio tworzą elementy ParagraphMarker i TextRun w razie potrzeby, aby odzwierciedlić zmiany.

Wstawianie tekstu

Tekst w indeksie możesz wstawić w indeksie za pomocą żądania InsertTextRequest w wywołaniu funkcji batchUpdate. Pole insertionIndex tej metody określa, gdzie należy wstawić tekst. Indeks możesz obliczyć, korzystając z pól indeksu początkowego i końcowego wewnątrz elementów tekstowych.

Wstawianie tekstu ma pewne efekty uboczne, które powielają działanie edytora Prezentacji:

• Wstawienie znaku nowego wiersza powoduje domyślne utworzenie nowego akapitu, w wyniku czego zostanie utworzony element tekstowy ParagraphMarker, który rozpoczyna się w indeksie nowego wiersza i kończy na kolejnym wierszu. Styl akapitu – w tym szczegóły listy punktowanej i listy – zostanie skopiowany z bieżącego akapitu do nowego akapitu.
• Styl wstawianych znaków jest określany automatycznie, zazwyczaj zachowując styl używany w indeksie wstawiania. W rezultacie tekst jest zazwyczaj wstawiany do istniejącego indeksu TextRun w tym indeksie. Ten styl możesz później zaktualizować za pomocą żądania UpdateTextStyle.

Usuwam tekst

Możesz usunąć zakres tekstu, używając komunikatu DeleteTextRequest w wywołaniu funkcji batchUpdate. Usunięcie tekstu wiąże się z kilkoma subtelami:

• Usunięcie, które przekracza granicę akapitu, powoduje scalenie dwóch akapitów i usunięcie rozdzielającego elementu tekstowego ParagraphMarker.
• Nowy scalony akapit będzie korzystać z połączonego stylu akapitu, tak aby działał jak w edytorze Prezentacji.
• Usunięcie, którego zakres obejmuje uruchomienie tekstu, usuwa wszystkie treści z uruchomienia tekstu oraz samo uruchomienie tekstu.
• Usunięcie, którego zakres obejmuje element AutoText, powoduje usunięcie elementu AutoText.

Aktualizuję styl tekstu

Wygląd wyrenderowanego tekstu na slajdzie zależy od właściwości stylu tekstu:

• Style akapitu, takie jak wcięcie, wyrównanie i glify punktorów, są definiowane za pomocą właściwości znaczników akapitu.
• Style znaków, takie jak pogrubienie, kursywa i podkreślenie, są definiowane przez właściwości przy poszczególnych uruchomieniach tekstu.

Aktualizuję styl znaków

Style znaków możesz aktualizować za pomocą komunikatu UpdateTextStyleRequest w wywołaniu funkcji batchUpdate.

Podobnie jak w przypadku innych operacji na tekście, styl znaków jest stosowany do zakresu tekstu i w razie potrzeby tworzy nowe obiekty TextRun.

Ustawienie niektórych stylów znaków pośrednio aktualizuje pozostałe powiązane style, aby pasowały do działania w edytorze Prezentacji. Na przykład dodanie linku automatycznie zmienia kolor tekstu na pierwszym planie i właściwości podkreślenia. Więcej informacji znajdziesz w dokumentacji referencyjnej TextStyle.

Aktualizuję styl akapitu

Style akapitu możesz zmienić za pomocą komunikatu UpdateParagraphStyleRequest w wywołaniu funkcji batchUpdate.

Interfejs Prezentacji Google obsługuje żądanie CreateParagraphBulletsRequest, który odzwierciedla funkcjonalność gotowych ustawień punktorów w edytorze Prezentacji, umożliwiając tworzenie list punktowanych i numerowanych. Podobnie DeleteParagraphBulletsRequest powoduje usunięcie wszystkich punktorów w akapitach.

Style dziedziczone

Niektóre kształty, określane jako placeholders, mogą dziedziczyć style tekstu od innych kształtów nadrzędnych. Więcej informacji o dziedziczeniu kształtów znajdziesz w opisie placeholders.

Ta sekcja dotyczy sposobu, w jaki działa dziedziczenie stylów, aby tworzyć ostateczne, renderowane style tekstu wyświetlane na slajdzie.

Reprezentowanie stylów w obiektach zastępczych

W sekcji poświęconej placeholders opisujemy, jak działa dziedziczenie między kształtami nadrzędnymi i podrzędnymi. Dziedziczenie stylów tekstowych jest obsługiwane przez dodatkowe funkcje w modelu dziedziczenia:

• Właściwości elementów tekstowych ParagraphMaker definiują formatowanie akapitu.
• Formatowanie znaków zależy od właściwości elementów tekstowych TextRun.
• Zawartość nadrzędnych obiektów zastępczych zawiera 8 takich par ParagraphMarker/TextRun (obsługuje 8 poziomów zagnieżdżania list).
• Podrzędny symbol zastępczy dziedziczy domyślne właściwości tekstu z tych elementów w zawartości tekstowej elementu nadrzędnego.

Na diagramie poniżej widać jeden ze sposobów wizualizacji tych relacji:

Pierwszy akapit ParagraphMarker/TextRun w kształcie nadrzędnym określa większość dziedziczonych stylów tekstu. Styl w pozostałych 7 parach ma wpływ tylko na akapity na coraz głęboko zagnieżdżonych poziomach punktorów:

Para elementów tekstowych nadrzędnych	Formatowanie podrzędne, które kontroluje
Pierwsze ParagraphMarker pierwsze TextRun	Styl tekstu w akapitach listy na poziomie 0 (najbardziej wysuniętym) i wszystkich akapitach spoza listy.
Drugie ParagraphMarker drugi TextRun	Styl tekstu na pozostałych (zagnieżdżonych) poziomach listy 1–7
Trzecia ParagraphMarker Trzecia TextRun
Czwarty ParagraphMarker czwarty (TextRun)
Piąty(a) ParagraphMarker 5. TextRun
Szósty ParagraphMarker 6. TextRun
Siódma ParagraphMarker 7. TextRun
Ósma ParagraphMarker Ósma TextRun

Aby uzyskać dostęp do tych par elementów tekstowych, użyj ich bezpośredniego indeksu w polu textElements, tak jak we fragmencie kodu poniżej. Pokazuje to ustawienie domyślnego (dziedziczonego) stylu dla akapitów na poziomie 0 i innych niż listy:

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

Pamiętaj, że pole content elementu TextRun kształtu nadrzędnego zawsze zawiera jeden znak nowego wiersza.

Style dziedziczone można zastąpić

Kształt podrzędny może określać właściwości stylu w elementach ParagraphMarker i TextRun w jego treści. Te właściwości określone lokalnie zastąpią wszystkie usługi dziedziczone w ich zakresie lokalnym. Elementy, które nie mają określonego stylu, będą używać odpowiedniego stylu odziedziczonego z elementu nadrzędnego.

Usunięcie wyraźnej właściwości stylu z kształtu podrzędnego, przez co nie jest ona już ustawiona, spowoduje, że będzie ona dziedziczyć kształt z elementu nadrzędnego.

Przykład

Biorąc pod uwagę dziedziczenie przedstawione na powyższym diagramie, załóżmy, że kształt ParentPlaceholder ma taką treść tekstową:

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

A załóżmy, że kształt ChildPlaceholder zawiera następującą treść tekstową:

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

Efektem będą wyniki opisane w kolejnych akapitach.

Dziedziczenie stylu zwykłego akapitu

Pierwszy akapit kształtu podrzędnego, który zawiera tekst „To mój pierwszy akapit”, jest zwykłym akapitem (nie jest listą). Żaden element w treści tekstowej nie określa żadnych właściwości stylu, więc elementy te dziedziczą wszystkie style znaków i akapitów ze swoich elementów nadrzędnych. Powoduje to takie renderowanie:

• Tekst: „To mój pierwszy akapit” jest renderowany. Sam tekst nigdy nie jest dziedziczony.
• Wyrównanie: tekst jest renderowany z wyrównaniem START odziedziczonym z pierwszego elementu ParagraphMarker elementu nadrzędnego.
• Kolor pierwszego planu: tekst jest renderowany przy użyciu koloru pierwszego planu DARK1, który jest dziedziczony z pierwszego elementu (TextRun) elementu nadrzędnego.

Dziedziczenie stylu w akapicie listy

Następny akapit, który zawiera tekst „Ten akapit znajduje się na liście”, znajduje się na liście punktowanej na pierwszym poziomie zagnieżdżenia, ponieważ odpowiadające mu pole bullet w wierszu ParagraphMarker jest ustawione na tym poziomie. W efekcie dziedziczy styl tekstu i akapitu z pierwszego poziomu zagnieżdżenia w elemencie nadrzędnym. Efektem jest renderowanie w ten sposób:

• Tekst: „Ten akapit znajduje się na liście” to tekst wyrenderowany. Sam tekst nigdy nie jest dziedziczony.
• Wyrównanie: tekst jest renderowany z wyrównaniem „END” (dziedziczone z drugiego ParagraphMarker elementu nadrzędnego).
• Kolor pierwszego planu: tekst jest renderowany przy użyciu koloru pierwszego planu (LIGHT1), który jest dziedziczony z drugiego elementu (TextRun) elementu nadrzędnego.

Interakcje między aktualizowaniem i dziedziczeniem stylów tekstu i akapitów

Style tekstu, które nie są ustawione w kształcie podrzędnym, dziedziczą wartości z elementu nadrzędnego. W niektórych zakresie lokalnym style tekstu ustawione w elemencie podrzędnym „zastąpią” wartości nadrzędne.

Za pomocą UpdateTextStyleRequest możesz anulować ustawienie stylu tekstowego kształtu podrzędnego, aby nie miało on już zastąpienia, odziedziczyłby jego sylety z kształtu nadrzędnego. Poza tym zaktualizowanie stylu tekstu podrzędnego, aby pasował do wartości odziedziczonej z elementu nadrzędnego, powoduje domyślnie cofanie stylu i korzysta z wartości odziedziczonej.

Ustawienie stylu kształtu podrzędnego na taki sam jak jego nadrzędnego (co powoduje dziedziczenie stylu) daje taki sam skutek jak usunięcie ustawienia stylu kształtu podrzędnego.

Nie ma to wpływu na wygląd tekstu zaraz po aktualizacji, ale może mieć znaczenie, jeśli później zaktualizujesz styl akapitu lub tekstu w nadrzędnej zmiennej. To dziedziczenie jest zgodne z działaniem edytora Prezentacji, więc możesz eksperymentować z wynikami zmian stylu przed rozpoczęciem pracy z interfejsem API.

Przykład

Przeanalizuj definicje z poprzedniego przykładu dotyczące właściwości ChildPlaceholder i ParentPlaceholder.

Teraz załóżmy, że przesyłasz to polecenie UpdateTextStyleRequest:

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

To żądanie ma na celu ustawienie parametru DARK1pierwszy planColor na cały tekst obiektu ChildPlaceholder. Przy użyciu maski pola można określić, że zmienia się tylko kolor pierwszego planu elementu. Rezultatem prośby:

• Pierwszy akapit: nowy styl foregroundColor odpowiada odziedziczonemu stylowi foregroundColor, więc ten styl nie ma wpływu na jego dziedziczenie.
• Drugi akapit: nowy akapit foregroundColor nie jest zgodny z odziedziczonym foregroundColor, dlatego kolor pierwszego akapitu zostanie zmieniony na DARK1.

Obecna zawartość tekstowa obiektu 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"} }, },
        ...
      }
    }
  ]
}

Styl tekstu glifu w punktach

Podobnie jak zwykły tekst, glify punktorów mają styl, który określa sposób renderowania glifu. Tych stylów tekstu nie można modyfikować bezpośrednio za pomocą interfejsu Prezentacji API. Jeśli jednak użyjesz UpdateTextStyleRequest, aby zaktualizować cały akapit zawierający punktor, interfejs Prezentacji API zaktualizuje do tego styl tekstu glifu.

Style tekstu glifów w punktach mają nieco inną hierarchię dziedziczenia niż zwykłe style tekstu.

1. Punktor na określonym poziomie zagnieżdżenia najpierw dziedziczy wartość z pola TextStyle ustawionego w polu NestingLevel.bullet_style w obiekcie List punktu.
2. Następnie dziedziczy element NestingLevel.bullet_style w elemencie List swojego nadrzędnego obiektu zastępczego.
3. Na koniec wykonuje dziedziczenie z pozostałych nadrzędnych obiektów zastępczych.

Punkty w obiektach zastępczych w szablonach Układów i Nadrzędnych mają puste pole „TextStyle” w polu „ParagraphMarker.bullet”. Wszelkie zmiany stylu tekstu w tych akapitach zostaną odzwierciedlone tylko w wiadomościach „List”.