Google Dokümanlar API, dokümandaki herhangi bir sekmedeki içeriğe erişmenize olanak tanır.
Sekmeler nedir?
Google Dokümanlar'da sekmeler adlı bir kuruluş katmanı bulunur. Dokümanlar, kullanıcıların tek bir doküman içinde bir veya daha fazla sekme oluşturmasına olanak tanır. Bu, E-Tablolar'daki sekmelerin işlevine benzer. Her sekmenin kendi başlığı ve kimliği (URL'ye eklenir) vardır. Sekmelerin alt sekmeleri de olabilir. Bunlar, başka bir sekmenin altına yerleştirilmiş sekmelerdir.
Doküman içeriğinin Doküman Kaynağı'nda gösterilme şekliyle ilgili yapısal değişiklikler
Eskiden belgelerde sekme kavramı yoktu. Bu nedenle, Document
kaynağı, aşağıdaki alanlar aracılığıyla tüm metin içeriklerini doğrudan içeriyordu:
document.body
document.headers
document.footers
document.footnotes
document.documentStyle
document.suggestedDocumentStyleChanges
document.namedStyles
document.suggestedNamedStylesChanges
document.lists
document.namedRanges
document.inlineObjects
document.positionedObjects
Sekmelerin ek yapısal hiyerarşisi sayesinde bu alanlar artık dokümandaki tüm sekmelerdeki metin içeriğini anlamsal olarak temsil etmiyor. Metin tabanlı içerik artık farklı bir katmanda gösteriliyor. Google Dokümanlar'daki sekme özelliklerine ve içeriğine document.tabs
ile erişilebilir. document.tabs
, her biri yukarıda belirtilen metin içerik alanlarının tümünü içeren Tab
nesnelerinin bir listesidir. Sonraki bölümlerde kısa bir genel bakış sunulur. Sekme JSON temsili de daha ayrıntılı bilgi sağlar.
Sekme özelliklerine erişme
Sekmenin kimliği, başlığı ve konumu gibi bilgileri içeren tab.tabProperties
öğesini kullanarak sekme özelliklerine erişin.
Sekme içindeki metin içeriğine erişme
Sekmedeki gerçek belge içeriği tab.documentTab
olarak gösterilir.
Yukarıda belirtilen metin içeriği alanlarının tümüne tab.documentTab
kullanılarak erişilebilir. Örneğin, document.body
yerine document.tabs[indexOfTab].documentTab.body
kullanmalısınız.
Sekme hiyerarşisi
Alt sekmeler, API'de Tab
üzerinde tab.childTabs
alanı olarak temsil edilir. Bir dokümandaki tüm sekmelere erişmek için alt sekmelerin "ağacını" incelemeniz gerekir. Örneğin, aşağıdaki sekme hiyerarşisini içeren bir doküman düşünün:
3.1.2 sekmesinden Body
öğesini almak için document.tabs[2].childTabs[0].childTabs[1].documentTab.body
öğesine erişirsiniz. Bir dokümandaki tüm sekmeler arasında iterasyon için örnek kod sağlayan sonraki bölümdeki örnek kod bloklarına bakın.
Yöntemlerde yapılan değişiklikler
Sekmelerin kullanıma sunulmasıyla birlikte, doküman yöntemlerinin her birinde kodunuzu güncellemenizi gerektirebilecek birkaç değişiklik yapıldı.
documents.get
Varsayılan olarak, tüm sekme içerikleri döndürülmez. Geliştiriciler, tüm sekmelere erişmek için kodlarını güncellemelidir. documents.get
yöntemi, yanıtta tüm sekmelerdeki içeriklerin sağlanıp sağlanmayacağını yapılandırmayı sağlayan bir includeTabsContent
parametresi gösterir.
includeTabsContent
,true
olarak ayarlanırsadocuments.get
yöntemi,document.tabs
alanının doldurulduğu birDocument
kaynağı döndürür. Doğrudandocument
'te bulunan tüm metin alanları (ör.document.body
) boş bırakılır.includeTabsContent
sağlanmazsaDocument
kaynağındaki (ör.document.body
) metin alanları yalnızca ilk sekmedeki içerikle doldurulur.document.tabs
alanı boş olur ve diğer sekmelerdeki içerikler döndürülmez.
documents.create
documents.create
yöntemi, oluşturulan boş belgeyi temsil eden bir Document
kaynağı döndürür. Döndürülen Document
kaynağı, hem dokümanın metin içerik alanlarında hem de document.tabs
'da boş doküman içeriklerini doldurur.
document.batchUpdate
Her Request
, güncellemenin uygulanacağı sekmeleri belirtme yöntemi içerir. Varsayılan olarak, bir sekme belirtilmezse Request
çoğu durumda dokümandaki ilk sekmeye uygulanır.
ReplaceAllTextRequest
,
DeleteNamedRangeRequest
ve
ReplaceNamedRangeContentRequest
, varsayılan olarak tüm sekmelere uygulanacak üç özel istektir.
Ayrıntılar için Request
dokümanlarını inceleyin.
Dahili bağlantılarda yapılan değişiklikler
Kullanıcılar, bir dokümanda sekmelere, yer işaretlerine ve başlıklara dahili bağlantılar oluşturabilir.
Sekme özelliğinin kullanıma sunulmasıyla birlikte, Link
kaynağındaki link.bookmarkId
ve link.headingId
alanları artık dokümanda belirli bir sekmedeki yer işaretini veya başlığı temsil edemez.
Geliştiriciler, kodlarını okuma ve yazma işlemlerinde link.bookmark
ve link.heading
kullanacak şekilde güncellemelidir. Her biri yer işaretinin veya başlığın kimliğini ve bulunduğu sekmenin kimliğini içeren BookmarkLink
ve HeadingLink
nesnelerini kullanarak dahili bağlantıları gösterirler. Ayrıca link.tabId
, sekmelerin dahili bağlantılarını da gösterir.
documents.get
yanıtının bağlantı içerikleri de includeTabsContent
parametresine bağlı olarak değişiklik gösterebilir:
includeTabsContent
,true
değerine ayarlanırsa tüm dahili bağlantılarlink.bookmark
velink.heading
olarak gösterilir. Eski alanlar artık kullanılmayacak.includeTabsContent
sağlanmazsa tek sekme içeren dokümanlarda, bu tek sekmedeki yer işaretlerine veya başlıklara ait tüm dahili bağlantılarlink.bookmarkId
velink.headingId
olarak gösterilmeye devam eder. Birden fazla sekme içeren belgelerde dahili bağlantılarlink.bookmark
velink.heading
olarak gösterilir.
document.batchUpdate
'te, eski alanlardan biri kullanılarak dahili bir bağlantı oluşturulursa yer işaretinin veya başlığın, Request
'te belirtilen sekme kimliğinden geldiği kabul edilir. Hiçbir sekme belirtilmezse belgedeki ilk sekmeden alındığı kabul edilir.
Bağlantı JSON temsili daha ayrıntılı bilgi sağlar.
Sekmelerin yaygın kullanım kalıpları
Aşağıdaki kod örneklerinde, sekmelerle etkileşime geçmenin çeşitli yolları açıklanmaktadır.
Belgedeki tüm sekmelerden sekme içeriğini okuma
Sekmeler özelliğinden önce bunu yapan mevcut kod, includeTabsContent
parametresini true
olarak ayarlayarak, sekmeler ağaç hiyerarşisini gezerek ve Document
yerine Tab
ve DocumentTab
üzerinden alıcı yöntemleri çağırarak sekmeleri desteklemek üzere taşınabilir. Aşağıdaki kısmi kod örneği, Bir dokümandan metin ayıklama başlıklı makaledeki snippet'i temel alır. Bu eğitimde, bir dokümandaki her sekmedeki metin içeriklerinin tamamının nasıl yazdırılacağını gösterilmektedir. Bu sekme geçiş kodu, sekmelerin gerçek yapısıyla ilgilenmeyen diğer birçok kullanım alanına uyarlanabilir.
Java
/** Prints all text contents from all tabs in the document. */ static void printAllText(Docs service, String documentId) throws IOException { // Fetch the document with all of the tabs populated, including any nested // child tabs. Document doc = service.documents().get(documentId).setIncludeTabsContent(true).execute(); List<Tab> allTabs = getAllTabs(doc); // Print the content from each tab in the document. for (Tab tab: allTabs) { // Get the DocumentTab from the generic Tab. DocumentTab documentTab = tab.getDocumentTab(); System.out.println( readStructuralElements(documentTab.getBody().getContent())); } } /** * Returns a flat list of all tabs in the document in the order they would * appear in the UI (top-down ordering). Includes all child tabs. */ private List<Tab> getAllTabs(Document doc) { List<Tab> allTabs = new ArrayList<>(); // Iterate over all tabs and recursively add any child tabs to generate a // flat list of Tabs. for (Tab tab: doc.getTabs()) { addCurrentAndChildTabs(tab, allTabs); } return allTabs; } /** * Adds the provided tab to the list of all tabs, and recurses through and * adds all child tabs. */ private void addCurrentAndChildTabs(Tab tab, List<Tab> allTabs) { allTabs.add(tab); for (Tab tab: tab.getChildTabs()) { addCurrentAndChildTabs(tab, allTabs); } } /** * Recurses through a list of Structural Elements to read a document's text * where text may be in nested elements. * * <p>For a code sample, see * <a href="https://developers.google.com/workspace/docs/api/samples/extract-text">Extract * the text from a document</a>. */ private static String readStructuralElements(List<StructuralElement> elements) { ... }
Dokümandaki ilk sekmedeki sekme içeriğini okuma
Bu, tüm sekmelerin okunmasına benzer.
Java
/** Prints all text contents from the first tab in the document. */ static void printAllText(Docs service, String documentId) throws IOException { // Fetch the document with all of the tabs populated, including any nested // child tabs. Document doc = service.documents().get(documentId).setIncludeTabsContent(true).execute(); List<Tab> allTabs = getAllTabs(doc); // Print the content from the first tab in the document. Tab firstTab = allTabs.get(0); // Get the DocumentTab from the generic Tab. DocumentTab documentTab = firstTab.getDocumentTab(); System.out.println( readStructuralElements(documentTab.getBody().getContent())); }
İlk sekmeyi güncelleme isteği gönderme
Aşağıdaki kısmi kod örneğinde, Request
içinde belirli bir sekmenin nasıl hedefleneceği gösterilmektedir.
Bu kod, Metin ekleme, silme ve taşıma kılavuzundaki örneğe dayanır.
Java
/** Inserts text into the first tab of the document. */ static void insertTextInFirstTab(Docs service, String documentId) throws IOException { // Get the first tab's ID. Document doc = service.documents().get(documentId).setIncludeTabsContent(true).execute(); Tab firstTab = doc.getTabs().get(0); String tabId = firstTab.getTabProperties().getTabId(); List<Request>requests = new ArrayList<>(); requests.add(new Request().setInsertText( new InsertTextRequest().setText(text).setLocation(new Location() // Set the tab ID. .setTabId(tabId) .setIndex(25)))); BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests); BatchUpdateDocumentResponse response = docsService.documents().batchUpdate(DOCUMENT_ID, body).execute(); }