Google Docs API'yi etkili bir şekilde kullanmak için bir Google Dokümanlar dokümanının mimarisini, bir dokümanı oluşturan öğeleri ve bunlar arasındaki ilişkiyi anlamanız gerekir. Bu sayfada, bu konulara ayrıntılı bir genel bakış sunulmaktadır:
- Belge öğelerinin kavramsal modeli
- Docs API bu öğeleri nasıl temsil eder?
- Öğelerin stil özellikleri
Üst düzey öğeler
Google Dokümanlar'daki en dıştaki kapsayıcı öğe bir dokümandır. Bu birim Google Drive'a kaydedilebilen, diğer kullanıcılarla paylaşılabilen, metin ve resimlerle güncellenebilen birimdir.
Bir documents kaynağının üst düzey öğeleri Body, Header, Footer ve daha birçok özelliği içerir:
document: {
body: ... ,
documentStyle: ... ,
lists: ... ,
documentId: ... ,
namedStyles: ... ,
revisionId: ... ,
title: ...
}
Genel doküman özelliklerini Body içeriğinin dışındaki değiştirmek için programatik olarak yeni dokümanlar oluşturmak üzere temel olarak kullanabileceğiniz bir veya daha fazla belge şablonu kullanmak neredeyse her zaman daha iyidir. Daha fazla bilgi için Metni dokümanda birleştirme bölümüne bakın.
Gövde içeriği
Body, genellikle tüm doküman içeriğini barındırır. Programatik olarak kullanabileceğiniz veya muhtemelen kullanmak isteyebileceğiniz öğelerin çoğu Body içeriğinde yer alır:
Yapısal öğe
StructuralElement, dokümanın yapısını sağlayan içerikleri tanımlar. Body içeriği, StructuralElement nesneden oluşan bir dizidir. Bir içerik öğesi, aşağıdaki şemada gösterildiği gibi her bir StructuralElement nesnesini kişiselleştirir:
Yapısal öğeler ve bunların içerik nesneleri, belgedeki tüm görsel bileşenleri içerir. Buna metin, satır içi resimler ve biçimlendirme dahildir.
Paragraf yapısı
Paragraph, bir paragrafı temsil eden StructuralElement öğesidir. Yeni satır karakteriyle sonlandırılan
bir içerik yelpazesine sahiptir. Aşağıdaki nesnelerden oluşur:
ParagraphElement: Bir paragraftaki içeriği açıklar.ParagraphStyle: Paragraf için stil özelliklerini açıkça ayarlayan isteğe bağlı bir öğe.Bullet: Paragraf bir listenin parçasıysa madde işareti spesifikasyonu sağlayan isteğe bağlı bir öğe.
ParagraphElement, StructuralElement gibi çalışır. Bir içerik öğesi türü grubu (ör. ColumnBreak ve Equation), aşağıdaki şemada gösterildiği gibi kendi ParagraphElement öğesini kişiselleştirir:
Eksiksiz bir belge yapısı örneği için JSON biçimindeki doküman örneğine bakın. Çıkışta, temel yapısal ve içerik öğelerinin çoğunun yanı sıra başlangıç ve bitiş dizinlerinin kullanımını aşağıdaki bölümde açıklanan şekilde görebilirsiniz.
Metin çalışıyor
TextRun, tamamen aynı metin stiline sahip bitişik bir metin dizesini temsil eden ParagraphElement öğesidir. Bir paragraf birden fazla metin çalıştırması içerebilir ancak metin hiçbir zaman paragraf sınırlarını aşmaz. İçerikler, yeni satır karakterinden sonra ayrı metin çalıştırmaları oluşturmak için bölünür. Örneğin, aşağıdaki gibi küçük bir dokümanı ele alalım:
Aşağıdaki şemada, her biri kendi TextRun ve isteğe bağlı Bullet ayarlarına sahip olan, önceki dokümanda paragraf sırasını nasıl görselleştirebileceğiniz gösterilmiştir.
AutoText
AutoText, metindeki bir noktayı temsil eden ve zaman içinde değişebilen içerikle dinamik olarak değiştirilen bir ParagraphElement değeridir. Dokümanlar'da bu, sayfa numaraları için
kullanılır.
Başlangıç ve bitiş dizinleri
Bir dokümanın içeriğinde güncellemeler yaptığınızda, her güncelleme bir konumda veya dokümanın içindeki bir aralıkta gerçekleşir. Bu konumlar ve aralıklar, içeren bir belge segmenti içindeki ofseti temsil eden dizinler kullanılarak belirlenir. Segment, yapısal öğeler veya içerik öğeleri içeren gövde, üst bilgi, alt bilgi veya dipnottur. Bir segment içindeki öğelerin dizinleri, söz konusu segmentin başlangıcına bağlıdır.
Gövde içeriğindeki çoğu öğe, sıfır tabanlı startIndex ve endIndex özelliklerine sahiptir. Bunlar, bir öğeyi çevreleyen segmentin başlangıcına göre başlangıç ve bitişinin uzaklığını gösterir. Dokümanlar API'si toplu çağrılarınızı sıralama hakkında daha fazla bilgi için Toplu güncellemeler başlıklı makaleyi inceleyin.
Dizinler, UTF-16 kod birimleriyle ölçülür. Bu, vekil çiftlerinin iki dizin tükettiği anlamına gelir. Örneğin "SİLGİ SURAT" emojisi 😄 \uD83D\uDE00 olarak temsil edilir ve iki dizin kullanır.
Belge gövdesindeki öğeler için dizinler, "kök" öğe olan gövde içeriğinin başlangıcından itibaren olan ofsetleri temsil eder.
SectionBreak,
TableOfContents,
Table ve
Paragraph yapısal öğeleri için "kişiselleştirme" türleri, ilgili StructuralElement alanlarında bu alanlar bulunduğundan bu dizinlere sahip değildir. Bu durum, ParagraphElement içinde yer alan TextRun, AutoText ve PageBreak gibi kişiselleştirme türleri için de geçerlidir.
Erişim öğeleri
Birçok öğe documents.batchUpdate yöntemiyle değiştirilebilir. Örneğin, metin içeren herhangi bir öğenin içeriğini InsertTextRequest kullanarak değiştirebilirsiniz. Benzer şekilde, bir veya daha fazla öğede bulunan metin aralığına biçimlendirme uygulamak için UpdateTextStyleRequest kullanabilirsiniz.
Dokümanın öğelerini okumak için documents.get yöntemini kullanarak dokümanın tamamının JSON dökümünü elde edin. Daha sonra, tekil öğelerin değerlerini bulmak için elde edilen JSON'u ayrıştırabilirsiniz. Daha fazla bilgi için JSON olarak çıkış dokümanı içeriği bölümüne bakın.
İçeriğin ayrıştırılması çeşitli kullanım alanlarında faydalı olabilir. Örneğin, bulduğu belgeleri listeleyen bir belgeyi kataloglama düşünelim. Bu uygulama, aşağıdaki şemada gösterildiği gibi bir belgenin başlığını, düzeltme kimliğini ve başlangıç sayfası numarasını ayıklayabilir:
Bu ayarları açıkça okumak için bir yöntem olmadığından uygulamanızın tüm belgeyi alması ve ardından bu değerleri ayıklamak için JSON'u ayrıştırması gerekir.
Mülkten devralınan izinler
StructuralElement, mülkleri üst nesnelerinden devralabilir. Tanımladıkları ve devraldıkları özellikler de dahil olmak üzere, bir nesnenin özellikleri nihai görsel görünümünü belirler.
Metin karakter biçimlendirmesi, metnin bir dokümanda nasıl oluşturulduğunu (kalın, italik ve altı çizili gibi) belirler. Uyguladığınız biçimlendirme, temel paragraftan TextStyle devralınan varsayılan biçimlendirmeyi geçersiz kılar. Buna karşılık, biçimlendirmesini ayarlamadığınız karakterler paragrafın stillerinden devralmaya devam eder.
Paragraf biçimlendirmesi, metin bloklarının bir dokümanda nasıl hizalanacağını (ör. hizalama, kenarlıklar ve girinti) belirler. Uyguladığınız biçimlendirme, temel ParagraphStyle öğesinden devralınan varsayılan biçimlendirmeyi geçersiz kılar.
Bununla birlikte, ayarlamadığınız tüm biçimlendirme özellikleri paragraf stilinden devralınmaya devam eder.