Google Docs API'yi etkili bir şekilde kullanmak için Google Dokümanları dokümanının mimarisini, dokümanı oluşturan öğeleri ve aralarındaki ilişkiyi anlamanız gerekir. Bu sayfada aşağıdaki konularla ilgili 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 kaydedilebilir, diğer kullanıcılarla paylaşılabilir ve metinler ile resimlerle güncellenebilir.
Bir documents kaynağının üst düzey öğeleri, Tab, SuggestionsViewMode ve diğer özellikleri içerir:
document: {
title: ... ,
revisionId: ... ,
documentId: ... ,
suggestionsViewMode: ... ,
tabs: ...
}
Sekmeler
Tek bir doküman, farklı metin düzeyinde içeriklere sahip birden fazla sekme içerebilir. Belgenin tabs özelliği, Tab nesnelerinin sırasıdır. Tab aşağıdaki alanlardan oluşur:
TabProperties: Kimlik, başlık ve dizin gibi bir sekmenin özelliklerini içerir.childTabs: Bir sekmenin alt sekmelerini (doğrudan altına yerleştirilmiş sekmeler) gösterir.DocumentTab: Bir sekmenin metin içeriğini gösterir.
Sonraki bölümlerde, doküman sekmesi hiyerarşisine kısa bir genel bakış sunulmaktadır. Tab JSON gösterimi de daha ayrıntılı bilgi sağlar. Sekmeler özelliği hakkında daha fazla bilgi için Sekmelerle çalışma başlıklı makaleyi inceleyin.
Genel doküman sekmesi özelliklerini Body içeriği dışında kullanmak için yeni dokümanları programatik olarak oluştururken temel olarak kullanabileceğiniz bir veya daha fazla doküman şablonu kullanmak neredeyse her zaman daha iyidir. Daha fazla bilgi için Metni belgeye birleştirme başlıklı makaleyi inceleyin.
Gövde içeriği
Body genellikle bir dokümanın sekmesinin tüm içeriğini içerir. Programatik olarak kullanabileceğiniz veya kullanmak isteyeceğiniz öğelerin çoğu Body içeriğindeki öğelerdir:
Yapısal öğe
StructuralElement, dokümana yapı kazandıran içeriği tanımlar. Body içeriği, StructuralElement nesnelerden 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 içerik nesneleri, dokümandaki tüm görsel bileşenleri içerir. Metin, satır içi resimler ve biçimlendirme buna dahildir.
Paragraf yapısı
Paragraph, bir paragrafı temsil eden StructuralElement türüdür. Yeni satır karakteriyle sonlandırılan bir dizi içerik barındırıyor. 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 öğe.Bullet: Paragraf bir listenin parçasıysa madde işareti belirtimini sağlayan isteğe bağlı bir öğe.
ParagraphElement, StructuralElement gibi çalışır. Bir dizi içerik öğesi türü (ö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 birçoğunun yanı sıra sonraki bir bölümde açıklanan başlangıç ve bitiş dizinlerinin kullanımını görebilirsiniz.
Metin çalıştırmaları
TextRun, ParagraphElement
olan ve aynı metin stiline sahip bitişik bir metin dizesini temsil eden bir öğedir. Bir paragraf birden fazla metin çalıştırması içerebilir ancak metin çalıştırmaları hiçbir zaman paragraf sınırlarını aşmaz. İçerikler, ayrı metin çalıştırmaları oluşturmak için yeni satır karakterinden sonra bölünür. Örneğin, aşağıdaki gibi küçük bir dokümanı ele alalım:
Aşağıdaki şemada, önceki dokümandaki paragrafların sırasını nasıl görselleştirebileceğiniz gösterilmektedir. Her paragrafın kendi TextRun ve isteğe bağlı Bullet ayarları vardır.
AutoText
AutoText, metinde zaman içinde değişebilen içerikle dinamik olarak değiştirilen bir noktayı temsil eden bir ParagraphElement'dir. Dokümanlar'da bu özellik sayfa numaraları için kullanılır.
Başlangıç ve bitiş dizinleri
Bir dokümanın sekmesindeki içerikte güncelleme yaptığınızda her güncelleme, dokümandaki bir konumda veya bir aralıkta gerçekleşir. Bu konumlar ve aralıklar, dizinler kullanılarak belirtilir. Dizinler, kapsayan bir doküman segmentindeki bir uzaklığı temsil eder. Segment, yapısal veya içerik öğeleri içeren gövde, üstbilgi, altbilgi ya da dipnottur. Bir segmentteki öğelerin dizinleri, söz konusu segmentin başlangıcına göre belirlenir.
Gövde içeriğindeki çoğu öğe sıfır tabanlı startIndex ve endIndex özelliklerine sahiptir. Bunlar, bir öğenin başlangıcının ve bitişinin, kapsayan segmentinin başlangıcına göre olan uzaklığını gösterir. Toplu Docs API çağrılarınızı sıralama hakkında daha fazla bilgi için Toplu
güncellemeler bölümüne bakın.
Dizinler UTF-16 kod birimleriyle ölçülür. Bu, vekil çiftlerinin iki dizin kullandığı anlamına gelir. Örneğin, "Sırıtan Yüz" emojisi 😄,
\uD83D\uDE00 olarak temsil edilir ve iki indeks tüketir.
Bir doküman gövdesindeki öğeler için dizinler, gövde içeriğinin başlangıcından itibaren olan uzaklıkları temsil eder. Bu uzaklıklar, "kök" öğe olarak kabul edilir.
Yapısal öğeler için "kişiselleştirme" türleri (SectionBreak, TableOfContents, Table ve Paragraph) bu dizinlere sahip değildir. Çünkü bunları içeren StructuralElement öğesinde bu alanlar bulunur. Bu durum, ParagraphElement içinde yer alan kişiselleştirme türleri (ör. TextRun, AutoText ve PageBreak) için de geçerlidir.
Erişim öğeleri
Birçok öğe, documents.batchUpdate yöntemiyle değiştirilebilir. Örneğin, InsertTextRequest kullanarak metin içeren herhangi bir öğenin 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, sonuçtaki JSON'ı ayrıştırarak tek tek öğelerin değerlerini bulabilirsiniz. Daha fazla bilgi için Çıkış belgesi içeriğini JSON olarak bölümüne bakın.
İçeriğin ayrıştırılması çeşitli kullanım alanları için faydalı olabilir. Örneğin, bulduğu dokümanları listeleyen bir doküman kataloglama uygulamasını ele alalım. Bu uygulama, aşağıdaki şemada gösterildiği gibi bir dokümanın sekmelerinin başlığını, düzeltme kimliğini ve başlangıç sayfa numarasını ayıklayabilir:
Bu ayarları açıkça okumak için herhangi bir yöntem olmadığından uygulamanızın, bu değerleri ayıklamak için önce belgenin tamamını alması ve ardından JSON'ı ayrıştırması gerekir.
Mülkü devralma
Bir StructuralElement, özellikleri üst nesnelerinden devralabilir. Bir nesnenin tanımladığı ve devraldığı özellikler dahil olmak üzere nesnenin özellikleri, son görsel görünümünü belirler.
Metin karakteri biçimlendirmesi, metnin bir belgede nasıl oluşturulacağını belirler. Örneğin, kalın, italik ve altı çizili. 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 stillerini devralmaya devam eder.
Paragraf biçimlendirmesi, metin bloklarının bir belgede nasıl oluşturulacağını belirler. Örneğin, hizalama, kenarlıklar ve girinti. Uyguladığınız biçimlendirme, temel ParagraphStyle öğesinden devralınan varsayılan biçimlendirmeyi geçersiz kılar.
Aksine, ayarlamadığınız tüm biçimlendirme özellikleri paragraf stilinden devralınmaya devam eder.