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. |
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 elementuAutoText
.
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 elementuParagraphMarker
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.
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 DARK1
pierwszy 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 stylowiforegroundColor
, więc ten styl nie ma wpływu na jego dziedziczenie. - Drugi akapit: nowy akapit
foregroundColor
nie jest zgodny z odziedziczonymforegroundColor
, dlatego kolor pierwszego akapitu zostanie zmieniony naDARK1
.
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.
- Punktor na określonym poziomie zagnieżdżenia najpierw dziedziczy wartość z pola
TextStyle
ustawionego w poluNestingLevel.bullet_style
w obiekcieList
punktu. - Następnie dziedziczy element
NestingLevel.bullet_style
w elemencieList
swojego nadrzędnego obiektu zastępczego. - Na koniec wykonuje dziedziczenie z pozostałych nadrzędnych obiektów zastępczych.