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:
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 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:
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:
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ş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:
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.