با برگه ها کار کنید

اسکریپت برنامه‌ها برای Google Docs به شما امکان می‌دهد از هر تبی در سند به محتوا دسترسی داشته باشید.

برگه‌ها (tabs) چیستند؟

گوگل داکز (Google Docs) دارای یک لایه سازمانی به نام تب (tab) است. داکز به کاربران اجازه می‌دهد تا یک یا چند تب (tab) را در یک سند واحد ایجاد کنند، مشابه تب‌های امروزی در Sheets. هر تب عنوان و یک شناسه (ID) مخصوص به خود را دارد (که در URL اضافه شده است). یک تب همچنین می‌تواند تب‌های فرزند (child tabs ) داشته باشد، که تب‌هایی هستند که در زیر تب دیگر قرار گرفته‌اند.

دسترسی به تب‌ها

ویژگی‌ها و محتوای تب‌ها با استفاده از Document.getTabs() قابل دسترسی هستند که لیستی از Tab را برمی‌گرداند. بخش‌های بعدی مروری مختصر بر کلاس Tab ارائه می‌دهند؛ مستندات کلاس Tab نیز اطلاعات دقیق‌تری را ارائه می‌دهد.

ویژگی‌های برگه

ویژگی‌های تب را می‌توان با استفاده از متدهایی مانند Tab.getId() و Tab.getTitle() بازیابی کرد.

محتویات برگه

محتوای سند درون هر تب را می‌توان با استفاده از Tab.asDocumentTab() بازیابی کرد. بخش «تغییرات در ساختار کلاس سند» نحوه استفاده از این قابلیت را شرح می‌دهد.

سلسله مراتب تب

تب‌های فرزند در اسکریپت برنامه‌های گوگل از طریق Tab.getChildTabs() نمایش داده می‌شوند. دسترسی به محتوای همه تب‌ها نیاز به پیمایش «درخت» تب‌های فرزند دارد. برای مثال، سندی را در نظر بگیرید که شامل سلسله مراتب تب به شرح زیر است:

رابط کاربری فهرست تب‌ها شامل سه تب سطح بالا است که برخی از آنها دارای تب‌های فرزند هستند

برای دسترسی به تب ۳.۱.۲ ، می‌توانید مراحل زیر را انجام دهید:

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

بلوک‌های کد نمونه را در بخش‌های بعدی مشاهده کنید، که کد نمونه‌ای را برای تکرار در تمام برگه‌های یک سند ارائه می‌دهد.

روش‌های دیگر بازیابی تب‌ها

دو روش دیگر برای بازیابی تب‌ها وجود دارد:

  • Document.getTab(tabId) : تبی را که شناسه (ID) آن مشخص شده است، برمی‌گرداند.
  • Document.getActiveTab() : تب فعال کاربر را برمی‌گرداند. فقط در اسکریپت‌هایی که به یک سند متصل هستند، کار می‌کند. بخش‌های بعدی این موضوع را با جزئیات بیشتری توضیح می‌دهند.

تغییرات در ساختار کلاس سند

در گذشته، اسناد مفهومی به نام تب (tab) نداشتند، بنابراین کلاس Document متدهایی را برای دسترسی مستقیم و تغییر محتوای متنی سند ارائه می‌داد. متدهای زیر در این دسته قرار می‌گیرند:

با سلسله مراتب ساختاری اضافی تب‌ها، این متدها دیگر از نظر معنایی محتوای متن را از همه تب‌های موجود در سند نمایش نمی‌دهند. محتوای متن اکنون در یک لایه متفاوت نمایش داده می‌شود؛ همه متدهای متنی فوق‌الذکر از طریق DocumentTab قابل دسترسی هستند.

این متدهای موجود در کلاس Document به محتوای تب فعال (در اسکریپت‌های متصل به یک سند خاص) یا اولین تب (در صورت عدم وجود تب فعال) دسترسی پیدا کرده یا آن را تغییر می‌دهند.

دسترسی به محتوای متن در یک تب خاص

به جای استفاده از متدهای متنیِ Document ، توصیه می‌شود از متدهایی که خارج از کلاس DocumentTab در دسترس هستند (که از طریق متد Tab.asDocumentTab() در دسترس هستند) استفاده کنید. برای مثال:

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

تغییرات در انتخاب کاربر

روش‌های انتخاب متن

کلاس Document ، متدهای getter و setter را برای مدیریت محل انتخاب کاربر در متن، در سند فعال، ارائه می‌دهد. این متدها در چارچوب تب فعال کاربری که اسکریپت را اجرا می‌کند، عمل می‌کنند.

  • Document.getCursor() : موقعیت مکان‌نمای کاربر را در تب فعال برمی‌گرداند.
  • Document.getSelection() : محدوده انتخاب کاربر در تب فعال را برمی‌گرداند.
  • Document.setCursor(position) : موقعیت مکان‌نمای کاربر را در سند فعال تنظیم می‌کند. اگر موقعیت در یک تب غیرفعال باشد، تب فعال کاربر نیز به تب مرتبط با آن موقعیت تغییر می‌کند.
  • Document.setSelection(range) : محدوده انتخاب کاربر در سند فعال را تنظیم می‌کند. اگر محدوده در یک تب غیرفعال باشد، تب فعال کاربر نیز به تب مرتبط با آن محدوده تغییر می‌کند.

روش‌های انتخاب تب و موارد استفاده

با معرفی تب‌ها، دریافت و تنظیم تب فعال کاربری که اسکریپت را اجرا می‌کند می‌تواند مفید باشد. این کار را می‌توان با استفاده از روش‌های زیر انجام داد:

  • Document.getActiveTab() : Tab فعال کاربر را در سند فعال برمی‌گرداند.
  • Document.setActiveTab(tabId) : Tab انتخاب شده توسط کاربر در سند فعلی را روی تبی با شناسه مشخص شده تنظیم می‌کند.

«انتخاب» جامع کاربر از ترکیبی از تب فعال به همراه موقعیت فعلی مکان‌نما یا محدوده انتخاب تشکیل شده است. دو الگو برای کار با یک انتخاب فعال این است که یا تب فعال کاربر را به طور صریح به یک تب خاص تغییر دهید یا از تب فعال کاربر استفاده کنید.

تغییر صریح تب فعال کاربر می‌تواند با استفاده از Document.setActiveTab(tabId) انجام شود. به طور جایگزین، فراخوانی Document.setCursor(position) یا Document.setSelection(range) با یک Position یا Range از یک تب غیرفعال، آن تب را دوباره فعال می‌کند.

اگر رفتار مورد نظر اسکریپت، استفاده از تب فعال کاربر بدون تغییر آن باشد، آنگاه Document.setActiveTab(tabId) ضروری نیست. متدهای Document.getCursor() و Document.getSelection() از قبل بر اساس تبی که کاربر اسکریپت را از آن اجرا می‌کند، روی تب فعال عمل خواهند کرد.

توجه داشته باشید که یک سند از انتخاب چندین تب یا چندین موقعیت یا محدوده در تب‌های مختلف پشتیبانی نمی‌کند. بنابراین، استفاده از Document.setActiveTab(tabId) موقعیت مکان‌نما یا محدوده انتخاب قبلی را پاک می‌کند.

متدهای موقعیت و محدوده برای یک Tab خاص

تب خاص همان چیزی است که به مفاهیم انتخاب متن یعنی Position و Range معنا می‌دهد. به عبارت دیگر، موقعیت مکان‌نما یا محدوده انتخاب تنها در صورتی معنادار هستند که اسکریپت، تب خاصی را که موقعیت یا محدوده در آن قرار دارد، بشناسد.

این امر با استفاده از متدهای DocumentTab.newPosition(element, offset) و DocumentTab.newRange() محقق می‌شود که یک موقعیت یا محدوده ایجاد می‌کنند که DocumentTab خاصی را که متد از آن فراخوانی می‌شود، هدف قرار می‌دهد. در مقابل، Document.newPosition(element, offset) و Document.newRange() یک موقعیت یا محدوده ایجاد می‌کنند که تب فعال (یا اولین تب، در صورتی که اسکریپت مقید نشده باشد) را هدف قرار می‌دهد.

بلوک‌های کد نمونه را در بخش‌های بعدی مشاهده کنید، که کد نمونه‌ای برای کار با انتخاب‌ها ارائه می‌دهد.

الگوهای رایج استفاده از تب‌ها

نمونه‌های کد زیر روش‌های مختلف تعامل با تب‌ها را شرح می‌دهند.

محتوای تب را از تمام تب‌های موجود در سند بخوانید

کد موجودی که قبل از ویژگی تب‌ها این کار را انجام می‌داد، می‌تواند با پیمایش درخت تب‌ها و فراخوانی متدهای getter از Tab و DocumentTab به جای Document ، برای پشتیبانی از تب‌ها منتقل شود. نمونه کد ناقص زیر نحوه چاپ تمام محتوای متن از هر تب در یک سند را نشان می‌دهد. این کد پیمایش تب را می‌توان برای بسیاری از موارد استفاده دیگر که به ساختار واقعی تب‌ها اهمیتی نمی‌دهند، تطبیق داد. 

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

خواندن محتوای تب از اولین تب در سند

این مشابه خواندن همه تب‌ها است. 

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

به‌روزرسانی محتوای تب در اولین تب

نمونه کد ناقص زیر نحوه هدف قرار دادن یک تب خاص هنگام انجام به‌روزرسانی‌ها را نشان می‌دهد. 

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

به‌روزرسانی محتوای تب در تب فعال یا انتخاب‌شده

نمونه کد ناقص زیر نحوه هدف قرار دادن تب فعال هنگام انجام به‌روزرسانی‌ها را نشان می‌دهد. 

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

تنظیم موقعیت مکان‌نما یا محدوده انتخاب در برگه فعال

نمونه کد ناقص زیر نحوه به‌روزرسانی موقعیت مکان‌نما یا محدوده انتخاب در تب فعال کاربر را نشان می‌دهد. این فقط در اسکریپت‌های محدود شده (bound scripts) مرتبط است. 

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

تنظیم تب فعال یا انتخاب شده

نمونه کد ناقص زیر نحوه تغییر تب فعال کاربر را نشان می‌دهد. این فقط در اسکریپت‌های محدود شده مرتبط است. 

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