Sekmelerle çalışma

Google Dokümanlar API'si, dokümandaki herhangi bir sekmedeki içeriğe erişmenizi sağlar.

Sekmeler nedir?

Google Dokümanlar'da sekmeler adlı bir düzenleme katmanı bulunur. Dokümanlar, kullanıcıların tek bir dokümanda bir veya daha fazla sekme oluşturmasına olanak tanır. Bu özellik, E-Tablolar'daki sekmelere benzer. Her sekmenin kendi başlığı ve kimliği (URL'ye eklenir) vardır. Sekmelerin alt sekmeleri de olabilir. Alt sekmeler, başka bir sekmenin altında iç içe yerleştirilmiş sekmelerdir.

Doküman içeriğinin Doküman Kaynağı'nda gösterilme şekliyle ilgili yapısal değişiklikler

Geçmişte dokümanlarda sekmeler yoktu. Bu nedenle, Document Kaynak doğrudan aşağıdaki alanlar aracılığıyla tüm metin içeriklerini barındırıyordu:

• 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şisiyle birlikte bu alanlar artık dokümandaki tüm sekmelerden gelen metin içeriğini anlamsal olarak temsil etmiyor. Metin tabanlı içerik artık farklı bir katmanda gösteriliyor. Google Dokümanlar'daki tablo özellikleri ve içeriklerine document.tabs ile erişilebilir. Bu, her biri yukarıda bahsedilen tüm metin içeriği alanlarını içeren Tab nesnelerinin listesidir. Sonraki bölümlerde kısa bir genel bakış sunulmaktadır. Tab JSON gösterimi 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 kullanarak sekme özelliklerine erişin.

Sekmedeki metin içeriğine erişme

Sekmedeki gerçek belge içeriği tab.documentTab olarak gösterilir. Yukarıda belirtilen tüm metin içeriği alanlarına 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 gösterilir. Bir dokümandaki tüm sekmelere erişmek için alt sekmelerin "ağacında" gezinmek gerekir. Örneğin, aşağıdaki gibi bir sekme hiyerarşisi içeren bir dokümanı ele alalım:

Body değerini Tab 3.1.2'den almak için document.tabs[2].childTabs[0].childTabs[1].documentTab.body'a erişmeniz gerekir. Bir dokümandaki tüm sekmelerde yineleme yapmak için örnek kod sağlayan sonraki bölümdeki örnek kod bloklarına bakın.

Yöntemlerdeki 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üncellemeli. documents.get yöntemi, tüm sekmelerdeki içeriklerin yanıtta sağlanıp sağlanmayacağını yapılandırmaya olanak tanıyan bir includeTabsContent parametresini kullanıma sunar.

• includeTabsContent, true olarak ayarlanırsa documents.get yöntemi, document.tabs alanı doldurulmuş bir Document kaynağı döndürür. document üzerindeki tüm metin alanları (ör. document.body) boş bırakılır.
• includeTabsContent sağlanmazsa Document kaynağındaki metin alanları (ör. document.body) 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ş dokümanı temsil eden bir Document kaynağı döndürür. Döndürülen Document Kaynağı, hem dokümanın metin içeriği alanlarındaki hem de document.tabs içindeki boş doküman içeriklerini doldurur.

document.batchUpdate

Her Request, güncellemenin uygulanacağı sekmeleri belirtmenin bir yolunu içerir. Varsayılan olarak, sekme belirtilmezse Request çoğu durumda belgedeki ilk sekmeye uygulanır. ReplaceAllTextRequest, DeleteNamedRangeRequest, ve ReplaceNamedRangeContentRequest tüm sekmelere uygulanacak şekilde varsayılan olarak ayarlanacak üç özel istektir.

Ayrıntılı bilgi için Requests dokümanlarına bakın.

Dahili bağlantılarda yapılan değişiklikler

Kullanıcılar, bir dokümandaki sekmelere, yer işaretlerine ve başlıklara dahili bağlantılar oluşturabilir. Sekmeler özelliğinin kullanıma sunulmasıyla birlikte, Link kaynağındaki link.bookmarkId ve link.headingId alanları artık dokümandaki belirli bir sekmede yer işareti veya başlık olarak kullanılamaz.

Geliştiriciler, okuma ve yazma işlemlerinde link.bookmark ve link.heading kullanmak için kodlarını güncellemelidir. Bunlar, her biri yer işareti veya başlığın kimliğini ve bulunduğu sekmenin kimliğini içeren BookmarkLink ve HeadingLink nesnelerini kullanarak dahili bağlantıları gösterir. Ayrıca link.tabId, sekmelere yönelik dahili bağlantıları da gösterir.

documents.get yanıtının bağlantı içerikleri, includeTabsContent parametresine bağlı olarak da değişebilir:

• includeTabsContent, true olarak ayarlanırsa tüm dahili bağlantılar link.bookmark ve link.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 yönelik tüm dahili bağlantılar link.bookmarkId ve link.headingId olarak gösterilmeye devam eder. Birden fazla sekme içeren dokümanlarda, dahili bağlantılar link.bookmark ve link.heading olarak gösterilir.

document.batchUpdate içinde, eski alanlardan biri kullanılarak bir dahili bağlantı oluşturulursa yer işareti veya başlık, Request içinde belirtilen sekme kimliğinden alınmış olarak kabul edilir. Sekme belirtilmemişse belgedeki ilk sekmeden alındığı kabul edilir.

JSON bağlantısı gösterimi daha ayrıntılı bilgi sağlar.

Sekmelerin yaygın kullanım şekilleri

Aşağıdaki kod örneklerinde, sekmelerle etkileşime geçmenin çeşitli yolları açıklanmaktadır.

Belgedeki tüm sekmelerin içeriklerini okuma

Sekmeler özelliği öncesinde bu işlemi yapan mevcut kod, includeTabsContent parametresi true olarak ayarlanarak, sekmeler ağacı hiyerarşisi geçilerek ve Document yerine Tab ve DocumentTab üzerinden getter yöntemleri çağrılarak sekmeleri destekleyecek şekilde taşınabilir. Aşağıdaki kısmi kod örneği, Belgeden metin ayıklama bölümündeki snippet'e dayanmaktadır. Bir dokümandaki her sekmedeki tüm metin içeriklerinin nasıl yazdırılacağını gösterir. Bu sekme geçişi kodu, sekmelerin gerçek yapısını önemsemeyen birçok başka kullanım alanına da uyarlanabilir.

/** 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 sekmeden sekme içeriğini okuma

Bu, tüm sekmelerin okunmasına benzer.

/** 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ğinde bulunma

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 dayanmaktadır.

/** 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();
}