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 aşağıdaki konulara dair 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ış kapsayıcı öğe doküman'dır. Bu, Google Drive'a kaydedilebilen, diğer kullanıcılarla paylaşılabilen ve metin ve resimlerle güncellenebilen bir birimdir.
Bir documents kaynağının üst düzey öğeleri arasında Tab, SuggestionsViewMode ve diğer özellikler bulunur:
document: {
title: ... ,
revisionId: ... ,
documentId: ... ,
suggestionsViewMode: ... ,
tabs: ...
}
Sekmeler
Tek bir dokümanda, farklı metin düzeyinde içeriklere sahip birden fazla sekme bulunabilir. Belgenin tabs özelliği, Tab nesne dizisidir. Tab aşağıdaki alanlardan oluşur:
TabProperties: Sekmenin kimlik, başlık ve dizin gibi özelliklerini içerir.childTabs: Bir sekmenin alt sekmelerini (doğrudan altında iç içe yerleştirilmiş sekmeler) gösterir.DocumentTab: Bir sekmenin metin içeriğini temsil eder.
Sonraki bölümlerde, belge sekmesi hiyerarşisine kısaca göz atılır. Sekme JSON temsili de daha ayrıntılı bilgi sağlar. Sekme özelliği hakkında daha fazla bilgi için Sekmelerle çalışma başlıklı makaleyi inceleyin.
Body içeriğinin dışındaki genel doküman sekmesi özelliklerini değiştirmek için neredeyse her zaman bir veya daha fazla doküman şablonu kullanmak daha iyidir. Bu şablonları, programatik olarak yeni dokümanlar oluşturmak için temel olarak kullanabilirsiniz. Daha fazla bilgi için Metni dokümanda birleştirme bölümüne bakın.
Gövde içeriği
Body, genellikle bir doküman sekmesinin tüm içeriğini barındırır. Programatik olarak kullanabileceğiniz veya kullanmayı isteyebileceğiniz öğelerin çoğu Body içeriğindeki öğelerdir:
Yapısal öğe
StructuralElement, dokümana yapı sağlayan içeriği tanımlar. Body içeriği, StructuralElement nesneden oluşan bir dizidir. İçerik öğesi, aşağıdaki şemada gösterildiği gibi her StructuralElement nesnesini kişiselleştirir:
Yapısal öğeler ve içerik nesneleri, dokümandaki tüm görsel bileşenleri içerir. Metin, satır içi resimler ve biçimlendirme bu kapsamdadır.
Paragraf yapısı
Paragraph, bir paragrafı temsil eden bir StructuralElement öğesidir. Yeni satır karakteriyle sonlandırılan
bir içerik yelpazesine sahiptir. Aşağıdaki nesnelerden oluşur:
ParagraphElement: Paragraftaki içeriği açıklar.ParagraphStyle: Paragrafın stil özelliklerini açıkça ayarlayan isteğe bağlı bir öğedir.Bullet: Paragraf bir listenin parçasıysa isteğe bağlı bir öğedir ve liste işareti spesifikasyonunu sağlar.
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. Çıktıda, temel yapısal ve içerik öğelerinin çoğunun yanı sıra sonraki bölümde açıklandığı gibi başlangıç ve bitiş dizelerinin kullanımını görebilirsiniz.
Metin çalıştırmaları
TextRun, tümüyle aynı metin stilinde olan bitişik bir metin dizesini temsil eden bir ParagraphElementdir. Bir paragraf birden fazla metin çalıştırması içerebilir ancak metin hiçbir zaman paragraf sınırlarını aşmaz. İçerik, ayrı metin akışları oluşturmak için yeni satır karakterinden sonra bölünür. Örneğin, aşağıdaki gibi küçük bir belgeyi ele alalım:
Aşağıdaki şemada, önceki dokümanda her biri kendi TextRun ve isteğe bağlı Bullet ayarlarına sahip paragraf sırasını nasıl görselleştirebileceğiniz gösterilmektedir.
AutoText
AutoText, metinde zaman içinde değişebilecek içerikle dinamik olarak değiştirilen bir yeri temsil eden bir ParagraphElement'tır. Dokümanlar'da bu, sayfa numaraları için kullanılır.
Başlangıç ve bitiş dizinleri
Bir dokümanın sekmesinin içeriğinde güncelleme yaptığınızda, her güncelleme belirli bir konumda veya doküman içindeki bir aralık genelinde gerçekleşir. Bu konumlar ve aralıklar, içeren doküman segmenti içindeki bir ofseti temsil eden dizinler kullanılarak belirtilir. Segment, yapısal öğeler veya içerik öğeleri içeren gövde, üstbilgi, altbilgi veya dipnottur. Bir segmentteki öğelerin dizinleri, ilgili segmentin başlangıcına göredir.
Gövde içeriğindeki öğelerin çoğu 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. Toplu Dokümanlar API çağrılarınızı nasıl sıralayacağınız hakkında daha fazla bilgi için Toplu güncellemeler bölümüne bakın.
Dizinler UTF-16 kod birimleri cinsinden ölçülür. Bu, vekil çiftlerinin iki dizin kullandığı anlamına gelir. Örneğin, "SIRıTAN YÜZ"; emoji, 😄, şu şekilde temsil edilir:
\uD83D\uDE00 ve iki indeks tüketir.
Bir doküman gövdesindeki öğeler için dizinler, "kök" öğesi olan gövde içeriğinin başlangıcından itibaren 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.
Öğelere erişim
Birçok öğe, documents.batchUpdate yöntemiyle değiştirilebilir. Örneğin, InsertTextRequest kullanarak metin içeren tüm öğelerin içeriğini değiştirebilirsiniz. Benzer şekilde, bir veya daha fazla öğede yer alan bir metin aralığına biçimlendirme uygulamak için UpdateTextStyleRequest kullanabilirsiniz.
Belgenin öğelerini okumak için documents.get yöntemini kullanarak belgenin tamamının JSON dökümünü alın. Ardından, tek tek öğelerin değerlerini bulmak için elde edilen JSON'u ayrıştırabilirsiniz. Daha fazla bilgi için Belge içeriğini JSON olarak yayınlama başlıklı makaleyi inceleyin.
İçeriği ayrıştırmak çeşitli kullanım alanları için yararlı olabilir. Örneğin, bulduğu dokümanları listeleyen bir doküman kataloglama uygulamasını düşünün. Bu uygulama, aşağıdaki şemada gösterildiği gibi bir belge sekmelerinin başlığını, düzeltme kimliğini ve başlangıç sayfası numarasını ayıklayabilir:
Bu ayarları açıkça okumak için yöntem olmadığından, uygulamanızın belgenin tamamını alması ve ardından bu değerleri ayıklamak için JSON'u ayrıştırması gerekir.
Mülkü devralma
StructuralElement, özellikleri üst nesnelerinden devralabilir. Bir nesnenin, tanımladığı ve devraldığı özellikler de dahil olmak üzere özellikleri, nihai görsel görünümünü belirler.
Metin karakteri biçimlendirmesi, metnin bir dokümanda nasıl oluşturulacağını (ör. kalın, italik ve altı çizili) belirler. Uyguladığınız biçimlendirme, temel paragrafın TextStyle öğesinden 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.
Buna karşılık, ayarlamadığınız tüm biçimlendirme özellikleri paragraf stilinden devralınmaya devam eder.