Struktur dan Gaya Teks

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.

Slides API dapat menyertakan lebih banyak jenis elemen teks di masa mendatang. Kode yang memproses teks harus menangani jenis elemen teks baru dengan baik, biasanya dengan mengabaikan jenis yang tidak dikenal.

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 elemen AutoText.

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 dari ParagraphMarker pertama induk.
• Warna latar depan: Teks dirender dengan warna latar depan DARK1, diwarisi dari TextRun 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 dari TextRun 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.

Menyetel gaya bentuk turunan agar sama persis dengan induknya (sehingga menyebabkannya mewarisi gaya) memiliki hasil yang sama dengan membatalkan penetapan gaya bentuk turunan.

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 dengan foregroundColor yang diwarisi, sehingga gaya ini tidak berubah dan masih diwarisi.
• Paragraf kedua: foregroundColor yang baru tidak cocok dengan foregroundColor yang diwarisi sehingga warna latar depan paragraf kedua diperbarui menjadi DARK1.

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.

1. Butir pada tingkat hierarki tertentu terlebih dahulu mewarisi dari TextStyle yang ditetapkan dalam kolom NestingLevel.bullet_style di dalam objek List butir.
2. Selanjutnya, elemen ini mewarisi dari NestingLevel.bullet_style yang sesuai dalam List placeholder induknya.
3. Terakhir, class tersebut berusaha mewarisi dari objek placeholder induk lainnya.

Butir dalam placeholder pada Tata Letak dan Master memiliki `TextStyle` kosong di kolom `ParagraphMarker.bullet`, dan setiap perubahan gaya teks pada paragraf tersebut hanya akan terlihat dalam pesan `List`.