Struktur dan Gaya Teks

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Di Slides API, teks dapat ditempatkan dalam bentuk atau dalam sel tabel. Sebelum dapat memanipulasi dan menata gaya teks, Anda perlu memahami strukturnya dan cara kerja gaya visual.

Halaman ini menjelaskan cara teks direpresentasikan di Slides API.

Urutan elemen teks

Teks yang terdapat dalam bentuk atau sel tabel terdiri dari urutan struktur TextElement. Urutan ini mewakili struktur teks, dalam urutan yang muncul dari awal hingga akhir.

Misalnya, pertimbangkan konten 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:

Secara lebih konkret, 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 dalam teks lengkap elemen halaman, bersama dengan salah satu jenis objek teks berikut:

Mengubah konten teks

Jika perlu mengubah teks menggunakan Slides API, Anda tidak perlu membuat semua elemen teks yang sesuai secara eksplisit. Sebagai gantinya, Anda dapat mengoperasikan 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 indeks menggunakan permintaan InsertTextRequest dalam panggilan ke batchUpdate. Kolom insertionIndex 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, membuat elemen teks ParagraphMarker yang dimulai pada indeks baris baru dan berakhir pada baris baru berikutnya. Gaya paragraf—termasuk detail titik dan daftar — disalin dari paragraf saat ini ke paragraf baru.
• Gaya karakter yang disisipkan ditentukan secara otomatis, biasanya mempertahankan gaya teks yang sama dengan yang ada di indeks penyisipan. Akibatnya, teks biasanya 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 panggilan ke batchUpdate. Menghapus teks melibatkan beberapa hal yang perlu diperhatikan:

• Penghapusan yang melintasi batas paragraf akan menggabungkan dua paragraf, yang menghapus elemen teks ParagraphMarker pemisah.
• Paragraf gabungan baru akan menggunakan gaya paragraf gabungan, yang cocok dengan perilaku di editor Slide.
• Penghapusan yang rentangnya mencakup run teks akan menghapus semua konten dari run teks, dan juga menghapus run teks itu sendiri.
• Penghapusan yang rentangnya mencakup elemen AutoText akan menghapus elemen AutoText.

Memperbarui gaya teks

Tampilan teks yang dirender dalam slide ditentukan oleh properti gaya teks:

• Gaya paragraf seperti indentasi, perataan, dan glyph peluru, 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.

Menetapkan beberapa gaya karakter secara implisit akan memperbarui gaya terkait lainnya agar cocok 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 buletin di editor Slide untuk pembuatan daftar berbutir dan bernombor. Demikian pula, DeleteParagraphBulletsRequest akan menghapus buletin yang ada pada paragraf.

Gaya turunan

Beberapa bentuk, yang dikenal sebagai placeholder, dapat mewarisi gaya teks dari bentuk induk lain: lihat placeholder 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 dalam slide.

Representasi gaya dalam placeholder

Bagian tentang placeholder 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 bertingkat daftar).
• Placeholder turunan mewarisi properti teks defaultnya dari elemen teks ini dalam konten teks induknya.

Diagram berikut menunjukkan salah satu cara untuk memvisualisasikan hubungan ini:

ParagraphMarker/TextRun pertama dalam bentuk induk menentukan sebagian besar gaya visual teks yang diwarisi; gaya visual dalam tujuh pasangan yang tersisa hanya memengaruhi paragraf pada tingkat peluru bertingkat yang semakin dalam:

Untuk mengakses pasangan elemen teks ini, gunakan indeks eksplisitnya dalam kolom textElements seperti yang ditunjukkan dalam cuplikan di bawah, yang menunjukkan setelan gaya default (dapat diwariskan) untuk paragraf tingkat 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 pada 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 yang sesuai yang diwarisi dari induk.

Menghapus properti gaya eksplisit dari bentuk turunan, sehingga tidak lagi ditetapkan, akan menyebabkannya mewarisi dari induk.

Contoh

Dengan pewarisan yang ditunjukkan dalam diagram di atas, misalkan 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 misalkan bentuk ChildPlaceholder 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 menyertakan teks "Ini adalah paragraf pertama saya", adalah paragraf biasa (bukan dalam daftar). Tidak ada elemen dalam konten teksnya yang menentukan properti gaya apa pun, sehingga elemen ini mewarisi semua gaya karakter dan paragrafnya dari induk. 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, yang diwarisi dari TextRun pertama induk.

Pewarisan gaya untuk paragraf daftar

Paragraf berikutnya, yang menyertakan teks "Paragraf ini ada dalam daftar", berada dalam daftar berbutir pada tingkat bertingkat 1, karena ParagraphMarker yang sesuai memiliki kolom bullet yang ditetapkan ke tingkat ini. Akibatnya, gaya teks dan paragraf akan diwarisi dari tingkat 1 bertingkat di induk. Hal ini menghasilkan rendering berikut:

• Teks: "Paragraf ini ada dalam daftar" adalah teks yang dirender. Teks itu sendiri tidak pernah diwarisi.
• Perataan: Teks dirender dengan perataan "END", yang diwarisi dari ParagraphMarker kedua induk.
• Warna latar depan: Teks dirender dengan warna latar depan teks LIGHT1, yang diwarisi dari TextRun kedua induk.

Interaksi antara memperbarui dan mewarisi gaya teks dan paragraf

Gaya teks yang tidak ditetapkan dalam bentuk turunan akan mewarisi nilai dari induk. Gaya teks yang ditetapkan di turunan akan "mengganti" nilai induk dalam beberapa cakupan lokal.

Anda dapat menggunakan UpdateTextStyleRequest untuk menetapkan ulang gaya teks bentuk turunan, sehingga tidak lagi memiliki penggantian lokal dan dengan demikian mewarisi gayanya dari bentuk induk. Selain itu, memperbarui gaya teks turunan agar cocok dengan nilai yang diwarisi dari induk secara implisit akan menghapus gaya sehingga menggunakan nilai yang diwarisi.

Hal ini tidak memengaruhi tampilan visual teks segera setelah pembaruan, tetapi mungkin penting jika Anda nantinya memperbarui paragraf atau gaya teks di placeholder induk. Perilaku pewarisan ini cocok dengan perilaku editor Slide, sehingga Anda dapat bereksperimen dengan hasil perubahan gaya sebelum menggunakan API.

Contoh

Pertimbangkan definisi dalam contoh sebelumnya untuk ChildPlaceholder dan ParentPlaceholder.

Sekarang, anggaplah Anda mengirimkan UpdateTextStyleRequest ini:

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

Permintaan ini mencoba menetapkan foregroundColor DARK1 ke semua teks ChildPlaceholder, menggunakan field mask untuk menentukan bahwa hanya warna latar depan elemen yang akan 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 baru tidak cocok dengan foregroundColor yang diwarisi, sehingga warna latar depan paragraf kedua diperbarui menjadi DARK1.

Konten teks ChildPlaceholder sekarang adalah:

"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 glyph titik

Seperti teks normal, glyph titik memiliki gaya teks yang mengontrol cara glyph dirender. Gaya teks ini tidak dapat diubah menggunakan Slides API secara langsung. Namun, jika Anda menggunakan UpdateTextStyleRequest untuk memperbarui paragraf lengkap yang menyertakan tanda peluru, Slides API akan memperbarui gaya teks glyph peluru agar cocok.

Gaya teks glyph peluru mengikuti hierarki pewarisan yang sedikit berbeda dengan gaya teks normal.

1. Tanda peluru pada tingkat tingkatan tertentu pertama kali mewarisi dari TextStyle yang ditetapkan di kolom NestingLevel.bullet_style di dalam objek List peluru.
2. Selanjutnya, NestingLevel.bullet_style mewarisi dari NestingLevel.bullet_style yang sesuai dalam List placeholder induknya.
3. Terakhir, objek ini mencoba mewarisi dari objek placeholder induk yang tersisa.