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

Google Docs API'yi etkili bir şekilde kullanmak için Google Dokümanlar dokümanının mimarisini, dokümanı oluşturan öğeleri ve bunlar arasındaki ilişkiyi anlamanız gerekir. Bu sayfada, söz konusu konuların 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'da en dıştaki kapsayıcı öğe bir dokümandır. Bu birim Google Drive'a kaydedilebilir, diğer kullanıcılarla paylaşılabilir, metin ve resimlerle güncellenebilir.

Bir documents kaynağının üst düzey öğeleri Body, Header, Footer ve diğer birçok özelliği içerir:

document: {
    body: ... ,
    documentStyle: ... ,
    lists: ... ,
    documentId: ... ,
    namedStyles: ... ,
    revisionId: ... ,
    title: ...
}

Body içeriği dışındaki genel doküman özelliklerini değiştirmek için, programatik olarak yeni dokümanlar oluşturmak için temel olarak kullanabileceğiniz bir veya daha fazla doküman şablonu kullanmak neredeyse her zaman daha iyidir. Daha fazla bilgi için Metni bir dokümanda birleştirme bölümüne bakın.

Gövde içeriği

Body genellikle doküman içeriğinin tamamını içerir. Programatik olarak kullanabileceğiniz veya muhtemelen kullanmak isteyeceğiniz öğelerin çoğu Body içeriğinde yer alır:

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

Yapısal öğe

StructuralElement, belgeye yapı sağlayan içeriği tanımlar. Body içeriği, StructuralElement nesne dizisidir. Bir içerik öğesi, aşağıdaki şemada gösterildiği gibi her StructuralElement nesnesini kişiselleştirir:

Yapısal öğeler.
Şekil 2. Yapısal öğeler.

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 de dahildir.

Paragraf yapısı

Paragraph, bir paragrafı temsil eden StructuralElement simgesidir. Bir yeni satır karakteriyle sonlandırılan bir dizi içeriğe sahiptir. Aşağıdaki nesnelerden oluşur:

  • ParagraphElement: Bir paragraftaki içeriği açıklar.
  • ParagraphStyle: Paragraf için stil özelliklerini açık bir şekilde ayarlayan isteğe bağlı bir öğe.
  • Bullet: Paragraf bir listenin parçasıysa madde işareti spesifikasyonunu sağlayan isteğe bağlı bir öğe.

ParagraphElement, StructuralElement gibi çalışır. İçerik öğesi türleri grubu (ColumnBreak ve Equation gibi), aşağıdaki şemada gösterildiği gibi kendi ParagraphElement öğesini kişiselleştirir:

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

Eksiksiz bir belge yapısı örneği için JSON biçimindeki doküman örneğine bakın. Çıkışta, birçok temel yapısal ve içerik öğesinin yanı sıra aşağıdaki bölümde açıklandığı gibi başlangıç ve bitiş dizinlerinin kullanımını görebilirsiniz.

Metin çalıştırmaları

TextRun, tamamen aynı metin stiline sahip bitişik bir metin dizesini temsil eden bir ParagraphElement simgesidir. Bir paragraf birden fazla metin çalıştırması içerebilir ancak metinler hiçbir zaman paragraf sınırlarını aşmaz. İçerikler, ayrı metin çalıştırmaları oluşturmak için bir yeni satır karakterinden sonra bölünür. Örneğin, aşağıdaki gibi küçük bir dokümanı ele alalım:

Paragraflar ve madde işaretli liste içeren küçük doküman.
Şekil 4. 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.

Bir metin çalıştırmanın yapısı.
Şekil 5. Bir metin çalıştırmanın yapısı.

AutoText

AutoText, metinde zaman içinde değişebilen içeriklerle dinamik olarak değiştirilen bir alanı temsil eden ParagraphElement öğesidir. Dokümanlar'da bu, sayfa numaraları için kullanılır.

Başlangıç ve bitiş dizinleri

Bir dokümanın içeriğinde güncelleme yaptığınızda, her güncelleme belge içindeki bir konumda veya bir aralıkta gerçekleşir. Bu konumlar ve aralıklar, içeren belge segmenti içindeki bir ofseti temsil eden dizinler kullanılarak belirtilir. Segment, yapısal veya içerik öğeleri içeren gövde, üstbilgi, altbilgi veya dipnottur. Bir segment içindeki öğ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 çevreleyen segmentin başlangıcına göre başlangıç ve bitişinin uzaklığını gösterir. Docs API çağrılarınızı toplu olarak nasıl sipariş edeceğiniz hakkında daha fazla bilgi için Toplu güncellemeler bölümüne bakın.

Dizinler UTF-16 kod birimleri olarak ölçülür. Bu, vekil çiftlerinin iki dizin tükettiği anlamına gelir. Örneğin "GRINNING FACE" emojisi 😄 \uD83D\uDE00 olarak gösterilir ve iki dizin tüketir.

Bir belge gövdesindeki öğeler için dizinler, "kök" öğe olan gövde içeriğinin başlangıcından itibaren ofsetleri temsil eder.

Yapısal öğelerin "kişiselleştirme" türlerinde (SectionBreak, TableOfContents, Table ve Paragraph), kendilerini kapsayan StructuralElement alanları bu alanlara sahip olduğundan bu dizinler yoktur. 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öntemi ile 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 yer alan bir metin aralığına biçimlendirme uygulamak için UpdateTextStyleRequest kullanabilirsiniz.

Belgenin öğelerini okumak için belgenin tamamının JSON dökümünü almak için documents.get yöntemini kullanın. Daha sonra, tek tek öğelerin değerlerini bulmak için sonuç JSON dosyasını ayrıştırabilirsiniz. Daha fazla bilgi için Doküman içeriklerini JSON olarak çıkış 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 uygulama belgelerini kataloglayan bir belgeyi düşünün. Bu uygulama, aşağıdaki şemada gösterildiği gibi bir dokümanın başlığını, düzeltme kimliğini ve başlangıç sayfası numarasını çıkarabilir:

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

Bu ayarları açıkça okumak için herhangi bir yöntem bulunmadığından, uygulamanızın tüm belgeyi alması ve ardından bu değerleri çıkarmak için JSON'u ayrıştırması gerekir.

Mülkten devralınan izinler

Bir StructuralElement, mülkleri üst nesnelerinden devralabilir. Bir nesnenin tanımladığı ve devraldığı özellikler dahil olmak üzere özellikleri, nesnenin son 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, bir dokümanda hizalama, kenarlıklar ve girinti gibi metin bloklarının nasıl oluşturulduğunu 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.