Metin Yapısı ve Stili

Slaytlar API'sinde metinler şekillerde veya tablo hücrelerinde bulunabilir. Metni değiştirip biçimlendirebilmek için metnin yapısını ve biçimlendirmenin işleyiş şeklini anlamanız gerekir.

Bu sayfada, metnin Slaytlar API'sinde nasıl temsil edildiği açıklanmaktadır.

Metin öğesi dizileri

Bir şekil veya tablo hücresinde bulunan metin, TextElement yapılarının bir dizisinden oluşur. Bu sıra, metnin başlangıçtan sona kadar göründüğü sırayla yapısını temsil eder.

Örneğin, tümünün tek bir metin kutusunda yer aldığı şu slayttaki içeriği düşünün:

Yukarıdaki slaytta, text alanının aşağıdaki şemada gösterildiği gibi bir metin öğesi dizisi içeren bir metin kutusu vardır:

Daha açık belirtmek gerekirse bu metin dizisi, Slaytlar API'de aşağıdaki gibi gösterilir:

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

TextElement içerikleri

Her metin öğesi, sıfır tabanlı bir başlangıç dizini ve bitiş dizini içerir. Bu dizinler, öğenin sayfa öğesinin tam metnindeki konumunu tanımlar ve aşağıdaki metin nesnesi türlerinden biriyle birlikte kullanılır:

Metin içeriklerini değiştirme

Slaytlar API'sini kullanarak metni değiştirmeniz gerektiğinde, tüm uygun metin öğelerini açıkça oluşturmanız gerekmez. Bunun yerine, metin üzerinde Slaytlar düzenleyicisinde yaptığınız işlemleri yapabilirsiniz: Metin ekleyebilir, aralıkları silebilir ve aralıklardaki stilleri güncelleyebilirsiniz. Bu işlemler, değişikliklerinizi yansıtmak için gerektiğinde ParagraphMarker ve TextRun öğelerini dolaylı olarak oluşturur.

Metin ekleme

batchUpdate çağrısında InsertTextRequest isteğini kullanarak bir dizin içine metin ekleyebilirsiniz. Bu yöntemin insertionIndex alanı, metnin nereye ekleneceğini belirtir. Bu dizini, metin öğelerindeki başlangıç ve bitiş dizini alanlarını kullanarak hesaplayabilirsiniz.

Metin eklemenin, Slaytlar düzenleyicisinin davranışını yansıtan bazı yan etkileri vardır:

• Yeni satır karakteri eklemek, yeni bir paragraf oluşturur. Bu paragraf, yeni satırın dizini ile sonraki yeni satır arasında başlayan ve biten bir ParagraphMarker metin öğesi oluşturur. Noktalı liste ve liste ayrıntıları dahil olmak üzere paragraf stili, mevcut paragraftan yeni paragrafa kopyalanır.
• Eklenen karakterlerin stili otomatik olarak belirlenir. Genellikle, ekleme dizininde bulunan metin stili korunur. Sonuç olarak, metin genellikle söz konusu dizindeki mevcut TextRun öğesine eklenir. Bu stili daha sonra UpdateTextStyle isteğiyle güncelleyebilirsiniz.

Metni silme

batchUpdate çağrısında DeleteTextRequest mesajını kullanarak bir metin aralığını silebilirsiniz. Metin silme işleminde bazı incelikler vardır:

• Bir paragraf sınırını aşan silme işlemi, iki paragrafı birleştirir ve ayırıcı ParagraphMarker metin öğesini siler.
• Birleştirilen yeni paragrafta, Slaytlar düzenleyicisindeki davranışla eşleşen birleşik bir paragraf stili kullanılır.
• Bir metin satırını kapsayan silme işlemi, metin satırındaki tüm içeriği ve metin satırını da siler.
• Aralığı bir AutoText öğesini kapsayan silme işlemi, AutoText öğesini siler.

Metin stilini güncelleme

Slayttaki metnin oluşturulan görünümü, metin stili özelliklerine göre belirlenir:

• Girintili paragraf, hizalama ve madde işareti gibi paragraf stilleri, paragraf işaretçilerindeki özelliklerle tanımlanır.
• Kalın, italik ve altı çizili gibi karakter stilleri, bağımsız metin satırlarındaki özelliklerle tanımlanır.

Karakter stilini güncelleme

batchUpdate çağrısında UpdateTextStyleRequest mesajını kullanarak karakter stillerini güncelleyebilirsiniz.

Diğer metin işlemleri gibi karakter stili de bir metin aralığına uygulanır ve gerektiğinde yeni TextRun nesneleri dolaylı olarak oluşturur.

Bazı karakter stilleri ayarlandığında, ilgili diğer stiller de Slaytlar düzenleyicisindeki davranışla eşleşecek şekilde dolaylı olarak güncellenir. Örneğin, bir bağlantı eklediğinizde metnin ön plan rengi ve altı çizili özellikleri otomatik olarak değişir. Daha fazla ayrıntı için TextStyle referans dokümanlarını inceleyin.

Paragraf stilini güncelleme

batchUpdate çağrısında UpdateParagraphStyleRequest mesajını kullanarak paragraf stillerini güncelleyebilirsiniz.

Slaytlar API'si, madde işaretli ve numaralandırılmış listeler oluşturmak için Slaytlar düzenleyicisindeki madde işareti hazır ayarlarının işlevini yansıtan bir CreateParagraphBulletsRequest işlevini destekler. Benzer şekilde, DeleteParagraphBulletsRequest işlevi paragraflardaki mevcut tüm madde işaretlerini kaldırır.

Devralınan stiller

Yer tutucular olarak bilinen bazı şekiller, diğer üst şekillerden metin stilleri alabilir: Genel olarak şekil devralma hakkında daha fazla bilgi edinmek için yer tutucular bölümüne bakın.

Bu bölümde, bir slaytta gösterilen nihai, oluşturulmuş metin stillerini oluşturmak için stil devralımının nasıl çalıştığı ele alınmaktadır.

Yer tutucularda stil temsili

Yer tutucular bölümünde, ana ve alt şekiller arasında devralınmanın işleyiş şekli açıklanmaktadır. Metin stillerinin devralınması, devralma modelindeki ek özellikler tarafından yönetilir:

• ParagraphMaker metin öğelerinin özellikleri paragraf biçimlendirmesini tanımlar.
• TextRun metin öğelerinin özellikleri karakter biçimlendirmesini tanımlar.
• Üst öğe yer tutucularının içeriği, sekiz tane ParagraphMarker/TextRun çifti içerir (sekiz düzeyde liste iç içe yerleştirmeyi desteklemek için).
• Alt yer tutucu, varsayılan metin özelliklerini üst öğesinin metin içeriğindeki bu metin öğelerinden devralır.

Aşağıdaki şemada bu ilişkilerin görselleştirilmesinin bir yolu gösterilmektedir:

Üst öğedeki ilk ParagraphMarker/TextRun, devralınan metin stilinin çoğunu belirler. Kalan yedi çiftteki stil, yalnızca giderek daha derin iç içe yerleştirilmiş madde düzeylerindeki paragrafları etkiler:

Bu metin öğesi çiftlerine erişmek için aşağıdaki snippet'te gösterildiği gibi textElements alanındaki açık dizinlerini kullanın. Bu snippet'te, 0. seviye ve liste dışı paragraflar için varsayılan (devralınabilir) stilin ayarlanması gösterilmektedir:

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

Üst öğe şeklinin TextRun alanındaki content alanının her zaman tek bir yeni satır karakterinden oluştuğunu unutmayın.

Devralınan stiller geçersiz kılınabilir

Alt şekil, içeriğindeki ParagraphMarker ve TextRun öğelerinde stil özelliklerini belirtebilir. Yerel olarak belirtilen bu özellikler, yerel kapsamlarındaki tüm devralınan özellikleri geçersiz kılar. Stil belirtilmeyen öğeler, üst öğeden devralınan ilgili stili kullanır.

Bir alt şekilden açık stil özelliği kaldırılırsa (artık ayarlanmamışsa) bu özellik üst öğeden devralınır.

Örnek

Yukarıdaki diyagramda gösterilen devralma işlemi göz önüne alındığında, ParentPlaceholder şeklinin aşağıdaki metin içeriğine sahip olduğunu varsayalım:

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

ChildPlaceholder şeklinin aşağıdaki metin içeriğine sahip olduğunu varsayalım:

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

Bu durum, aşağıdaki paragraflarda açıklanan sonuçlara yol açar.

Düz bir paragraf için stil devralınması

Alt şeklin "Bu benim ilk paragrafım" metnini içeren ilk paragrafı, düz bir paragraftır (liste içinde değildir). Metin içeriğindeki hiçbir öğe stil özelliği belirtmediğinden tüm karakter ve paragraf stillerini üst öğesinden devralır. Bu, aşağıdaki oluşturmaya neden olur:

• Metin: Oluşturulan metin "This is my first paragraph" (Bu benim ilk paragrafım) olur. Metnin kendisi hiçbir zaman devralınmaz.
• Hizalama: Metin, üst öğenin ilk ParagraphMarker öğesinden devralınan START hizalamasıyla oluşturulur.
• Ön plan rengi: Metin, üst öğenin ilk TextRun öğesinden devralınan DARK1 ön plan rengiyle oluşturulur.

Liste paragrafı için stil devralma

"Bu paragraf bir listededir" metnini içeren bir sonraki paragraf, ParagraphMarker öğesinin bullet alanının bu seviyeye ayarlanmış olması nedeniyle 1. iç içe yerleştirme düzeyinde bir madde listesi şeklindedir. Sonuç olarak, metin ve paragraf stilini üst öğenin 1. iç içe yerleştirme seviyesinden devralır. Bu işlem sonucunda aşağıdaki oluşturma işlemi gerçekleşir:

• Metin: Oluşturulan metin "Bu paragraf bir listededir". Metnin kendisi hiçbir zaman devralınmaz.
• Hizalama: Metin, üst öğenin ikinci ParagraphMarker öğesinden devralınan "END" hizalamasıyla oluşturulur.
• Ön plan rengi: Metin, üst öğenin ikinci TextRun öğesinden devralınan LIGHT1 metin ön plan rengiyle oluşturulur.

Metin ve paragraf stilleri güncelleme ve devralma arasındaki etkileşimler

Alt öğe şeklinde ayarlanmayan metin stilleri, değerleri üst öğesinden devralır. Alt öğede ayarlanan metin stilleri, bazı yerel kapsamlarda üst öğe değerlerini "geçersiz kılar".

Bir alt şeklin metin stilini ayarlamak için UpdateTextStyleRequest kullanabilirsiniz. Böylece, yerel geçersiz kılma işlemi kaldırılır ve stil üst öğeden devralınır. Ayrıca, alt öğenin metin stilini üst öğeden devralınan değerle eşleşecek şekilde güncellemek, devralınan değeri kullanması için stilin gizlice ayarını kaldırır.

Bu, güncellemeden hemen sonra metnin görsel görünümünü etkilemez ancak daha sonra üst öğe yer tutucusundaki bir paragrafı veya metin stilini güncellerseniz önemli olabilir. Bu devralma davranışı, Slaytlar düzenleyicisinin davranışıyla eşleştiğinden API ile çalışmaya başlamadan önce stil değişikliklerinin sonuçlarını deneyebilirsiniz.

Örnek

ChildPlaceholder ve ParentPlaceholder için önceki örnekteki tanımları göz önünde bulundurun.

Şimdi şu UpdateTextStyleRequest'i gönderdiğinizi varsayalım:

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

Bu istek, yalnızca öğenin ön plan renginin değişmesi gerektiğini belirtmek için alan maskesi kullanarak ChildPlaceholder öğesinin tüm metnine DARK1 foregroundColor ayarlamaya çalışır. Bu istek aşağıdaki sonuçları doğurur:

• İlk paragraf: Yeni foregroundColor, devralınan foregroundColor ile eşleştiği için bu stil değişmez ve devralınır.
• İkinci paragraf: Yeni foregroundColor, devralınan foregroundColor ile eşleşmez. Bu nedenle, ikinci paragrafın ön plan rengi DARK1 olarak güncellenir.

ChildPlaceholder'ın metin içeriği şu şekildedir:

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

Madde işareti glifi metin stili

Normal metin gibi, madde işareti gliflerinin de gliflerin nasıl oluşturulacağını kontrol eden bir metin stili vardır. Bu metin stilleri doğrudan Slaytlar API'si kullanılarak değiştirilemez. Ancak, UpdateTextStyleRequest kullanarak bir madde işareti içeren bir paragrafın tamamını güncellerseniz Slaytlar API'si, madde işareti glifinin metin stilini eşleşecek şekilde günceller.

Nokta simgesi metin stilleri, normal metin stillerinden biraz farklı bir devralma hiyerarşisi izler.

1. Belirli bir iç içe yerleştirme düzeyindeki bir madde işareti, önce madde işaretinin List nesnesi içindeki NestingLevel.bullet_style alanındaki TextStyle kümesini devralır.
2. Ardından, üst yer tutucunun List alanındaki ilgili NestingLevel.bullet_style öğesinden devralır.
3. Son olarak, kalan üst yer tutucu nesnelerden devralmaya çalışır.