Metin Yapısı ve Stili

Slaytlar API'sinde metin, şekillerde veya tablo hücrelerinde tutulabilir. Metinleri işleme ve stil belirlemeden önce yapısını ve stilin nasıl çalıştığını anlamanız gerekir.

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

Metin öğesi dizileri

Bir şekilde veya tablo hücresinde bulunan metin, bir dizi TextElement yapısından oluşur. Bu adım sırası, metnin yapısını, baştan sona göründüğü sırayla temsil eder.

Örneğin, bu slaytın içeriğini (tümü tek bir metin kutusunda bulunan) ele alalım:

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

Daha somut bir şekilde ifade etmek gerekirse bu metin dizisi Slaytlar API'sinde şu şekilde temsil edilir:

"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, aşağıdaki metin nesnesi türlerinden biriyle birlikte öğenin sayfa öğesinin tam metni içindeki konumunu tanımlar:

Metin türü	Açıklama
ParagraphMarker	Bu metin öğesi, yeni bir paragrafın başlangıcını temsil eder. Metin öğesinin başlangıç ve bitiş dizini, paragrafı sonlandıran yeni satır karakteri de dahil olmak üzere paragrafın tamamını temsil eder. Bir paragraf başka bir paragrafla çakışmaz. Paragraflar her zaman yeni satır karakteriyle biter. Bu nedenle, bir şeklin veya tablo hücresinin metin içeriklerinin sonunda her zaman yeni bir satır olur. Paragraflar madde işaretli veya numaralı listelere ait olabilir. Bu durumda, ParagraphMarker.bullet alanının içeriği bir liste kimliği içerir. Bu kimlik, TextElement dizisiyle birlikte TextContent içinde bulunan bir liste öğesine referans verir. Aynı mantıksal liste içindeki paragraflar aynı liste kimliğine başvurur.
TextRun	Bu metin öğesi, hepsi aynı metin stiline sahip olan bitişik bir metin dizesini temsil eder. Metin hiçbir zaman paragraf sınırlarını aşmaz: Bir paragrafı bitiren metin bir sonraki paragraftan başlayan metinle aynı stile sahip olsa bile içerikler yeni satır karakterinden sonra ayrı bir metin oluşturmak için bölünür. Bir sayfa öğesinin içinde tam metin dizesini işlemeniz gerekiyorsa tüm metin öğelerini tekrarlayarak metnin tümünde bulunan dizeleri bir araya getirin.
AutoText	Otomatik metin, metindeki bağlama göre dinamik bir şekilde değişen yerleri ifade eder. Slaytlar'da bu, mevcut slayt numarasını metin içinde göstermek için kullanılır.

Slaytlar API'si gelecekte daha fazla metin öğesi türü içerebilir. Metni işleyen kod, yeni metin öğesi türlerini sorunsuz bir şekilde (genellikle bilinmeyen türleri yok sayarak) işlemelidir.

Metin içeriklerini değiştirme

Slaytlar API'yi kullanarak metni değiştirmeniz gerektiğinde, uygun tüm metin öğelerini açıkça oluşturmanız gerekmez. Bunun yerine, Slaytlar düzenleyicisinde olduğu gibi metin üzerinde çalışabilirsiniz: Metin ekleyerek, aralıkları silerek ve aralıklardaki stilleri güncelleyerek bu işlemleri yapabilirsiniz. Bu işlemler, değişikliklerinizi yansıtmak için gerektiğinde dolaylı olarak ParagraphMarker ve TextRun öğeleri oluşturur.

Metin ekleme

batchUpdate çağrısında InsertTextRequest isteğini kullanarak bir dizine metin ekleyebilirsiniz. Bu yöntemin insertionIndex alanı, metnin nereye ekleneceğini belirtir. Bu dizini, metin öğeleri içindeki 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 eklendiğinde dolaylı olarak yeni bir paragraf oluşturulur ve yeni satırın dizininde başlayıp sonraki yeni satırda biten bir ParagraphMarker metin öğesi oluşturulur. Madde işareti ve liste ayrıntıları dahil olmak üzere paragraf stili, mevcut paragraftan yeni paragrafa kopyalanır.
• Eklenen karakterlerin stili otomatik olarak belirlenir ve genellikle ekleme dizininde bulunan metin stili aynı kalır. Bunun sonucunda, metin genellikle bu dizindeki mevcut TextRun içine eklenir. Bu stili daha sonra UpdateTextStyle isteği kullanarak güncelleyebilirsiniz.

Metin siliniyor

Bir metin aralığını batchUpdate çağrısındaki DeleteTextRequest mesajını kullanarak silebilirsiniz. Metni silmek için bazı ince işlemler söz konusudur:

• Paragraf sınırını geçen bir silme işlemi, iki paragrafı birleştirerek ayıran ParagraphMarker metin öğesini siler.
• Birleştirilmiş yeni paragraf, Slaytlar düzenleyicisinde birleşik bir paragraf stili ve eşleme davranışı kullanacak.
• Aralığı bir metin çalıştırmasını kapsayan silme işlemi, metin çalıştırmasındaki tüm içeriği kaldırır ve metin çalıştırmasını da siler.
• Aralığı bir AutoText öğesi içeren silme işlemi, AutoText öğesini siler.

Metin stili güncelleniyor

Slayttaki metnin görünümü, metin stili özellikleri tarafından belirlenir:

• Girinti, hizalama ve madde işaretleri gibi paragraf stilleri, paragraf işaretçilerindeki özellikler tarafından tanımlanır.
• Kalın, italik ve altı çizili gibi karakter stilleri, bağımsız metin çalıştırmalarındaki özelliklerle tanımlanır.

Karakter stili güncelleniyor

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

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

Bazı karakter stilleri ayarlandığında, ilgili diğer stiller Slaytlar düzenleyicisindeki davranışla eşleşecek şekilde dolaylı olarak güncellenir. Örneğin, bir bağlantı eklendiğinde metin ön planı rengi ve özelliklerin alt çizgisi otomatik olarak değiştirilir. Daha fazla ayrıntı için TextStyle referans belgelerine bakın.

Paragraf stili güncelleniyor

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

Slaytlar API, madde işaretli ve numaralı listeler oluşturmaya yönelik olarak Slaytlar düzenleyicisindeki madde işareti hazır ayarlarının işlevselliğini yansıtan CreateParagraphBulletsRequest öğesini destekler. Benzer şekilde, DeleteParagraphBulletsRequest paragraflardaki mevcut madde işaretlerini kaldırır.

Devralınan stiller

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

Bu bölüm, bir slaytta görüntülenen nihai, oluşturulmuş metin stillerini oluşturmak için stil devralma işleminin nasıl çalıştığına odaklanmaktadır.

Yer tutucularda stil gösterimi

placeholders bölümünde, devralmanın üst ve alt şekiller arasındaki işleyiş şekli açıklanmaktadır. Metin stillerinin devralınması, devralma modelindeki ek özellikler tarafından gerçekleştirilir:

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

Aşağıdaki şemada, bu ilişkileri görselleştirmenin bir yolu gösterilmektedir:

Üst şekildeki ilk ParagraphMarker/TextRun, devralınan metin stilinin çoğunu belirler; kalan yedi çiftteki stil yalnızca kademeli olarak daha derin şekilde iç içe yerleştirilmiş madde işareti seviyelerindeki paragrafları etkiler:

Üst metin öğesi çifti	Denetlediği alt biçimlendirme
İlk ParagraphMarker İlk TextRun	Düzey 0'ın (en dıştaki) liste paragraflarını ve liste olmayan tüm paragrafları listeleyen metin stili.
İkinci ParagraphMarker İkinci TextRun	Kalan (iç içe yerleştirilmiş) liste seviyelerinin 1-7 metin stili
Üçüncü ParagraphMarker Üçüncü TextRun
Dördüncü ParagraphMarker Dördüncü TextRun
Beşinci ParagraphMarker Beşinci TextRun
Altıncı ParagraphMarker Altıncı TextRun
Yedinci ParagraphMarker Yedinci TextRun
Sekizinci ParagraphMarker Sekizinci TextRun

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

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

Bir üst şeklin TextRun öğesindeki 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ı dahilinde devralınan tüm özellikleri geçersiz kılar. Herhangi bir stil belirtmeyen öğeler, üst öğeden devralınan ilgili stili kullanır.

Bir alt şekilden açık stil özelliğinin, artık ayarlanmamış olması için kaldırılması, üst öğeden devralınmasına neden olur.

Örnek

Yukarıdaki şemada gösterilen devralma göz önünde bulundurulduğunda, ParentPlaceholder şeklindeki şeklin 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"} }, ...}
      }
    },
   ...
  ]
}

Ayrıca, 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, aşağıdaki paragraflarda açıklanan sonuçlarla sonuçlanır.

Düz bir paragraf için stil devralma

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ğini belirtmediğinden, tüm karakter ve paragraf stillerini üst öğesinden devralır. Bu, aşağıdaki oluşturmaya neden olur:

• Metin: "Bu benim ilk paragrafım", oluşturulan metindir. Metnin kendisi asla devralınmaz.
• Hizalama: Metin, üst öğenin ilk ParagraphMarker öğesinden devralınacak şekilde START hizalamasıyla oluşturulur.
• Ön plan rengi: Metin, üst öğenin ilk TextRun öğesinden alınan DARK1 ön plan rengiyle oluşturulur.

Bir liste paragrafı için stil devralma

"Bu paragraf bir listede" metnini içeren sonraki paragraf, karşılık gelen ParagraphMarker öğesinin bullet alanı bu düzeye ayarlandığı için iç içe yerleştirme düzeyi 1'de madde işaretli bir listededir. Sonuç olarak, üst öğedeki iç içe yerleştirme düzeyi 1'den metin ve paragraf stilini devralır. Bu işlem aşağıdaki oluşturmayla sonuçlanır:

• Metin: "Bu paragraf bir listede", oluşturulan metindir. Metnin kendisi asla devralınmaz.
• Hizalama: Metin, üst öğenin ikinci ParagraphMarker öğesinden devralınacak şekilde "END" hizalamasıyla oluşturulur.
• Ön plan rengi: Metin, üst öğenin ikinci TextRun öğesinden alınan LIGHT1 metin ön plan rengiyle oluşturulur.

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

Bir alt şekilde ayarlanmayan metin stilleri, üst öğesinden değer devralır. Alt öğede ayarlanan metin stilleri, bazı yerel kapsamlardaki üst değerleri "geçersiz kılar".

Bir alt şeklin metin stilinin ayarını kaldırmak için UpdateTextStyleRequest öğesini kullanabilirsiniz. Böylece, artık yerel bir geçersiz kılma bulunmaz ve böylece, syltes'ler üst şekilden devralınır. Buna ek olarak, alt öğenin metin stilinin bir üst öğeden devralınan değerle eşleşecek şekilde güncellenmesi, stilin devralınan değeri kullanması için stili dolaylı olarak iptal eder.

Bir alt şeklin stilini üst şeklinin stiliyle tam olarak eşleşecek şekilde ayarlamak (stiyi devralmasına neden olur), alt şeklin stilinin ayarını kaldırmakla aynı sonucu verir.

Bu, güncellemeden hemen sonra metnin görsel görünümünü etkilemez ancak daha sonra üst yer tutucudaki bir paragrafı veya metin stilini güncellemeniz halinde önemli olabilir. Bu devralma davranışı, Slaytlar düzenleyicisinin davranışıyla eşleşir. Böylece, API'ye karşı çalışmadan önce stil değişikliklerinin sonuçlarıyla denemeler yapabilirsiniz.

Örnek

ChildPlaceholder ve ParentPlaceholder için bir önceki örnekte verilen tanımları inceleyin.

Şimdi şu UpdateTextStyleRequest öğesini 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 bir alan maskesi kullanarak tüm ChildPlaceholder metnine bir DARK1preorderColor ayarlamayı dener. Bu talebin sonuçları aşağıdaki gibidir:

• İlk paragraf: Yeni foregroundColor, devralınan foregroundColor ile eşleşir. Bu nedenle bu stil değişmeden kalır.
• İkinci paragraf: Yeni foregroundColor, devralınan foregroundColor ile eşleşmediğinden ikinci paragrafın ön plan rengi DARK1 olarak güncellenir.

ChildPlaceholder'ın metin içeriği artık:

"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 glif metin stili

Normal metinlerde olduğu gibi madde işaretlerinde de glifin oluşturulma biçimini kontrol eden bir metin stili bulunur. Bu metin stilleri, Slaytlar API kullanılarak doğrudan değiştirilemez. Bununla birlikte, madde işareti içeren tam bir paragrafı güncellemek için UpdateTextStyleRequest kullanırsanız Slaytlar API'si madde işareti glifinin metin stilini eşleşecek şekilde günceller.

Madde işareti karakterli metin stilleri, normal metin stillerinden biraz farklı bir devralma hiyerarşisi izler.

1. Belirli bir iç içe yerleştirme düzeyindeki madde işareti, öncelikle madde işaretinin List nesnesindeki NestingLevel.bullet_style alanında ayarlanan TextStyle öğesini devralır.
2. Daha sonra, üst yer tutucusunun List öğesindeki karşılık gelen NestingLevel.bullet_style öğesinden devralır.
3. Son olarak, kalan üst yer tutucu nesnelerden devralmayı dener.

Layouts ve Ana Öğeler'deki yer tutuculardaki madde işaretlerinin "ParagraphMarker.bullet" alanında boş bir "TextStyle" değeri bulunur ve bu paragraflardaki metin stili güncellemeleri yalnızca "Liste" mesajlarına yansıtılır.