Google Dokümanlar API'yi etkili bir şekilde kullanmak için bir Google Dokümanlar belgesinin mimarisini, bir dokümanı oluşturan öğeleri ve bunların 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.
documents kaynağının üst düzey öğeleri Tab'lerini, SuggestionsViewMode'ı ve diğer özelliklerini içerir:
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 nesnelerinin bir 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 Belgeleri birleştirme başlıklı makaleyi inceleyin.
Gövde içeriği
Body genellikle bir belgenin sekmesinin tüm içeriğini içerir. Programatik olarak kullanabileceğiniz veya kullanmak 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 nesnesi dizisidir. İç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 dizisi vardır. Aşağıdaki nesnelerden oluşur:
ParagraphElement: Bir 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:
Tam bir belge yapısı örneği için JSON biçimindeki belge ö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 satırı içerebilir ancak metin satırı 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 paragrafların 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 sekmesindeki içerikte yaptığınız her güncelleme, doküman içinde bir konumda veya bir aralıkta gerçekleşir. Bu konumlar ve aralıklar, içeren doküman segmentindeki bir ofseti temsil eden dizinler kullanılarak belirtilir. Segment, yapısal veya içerik öğeleri içeren gövde, üstbilgi, altbilgi ya da 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 öğenin başlangıç ve sonunun, kapsayıcı segmentinin başlangıcına göre ofsetini belirtir. 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.
Yapısal öğeler için "kişiselleştirme" türleri (SectionBreak,
TableOfContents,
Table ve
Paragraph), bunları içeren StructuralElement öğelerinde bu alanlar bulunduğundan bu dize dizinlerine sahip değildir. Bu durum, ParagraphElement içinde bulunan kişiselleştirme türleri (ör. TextRun, AutoText ve PageBreak) 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 bulunan 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 belgenin sekmelerinin başlığını, düzeltme kimliğini ve başlangıç sayfa numarasını ayıklayabilir:
Bu ayarları açıkça okumak için yöntem olmadığından, uygulamanızın bu değerleri ayıklamak için dokümanın tamamını alması ve ardından JSON'u ayrıştırması gerekir.
Mülkü devralma
StructuralElement, üst nesnelerinden özellik alabilir. 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 tüm karakterler paragrafın stillerinden devralmaya devam eder.
Paragraf biçimlendirmesi, metin bloklarının bir belgede nasıl oluşturulacağı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.