Google Dokümanlar dokümanının yapısı

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
bölümünde açıklanan yardımcı programı kullanabilirsiniz.

Ü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.
Bir dokümanın sekmelerinin yapısı.
Şekil 1. Bir dokümanın sekmelerinin yapısı.

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 kullanmayı isteyebileceğiniz öğelerin çoğu Body içeriğindeki öğelerdir:

Gövde içeriğinin yapısı.
Şekil 2. Gövde içeriğinin yapısı.

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.
Şekil 3. Yapısal öğeler.

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: 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 liste öğelerini belirten isteğe bağlı bir öğedir.

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:

Paragraf öğelerinin yapısı.
Şekil 4. Paragraf öğelerinin yapısı.

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:

Paragraflar ve madde işaretli liste içeren küçük bir doküman.
Şekil 5. Küçük bir doküman.

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.

Metin satırının yapısı.
Şekil 6. Metin satırının yapısı.

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 segmenti içindeki 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 çoğu öğe, 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ılandırılmış öğeler için "kişiselleştirme" türleri (SectionBreak, TableOfContents, Table ve Paragraph), bunları içeren StructuralElement öğelerinde bu alanlar bulunduğundan bu dizelerde bulunmaz. 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 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:

Doküman kataloğunun yapısı.
Şekil 7. Doküman kataloğunun yapısı.

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.