Sekmelerle çalışma

Google Dokümanlar için Apps Komut Dosyası, 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ümanda 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.

Sekmelere erişme

Sekme özelliklerine ve içeriğine Document.getTabs() ile erişilebilir. Bu işlev, Tab öğelerinin listesini döndürür. Sonraki bölümlerde Tab sınıfına kısaca göz atılır. Sekme sınıfı dokümanları da daha ayrıntılı bilgi sağlar.

Sekme özellikleri

Sekme özellikleri, Tab.getId() ve Tab.getTitle() gibi yöntemler kullanılarak alınabilir.

Sekme içerikleri

Her sekmedeki doküman içeriği Tab.asDocumentTab() kullanılarak alınabilir. Belge sınıfı yapısında yapılan değişiklikler bölümünde bu özelliğin nasıl kullanılabileceği açıklanmaktadır.

Sekme hiyerarşisi

Alt sekmeler, Google Apps Komut Dosyası'nda Tab.getChildTabs() aracılığıyla gösterilir. Tüm sekmelerdeki içeriğe 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 sekmesine erişmek için şunları yapabilirsiniz:

// Print the ID of Tab 3.1.2.
const doc = DocumentApp.getActiveDocument();
const tab = doc.getTabs()[2].getChildTabs()[0].getChildTabs()[1];
console.log(tab.getId());

Bir belgedeki tüm sekmeler arasında iterasyon için örnek kod sağlayan sonraki bölümlerdeki örnek kod bloklarına bakın.

Sekmeleri almayla ilgili diğer yöntemler

Sekmeleri almak için başka iki yöntem daha vardır:

  • Document.getTab(tabId): Belirtilen kimliğe sahip sekmeyi döndürür.
  • Document.getActiveTab(): Kullanıcının etkin sekmesini döndürür. Yalnızca bir dokümana bağlı komut dosyalarında çalışır. Bu konu, sonraki bölümlerde daha ayrıntılı olarak açıklanmaktadır.

Doküman sınıfı yapısında yapılan değişiklikler

Geçmişte dokümanlarda sekme kavramı yoktu. Bu nedenle, Document sınıfı, dokümanın metin içeriğine doğrudan erişip bu içeriği değiştirmeye yönelik yöntemler sunuyordu. Aşağıdaki yöntemler bu kategoriye girer:

Sekmelerin ek yapısal hiyerarşisi sayesinde bu yöntemler artık dokümandaki tüm sekmelerdeki metin içeriğini anlamsal olarak temsil etmiyor. Metin içeriği artık farklı bir katmanda gösterilir. Yukarıda belirtilen tüm metin yöntemlerine DocumentTab üzerinden erişilebilir.

Document sınıfındaki mevcut yöntemler, etkin sekmedeki (belirli bir dokümana bağlı komut dosyalarında) veya ilk sekmedeki (etkin bir sekme yoksa) içeriğe erişir ya da bu içerikte değişiklik yapar.

Belirli bir sekmedeki metin içeriğine erişme

Document sınıfındaki metin yöntemleri yerine DocumentTab sınıfındaki yöntemleri (Tab.asDocumentTab() yöntemi aracılığıyla kullanılabilir) kullanmanız önerilir. Örneğin:

// Print the text from the body of the active tab.
const doc = DocumentApp.getActiveDocument();
const documentTab = doc.getActiveTab().asDocumentTab();
const body = documentTab.getBody();
console.log(body.getText());

Kullanıcı seçiminde yapılan değişiklikler

Metin seçim yöntemleri

Document sınıfı, etkin belgede kullanıcının metnin neresinde seçim yaptığını yönetmek için alıcı ve ayarlayıcı sağlar. Bu yöntemler, komut dosyasını çalıştıran kullanıcının etkin sekmesi bağlamında çalışır.

  • Document.getCursor(): Kullanıcı imlecini etkin sekmede döndürür.
  • Document.getSelection(): Etkin sekme'deki kullanıcının seçim aralığını döndürür.
  • Document.setCursor(position): Kullanıcıya etkin dokümanda imlecinin konumunu ayarlama olanağı sunar. Konum etkin olmayan bir sekmedeyse kullanıcının etkin sekmesi de bu konumla ilişkili sekmeye geçirilir.
  • Document.setSelection(range): Etkin dokümanda kullanıcının seçim aralığını belirler. Aralık etkin olmayan bir sekmedeyse kullanıcının etkin sekmesi de bu aralıkla ilişkili sekmeye geçirilir.

Sekme seçme yöntemleri ve kullanım alanları

Sekmelerin kullanıma sunulmasıyla birlikte, komut dosyasını çalıştıran kullanıcının etkin sekmesini almak ve ayarlamak yararlı olabilir. Bu işlem aşağıdaki yöntemlerle yapılabilir:

Kullanıcının bütünsel "seçimi", etkin sekmenin yanı sıra mevcut imleç konumu veya seçim aralığının bir kombinasyonundan oluşur. Etkin bir seçimle çalışmanın iki yolu vardır: Kullanıcının etkin sekmesini belirli bir sekmeyle açıkça değiştirmek veya kullanıcının etkin sekmesini kullanmak.

Kullanıcının etkin sekmesini açıkça değiştirmek için Document.setActiveTab(tabId) kullanılabilir. Alternatif olarak, etkin olmayan bir sekmeden Position veya Range ile Document.setCursor(position) veya Document.setSelection(range) çağrısı yapmak, ilgili sekmeyi yeni etkinleştirir.

Komut dosyasının amacı, kullanıcının etkin sekmesini değiştirmeden kullanmaksa Document.setActiveTab(tabId) gerekmez. Document.getCursor() ve Document.getSelection() yöntemleri, kullanıcının komut dosyasını çalıştırdığı sekmeye bağlı olarak etkin sekmede zaten çalışır.

Bir doküman, birden fazla sekme seçimini veya farklı sekmelerde birden fazla konumu ya da aralığı desteklemez. Bu nedenle, Document.setActiveTab(tabId) kullanıldığında önceki imleç konumu veya seçim aralığı temizlenir.

Belirli bir sekme için konum ve aralık yöntemleri

Position ve Range metin seçim kavramlarına anlam veren belirli sekmedir. Diğer bir deyişle, bir imleç konumu veya seçim aralığı yalnızca komut dosyası, konumun veya aralığın bulunduğu sekmeyi biliyorsa anlamlı olur.

Bu, DocumentTab.newPosition(element, offset) ve DocumentTab.newRange() yöntemleri kullanılarak yapılır. Bu yöntemler, yöntemin çağrıldığı belirli DocumentTab öğesini hedefleyen bir Konum veya Aralık oluşturur. Buna karşılık, Document.newPosition(element, offset) ve Document.newRange(), etkin sekmeyi (veya komut dosyası bağlı değilse ilk sekmeyi) hedefleyen bir Konum veya Aralık oluşturur.

Seçimlerle çalışmayla ilgili örnek kodların yer aldığı sonraki bölümlerdeki örnek kod bloklarına bakın.

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, sekmeler ağacında gezinerek ve Document yerine Tab ve DocumentTab'ten alıcı yöntemleri çağırarak sekmeleri desteklemek üzere taşınabilir. Aşağıdaki kısmi kod örneğinde, bir belgedeki her sekmedeki metin içeriklerinin tümü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.

/** Logs all text contents from all tabs in the active document. */
function logAllText() {
  // Generate a list of all the tabs in the document, including any
  // nested child tabs. DocumentApp.openById('abc123456') can also
  // be used instead of DocumentApp.getActiveDocument().
  const doc = DocumentApp.getActiveDocument();
  const allTabs = getAllTabs(doc);

  // Log the content from each tab in the document.
  for (const tab of allTabs) {
    // Get the DocumentTab from the generic Tab object.
    const documentTab = tab.asDocumentTab();
    // Get the body from the given DocumentTab.
    const body = documentTab.getBody();
    // Get the body text and log it to the console.
    console.log(body.getText());
  }
}

/**
 * Returns a flat list of all tabs in the document, in the order
 * they would appear in the UI (i.e. top-down ordering). Includes
 * all child tabs.
 */
function getAllTabs(doc) {
  const allTabs = [];
  // Iterate over all tabs and recursively add any child tabs to
  // generate a flat list of Tabs.
  for (const tab of 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.
 */
function addCurrentAndChildTabs(tab, allTabs) {
  allTabs.push(tab);
  for (const childTab of tab.getChildTabs()) {
    addCurrentAndChildTabs(childTab, allTabs);
  }
}

Dokümandaki ilk sekmedeki sekme içeriğini okuma

Bu, tüm sekmelerin okunmasına benzer.

/** 
 * Logs all text contents from the first tab in the active 
 * document. 
 */
function logAllText() {
  // Generate a list of all the tabs in the document, including any
  // nested child tabs.
  const doc = DocumentApp.getActiveDocument();
  const allTabs = getAllTabs(doc);

  // Log the content from the first tab in the document.
  const firstTab = allTabs[0];
  // Get the DocumentTab from the generic Tab object.
  const documentTab = firstTab.asDocumentTab();
  // Get the body from the DocumentTab.
  const body = documentTab.getBody();
  // Get the body text and log it to the console.
  console.log(body.getText());
}

İlk sekmedeki sekme içeriklerini güncelleme

Aşağıdaki kısmi kod örneğinde, güncelleme yaparken belirli bir sekmenin nasıl hedefleneceği gösterilmektedir.

/** Inserts text into the first tab of the active document. */
function insertTextInFirstTab() {
  // Get the first tab's body.
  const doc = DocumentApp.getActiveDocument();
  const firstTab = doc.getTabs()[0];
  const firstDocumentTab = firstTab.asDocumentTab();
  const firstTabBody = firstDocumentTab.getBody();

  // Append a paragraph and a page break to the first tab's body
  // section.
  firstTabBody.appendParagraph("A paragraph.");
  firstTabBody.appendPageBreak();
}

Etkin veya seçili sekmedeki sekme içeriklerini güncelleme

Aşağıdaki kısmi kod örneğinde, güncelleme yaparken etkin sekmenin nasıl hedefleneceği gösterilmektedir.

/**
 * Inserts text into the active/selected tab of the active
 * document.
 */
function insertTextInActiveTab() {
  // Get the active/selected tab's body.
  const doc = DocumentApp.getActiveDocument();
  const activeTab = doc.getActiveTab();
  const activeDocumentTab = activeTab.asDocumentTab();
  const activeTabBody = activeDocumentTab.getBody();

  // Append a paragraph and a page break to the active tab's body
  // section.
  activeTabBody.appendParagraph("A paragraph.");
  activeTabBody.appendPageBreak();
}

Etkin sekmede bir imleç konumu veya seçim aralığı ayarlama

Aşağıdaki kısmi kod örneğinde, kullanıcının etkin sekmesindeki imleç konumunun veya seçim aralığının nasıl güncelleneceği gösterilmektedir. Bu durum yalnızca bağlı komut dosyalarında geçerlidir.

/**
 * Changes the user's selection to select all tables within the tab
 * with the provided ID.
 */
function selectAllTables(tabId) {
  const doc = DocumentApp.getActiveDocument();
  const tab = doc.getTab(tabId);
  const documentTab = tab.asDocumentTab();

  // Build a range that encompasses all tables within the specified
  // tab.
  const rangeBuilder = documentTab.newRange();
  const tables = documentTab.getBody().getTables();
  for (let i = 0; i < tables.length; i++) {
    rangeBuilder.addElement(tables[i]);
  }
  // Set the document's selection to the tables within the specified
  // tab. Note that this actually switches the user's active tab as
  // well.
  doc.setSelection(rangeBuilder.build());
}

Etkin veya seçili sekmeyi ayarlama

Aşağıdaki kısmi kod örneğinde, kullanıcının etkin sekmesinin nasıl değiştirileceği gösterilmektedir. Bu yalnızca bağlı komut dosyalarında geçerlidir.

/**
 * Changes the user's selected tab to the tab immediately following
 * the currently selected one. Handles child tabs.
 *
 * 
Only changes the selection if there is a tab following the
 * currently selected one.
 */
function selectNextTab() {
  const doc = DocumentApp.getActiveDocument();
  const allTabs = getAllTabs(doc);
  const activeTab = doc.getActiveTab();

  // Find the index of the currently active tab.
  let activeTabIndex = -1;
  for (let i = 0; i < allTabs.length; i++) {
    if (allTabs[i].getId() === activeTab.getId()) {
      activeTabIndex = i;
    }
  }

  // Update the user's selected tab if there is a valid next tab.
  const nextTabIndex = activeTabIndex + 1;
  if (nextTabIndex < allTabs.length) {
    doc.setActiveTab(allTabs[nextTabIndex].getId());
  }
}