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

Geçmişte 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, her biri yukarıda belirtilen tüm metin içerik alanlarının bulunduğu Tab nesnelerinin listesi olan document.tabs ile erişilebilir. Sonraki bölümlerde kısa bir genel bakış sunulmaktadır. Sekme JSON temsili bölümünde de daha ayrıntılı bilgi verilmektedir.

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 belgedeki 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 belgeyi ele alalım:

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, tüm sekmelerdeki içeriklerin yanıtta 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 üzerinde 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ş dokümanı 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 belirtmenin bir yolunu 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ümandaki 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 belgedeki 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. Bunlar, 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österir. Ayrıca link.tabId, sekmelerin dahili bağlantılarını da gösterir.

documents.get yanıtının bağlantı içerikleri, includeTabsContent parametresine göre de 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 bir 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 dokümanlarda dahili bağlantılar link.bookmark ve link.heading olarak gösterilir.

document.batchUpdate'te eski alanlardan biri kullanılarak oluşturulan dahili bağlantılarda yer işareti veya başlığın, Request'te belirtilen sekme kimliğinden geldiği kabul edilir. Sekme belirtilmezse dokümandaki ilk sekmeden alındığı varsayılır.

Bağlantı JSON gösterimi 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, Belgeden metin ayıklama başlıklı makaledeki snippet'ten alınmıştı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 gezinme 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/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();
}