Di Slides API, teks dapat dimuat dalam bentuk atau sel tabel. Sebelum dapat memanipulasi dan menata gaya teks, Anda harus memahami strukturnya dan cara kerja penataan gaya.
Halaman ini menjelaskan cara teks direpresentasikan di Slides API.
Urutan elemen teks
Teks yang dimuat dalam bentuk atau sel tabel terdiri dari urutan struktur TextElement. Urutan ini mewakili struktur teks, dalam urutan teks muncul dari awal hingga akhir.
Misalnya, pertimbangkan isi slide ini—semuanya terdapat dalam satu kotak teks:
Slide di atas memiliki satu kotak teks, yang kolom text
-nya berisi urutan
elemen teks seperti yang ditunjukkan dalam diagram berikut:
Lebih jelasnya, urutan teks ini direpresentasikan di Slides API sebagai berikut:
"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": {} }
}]
Konten TextElement
Setiap elemen teks berisi indeks awal dan indeks akhir berbasis nol, yang menjelaskan lokasi elemen di dalam teks lengkap elemen halaman, bersama dengan salah satu jenis objek teks berikut:
Jenis teks | Deskripsi |
---|---|
ParagraphMarker | Elemen teks ini mewakili awal paragraf baru. Indeks awal dan akhir elemen teks merepresentasikan rentang penuh paragraf, termasuk karakter baris baru yang mengakhiri paragraf. Paragraf tidak pernah tumpang tindih dengan paragraf lain. Paragraf selalu berakhir dengan karakter baris baru, sehingga selalu ada baris baru di akhir konten teks dalam bentuk atau sel tabel. Paragraf dapat menjadi bagian dari daftar berbutir atau bernomor. Jika demikian, konten kolom ParagraphMarker.bullet akan menyertakan ID daftar. ID ini mereferensikan elemen daftar yang ada di dalam TextContent bersama dengan urutan TextElement . Paragraf dalam daftar logis yang sama akan merujuk ke ID daftar yang sama. |
TextRun | Elemen teks ini mewakili string teks yang bersebelahan karena semuanya memiliki gaya teks yang sama. Aliran teks tidak pernah melewati batas paragraf: meskipun teks yang mengakhiri satu paragraf memiliki gaya yang sama seperti teks yang memulai paragraf berikutnya, konten akan dipisahkan setelah karakter baris baru untuk membentuk teks terpisah yang berjalan. Jika Anda perlu memproses string teks lengkap di dalam elemen halaman, lakukan iterasi pada semua elemen teks, dengan menggabungkan string yang ditemukan di semua teks yang berjalan. |
AutoText | Teks otomatis mengacu pada tempat dalam teks yang berubah secara dinamis tergantung pada konteksnya. Pada Slide, ini digunakan untuk menyatakan nomor slide saat ini di dalam teks. |
Mengubah konten teks
Jika perlu mengubah teks menggunakan Slides API, Anda tidak harus secara eksplisit
membuat semua elemen teks yang sesuai. Sebagai gantinya, Anda dapat beroperasi pada teks
seperti yang Anda lakukan di editor Slide: dengan menyisipkan teks, menghapus rentang, dan
memperbarui gaya pada rentang. Operasi ini secara implisit membuat elemen ParagraphMarker
dan TextRun
sesuai kebutuhan untuk mencerminkan perubahan Anda.
Menyisipkan teks
Anda dapat menyisipkan teks di sebuah indeks menggunakan permintaan InsertTextRequest dalam panggilan ke batchUpdate. Kolom insertionIndex
pada metode ini menentukan tempat untuk menyisipkan teks; Anda dapat menghitung indeks ini menggunakan kolom indeks awal dan akhir di dalam elemen teks.
Penyisipan teks memiliki beberapa efek samping yang mencerminkan perilaku editor Slide:
- Menyisipkan karakter baris baru secara implisit akan membuat paragraf baru,
sehingga membuat elemen teks
ParagraphMarker
yang dimulai pada indeks baris baru dan berakhir di baris baru berikutnya. Gaya paragraf—termasuk detail butir dan daftar—disalin dari paragraf saat ini ke paragraf baru. - Gaya karakter yang disisipkan ditentukan secara otomatis, umumnya
mempertahankan gaya teks sama yang ada di indeks penyisipan. Akibatnya,
teks umumnya disisipkan ke dalam
TextRun
yang ada pada indeks tersebut. Anda dapat memperbarui gaya ini nanti menggunakan permintaan UpdateTextStyle.
Menghapus teks
Anda dapat menghapus rentang teks menggunakan pesan DeleteTextRequest dalam sebuah panggilan ke batchUpdate. Menghapus teks memerlukan beberapa detail:
- Penghapusan yang melewati batas paragraf akan menggabungkan dua paragraf,
sehingga menghapus elemen teks
ParagraphMarker
yang memisahkan. - Paragraf gabungan baru akan menggunakan gaya paragraf gabungan, yang sesuai dengan perilaku di editor Slide.
- Penghapusan yang rentangnya mencakup run teks akan menghapus semua konten dari proses teks, dan juga menghapus teks yang berjalan itu sendiri.
- Penghapusan yang rentangnya meliputi elemen
AutoText
akan menghapus elemenAutoText
.
Memperbarui gaya teks
Tampilan teks yang dirender di slide ditentukan oleh properti gaya teks:
- Gaya paragraf seperti indentasi, perataan, dan bullet-glyph, ditentukan oleh properti pada penanda paragraf.
- Gaya karakter seperti tebal, miring, dan garis bawah, ditentukan oleh properti pada setiap teks yang dijalankan.
Memperbarui gaya karakter
Anda dapat memperbarui gaya karakter menggunakan pesan UpdateTextStyleRequest dalam panggilan ke batchUpdate.
Seperti operasi teks lainnya, gaya karakter diterapkan ke rentang
teks dan secara implisit membuat objek TextRun
baru sesuai kebutuhan.
Menyetel beberapa gaya karakter secara implisit akan memperbarui gaya terkait lainnya agar sesuai dengan perilaku di editor Slide. Misalnya, menambahkan link akan otomatis mengubah warna latar depan teks dan properti garis bawah. Lihat dokumentasi referensi TextStyle untuk mengetahui detail selengkapnya.
Memperbarui gaya paragraf
Anda dapat memperbarui gaya paragraf menggunakan pesan UpdateParagraphStyleRequest dalam panggilan ke batchUpdate.
Slides API mendukung CreateParagraphBulletsRequest yang mencerminkan fungsi preset butir di editor Slide untuk pembuatan daftar berbutir dan bernomor. Demikian pula, DeleteParagraphBulletsRequest akan menghapus semua butir yang ada pada paragraf.
Gaya yang diwarisi
Beberapa bentuk, yang dikenal sebagai placeholders, dapat mewarisi gaya teks dari yang lain, yaitu bentuk induk: lihat placeholders untuk mempelajari lebih lanjut pewarisan bentuk secara umum.
Bagian ini berfokus pada cara kerja pewarisan gaya untuk membuat gaya teks akhir yang dirender dan ditampilkan di slide.
Representasi gaya dalam placeholder
Bagian placeholders menjelaskan cara kerja pewarisan antara bentuk induk dan turunan. Pewarisan gaya teks ditangani oleh fitur tambahan dalam model pewarisan:
- Properti elemen teks ParagraphMaker menentukan pemformatan paragraf.
- Properti elemen teks TextRun menentukan pemformatan karakter.
- Konten placeholder induk berisi delapan pasangan ParagraphMarker/TextRun tersebut (untuk mendukung delapan tingkat penyusunan daftar).
- Placeholder turunan mewarisi properti teks defaultnya dari elemen teks ini di konten teks induknya.
Diagram berikut menunjukkan salah satu cara untuk memvisualisasikan hubungan ini:
ParagraphMarker/TextRun pertama dalam bentuk induk menentukan sebagian besar gaya teks yang diwarisi; gaya visual di tujuh pasangan sisanya hanya memengaruhi paragraf pada tingkat butir bertingkat yang makin dalam:
Pasangan elemen teks induk | Pemformatan turunan yang dikontrol |
---|---|
TextRun pertama ParagraphMarker pertama |
Gaya teks paragraf daftar tingkat 0 (terluar) dan semua paragraf non-daftar. |
Kedua ParagraphMarker Kedua TextRun |
Gaya teks dari daftar (bertingkat) level 1-7 yang tersisa |
Ketiga ParagraphMarker Ketiga TextRun |
|
Keempat ParagraphMarker Keempat TextRun |
|
TextRun kelima ParagraphMarker kelima |
|
Keenam ParagraphMarker keenam TextRun |
|
Ketujuh ParagraphMarker TextRun Ketujuh |
|
Kedelapan ParagraphMarker Kedelapan TextRun |
Untuk mengakses pasangan elemen teks ini, gunakan indeks eksplisitnya dalam kolom textElements
seperti ditunjukkan dalam cuplikan di bawah, yang menunjukkan setelan gaya default (dapat diwarisi) untuk paragraf level 0 dan non-daftar:
"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" } }, }
}
},{
...
} ]
}
Perhatikan bahwa kolom content
dari TextRun
bentuk induk selalu terdiri dari
satu karakter baris baru.
Gaya yang diwarisi dapat diganti
Bentuk turunan dapat menentukan properti gaya visual di elemen ParagraphMarker dan TextRun dalam kontennya. Properti yang ditentukan secara lokal ini akan menggantikan properti yang diwarisi dalam cakupan lokalnya. Elemen yang tidak menentukan gaya apa pun akan menggunakan gaya terkait yang diwarisi dari induk.
Menghapus properti gaya eksplisit dari bentuk turunan sehingga tidak lagi ditetapkan, akan menyebabkannya mewarisi dari induk.
Contoh
Berdasarkan pewarisan yang ditampilkan dalam diagram di atas, anggaplah bentuk
ParentPlaceholder
memiliki konten teks berikut:
"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"} }, ...}
}
},
...
]
}
Dan anggaplah ChildPlaceholder
bentuk memiliki konten teks berikut:
"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": {},
...
}
}
]
}
Hal ini menghasilkan hasil yang dijelaskan dalam paragraf berikut.
Pewarisan gaya untuk paragraf biasa
Paragraf pertama bentuk turunan, yang berisi teks "This is my first paragraph", adalah paragraf biasa (tidak ada dalam daftar). Tidak ada elemen dalam konten teksnya yang menentukan properti gaya, sehingga elemen tersebut mewarisi semua karakter dan gaya paragrafnya dari induknya. Hal ini menyebabkan rendering berikut:
- Teks: "This is my first paragraph" adalah teks yang dirender. Teks itu sendiri tidak pernah diwariskan.
- Perataan: Teks dirender dengan perataan
START
, yang diwarisi dariParagraphMarker
pertama induk. - Warna latar depan: Teks dirender dengan warna latar depan
DARK1
, diwarisi dariTextRun
pertama induk.
Pewarisan gaya untuk paragraf daftar
Paragraf berikutnya, yang berisi teks "This Paragraph is in a list", berada dalam
daftar berbutir di level bertingkat 1, karena ParagraphMarker
yang sesuai
memiliki kolom bullet
yang ditetapkan ke level ini. Akibatnya, metode ini mewarisi teks dan
gaya paragraf dari tingkat bertingkat 1 di induk. Hal ini menghasilkan
rendering berikut:
- Teks: "This paragraph is in a list" adalah teks yang dirender. Teks itu sendiri tidak pernah diwariskan.
- Perataan: Teks dirender dengan perataan "END", yang diwarisi dari
ParagraphMarker
kedua induk. - Warna latar depan: Teks dirender dengan warna latar depan teks
LIGHT1
, diwarisi dariTextRun
kedua induk.
Interaksi antara memperbarui dan mewarisi gaya teks dan paragraf
Gaya teks yang tidak disetel dalam bentuk turunan akan mewarisi nilai dari induknya. Gaya teks yang ditetapkan di turunan akan "mengganti" nilai induk di beberapa cakupan lokal.
Anda dapat menggunakan UpdateTextStyleRequest untuk membatalkan penetapan gaya teks bentuk turunan, sehingga tidak lagi memiliki penggantian lokal, sehingga mewarisi gayanya dari bentuk induk. Selain itu, mengupdate gaya teks turunan agar sama dengan nilai yang diwarisi dari induk secara implisit akan membatalkan setelan gaya sehingga gaya menggunakan nilai yang diwarisi.
Hal ini tidak memengaruhi tampilan visual teks secara langsung setelah pembaruan, tetapi mungkin menjadi masalah jika nantinya Anda memperbarui gaya teks atau paragraf di placeholder induk. Perilaku pewarisan ini sesuai dengan perilaku editor Slide, sehingga Anda dapat bereksperimen dengan hasil perubahan gaya sebelum menggunakan API.
Contoh
Pertimbangkan definisi di contoh sebelumnya untuk
ChildPlaceholder
dan ParentPlaceholder
.
Sekarang, misalnya Anda mengirimkan UpdateTextStyleRequest ini:
{ "updateTextStyle": {
"objectId": "ChildPlaceholder",
"style": {"foregroundColor": {"opaqueColor": {"themeColor": "DARK1"} }, },
"textRange": { "type": "ALL" },
"fields": "foregroundColor"
}
}
Permintaan ini mencoba menyetel latar depanColor DARK1
ke semua
teks ChildPlaceholder menggunakan mask kolom
untuk menentukan bahwa hanya warna latar depan elemen yang harus berubah. Permintaan
ini memiliki hasil berikut:
- Paragraf pertama:
foregroundColor
baru cocok denganforegroundColor
yang diwarisi, sehingga gaya ini tidak berubah dan masih diwarisi. - Paragraf kedua:
foregroundColor
yang baru tidak cocok denganforegroundColor
yang diwarisi sehingga warna latar depan paragraf kedua diperbarui menjadiDARK1
.
Konten teks ChildPlaceholder sekarang menjadi:
"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"} }, },
...
}
}
]
}
Gaya teks bullet-glyph
Seperti teks normal, bullet-glyph memiliki gaya teks yang mengontrol cara glyph dirender. Gaya teks ini tidak dapat dimodifikasi menggunakan Slides API secara langsung. Namun, jika Anda menggunakan UpdateTextStyleRequest untuk memperbarui paragraf lengkap yang menyertakan butir, Slides API akan memperbarui gaya teks bullet-glyph agar sesuai.
Gaya teks glyph butir mengikuti hierarki pewarisan yang sedikit berbeda dengan gaya teks normal.
- Butir pada tingkat hierarki tertentu terlebih dahulu mewarisi dari
TextStyle
yang ditetapkan dalam kolomNestingLevel.bullet_style
di dalam objekList
butir. - Selanjutnya, elemen ini mewarisi dari
NestingLevel.bullet_style
yang sesuai dalamList
placeholder induknya. - Terakhir, class tersebut berusaha mewarisi dari objek placeholder induk lainnya.