Sekmelerle çalışma

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:

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:

Bazılarında alt sekmeler bulunan üç üst düzey sekme içeren sekme listesi kullanıcı arayüzü

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ırsa documents.get yöntemi, document.tabs alanının doldurulduğu bir Document kaynağı döndürür. Doğrudan document'te bulunan tüm metin alanları (ör. document.body) boş bırakılır.
  • includeTabsContent sağlanmazsa Document 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.

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ı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 ait tüm dahili bağlantılar link.bookmarkId ve link.headingId olarak gösterilmeye devam eder. Birden fazla sekme içeren belgelerde dahili bağlantılar link.bookmark ve link.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();
}