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

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

برگه ها چیست؟

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

تغییرات ساختاری در نحوه نمایش محتوای سند در منبع سند

در گذشته، اسناد مفهومی از برگه ها نداشتند، بنابراین منبع Document مستقیماً تمام محتوای متن را از طریق فیلدهای زیر شامل می شد:

با سلسله مراتب ساختاری اضافی برگه ها، این فیلدها دیگر محتوای متنی را از همه برگه ها در سند نشان نمی دهند. محتوای مبتنی بر متن اکنون در لایه دیگری نمایش داده می شود. ویژگی‌های برگه و محتوای Google Docs با document.tabs قابل دسترسی است که فهرستی از اشیاء Tab است که هر کدام شامل تمام فیلدهای محتوای متنی ذکر شده است. بخش‌های بعدی یک مرور مختصر ارائه می‌دهند. نمایش Tab JSON همچنین اطلاعات دقیق تری را ارائه می دهد.

دسترسی به ویژگی های برگه

با استفاده از tab.tabProperties که شامل اطلاعاتی مانند شناسه، عنوان و موقعیت برگه است، به ویژگی های برگه دسترسی پیدا کنید.

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

محتوای سند واقعی در برگه به ​​صورت tab.documentTab نمایش داده می شود. همه فیلدهای محتوای متنی ذکر شده با استفاده از tab.documentTab قابل دسترسی هستند. به عنوان مثال، به جای استفاده از document.body ، باید از document.tabs[indexOfTab].documentTab.body استفاده کنید.

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

برگه های فرزند در API به عنوان یک فیلد tab.childTabs در Tab نشان داده می شوند. دسترسی به همه برگه‌های یک سند مستلزم عبور از «درخت» تب‌های فرزند است. به عنوان مثال، سندی را که حاوی سلسله مراتب برگه است به صورت زیر در نظر بگیرید:

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

برای بازیابی Body از برگه 3.1.2 ، باید به document.tabs[2].childTabs[0].childTabs[1].documentTab.body دسترسی پیدا کنید. بلوک‌های کد نمونه را در بخش بعدی ببینید، که کد نمونه را برای تکرار در همه برگه‌های یک سند ارائه می‌کند.

تغییرات در روش ها

با معرفی تب ها، هر یک از روش های سند دارای چند تغییر هستند که ممکن است شما را ملزم به به روز رسانی کد خود کند.

اسناد.دریافت

به طور پیش فرض، همه محتویات برگه برگردانده نمی شوند. توسعه دهندگان باید کد خود را برای دسترسی به همه برگه ها به روز کنند. متد documents.get یک پارامتر includeTabsContent را نشان می‌دهد که پیکربندی اینکه آیا محتویات همه برگه‌ها در پاسخ ارائه می‌شوند یا خیر.

  • اگر includeTabsContent روی true تنظیم شده باشد، روش documents.get یک منبع Document با فیلد document.tabs پر شده برمی گرداند. تمام فیلدهای متنی مستقیماً روی document (به عنوان مثال document.body ) خالی خواهند ماند.
  • اگر includeTabsContent ارائه نشده باشد، فیلدهای متنی در منبع Document (به عنوان مثال document.body ) فقط با محتوای برگه اول پر می شود. فیلد document.tabs خالی خواهد بود و محتوای برگه های دیگر بازگردانده نمی شود.

اسناد.ایجاد

متد documents.create یک منبع Document را برمی‌گرداند که نمایانگر سند خالی ایجاد شده است. منبع Document برگردانده شده، محتوای خالی سند را در فیلدهای محتوای متنی سند و نیز document.tabs پر می کند.

document.batchUpdate

هر Request شامل راهی برای مشخص کردن برگه هایی است که به روز رسانی را در آنها اعمال کنید. به‌طور پیش‌فرض، اگر یک برگه مشخص نشده باشد، در بیشتر موارد Request در اولین برگه سند اعمال می‌شود. ReplaceAllTextRequest ، DeleteNamedRangeRequest ، و ReplaceNamedRangeContentRequest سه درخواست ویژه هستند که در عوض به طور پیش فرض برای همه برگه ها اعمال می شوند.

برای جزئیات بیشتر به مستندات Request مراجعه کنید.

کاربران می توانند پیوندهای داخلی به برگه ها، نشانک ها و سرفصل های یک سند ایجاد کنند. با معرفی ویژگی برگه‌ها، فیلدهای link.bookmarkId و link.headingId در منبع Link دیگر نمی‌توانند نشانک یا عنوان را در یک برگه خاص در سند نشان دهند.

توسعه دهندگان باید کد خود را برای استفاده از link.bookmark و link.heading در عملیات خواندن و نوشتن به روز کنند. آنها پیوندهای داخلی را با استفاده از اشیاء BookmarkLink و HeadingLink که هر کدام شامل شناسه نشانک یا عنوان و شناسه برگه ای است که در آن قرار دارد، نشان link.tabId دهد.

محتوای پیوند یک پاسخ documents.get نیز بسته به پارامتر includeTabsContent می‌تواند متفاوت باشد:

  • اگر includeTabsContent روی true تنظیم شود، همه پیوندهای داخلی به صورت link.bookmark و link.heading نمایش داده می شوند. فیلدهای قدیمی دیگر استفاده نخواهند شد.
  • اگر includeTabsContent ارائه نشده باشد، در اسنادی که حاوی یک برگه هستند، هر پیوند داخلی به نشانک‌ها یا سرفصل‌ها در آن برگه منحصر به فرد همچنان به‌عنوان link.bookmarkId و link.headingId نمایش داده می‌شوند. در اسناد حاوی چندین برگه، پیوندهای داخلی به صورت link.bookmark و link.heading نمایش داده می‌شوند.

در document.batchUpdate ، اگر پیوند داخلی با استفاده از یکی از فیلدهای قدیمی ایجاد شود، نشانک یا عنوان از شناسه برگه مشخص شده در Request در نظر گرفته می شود. اگر هیچ برگه ای مشخص نشده باشد، از اولین برگه سند در نظر گرفته می شود.

نمایش لینک JSON اطلاعات دقیق تری را ارائه می دهد.

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

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

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

کدهای موجود که این کار را قبل از ویژگی برگه‌ها انجام داده‌اند، می‌توانند با تنظیم پارامتر includeTabsContent روی true ، عبور از سلسله مراتب درخت برگه‌ها و فراخوانی متدهای دریافت کننده خارج از Tab و DocumentTab به جای Document به برگه‌های پشتیبانی منتقل شوند. نمونه کد جزئی زیر بر اساس قطعه در Extract the text from a document است. این نشان می دهد که چگونه تمام محتوای متن را از هر برگه در یک سند چاپ کنید. این کد پیمایش برگه را می توان برای بسیاری از موارد استفاده دیگر که به ساختار واقعی برگه ها اهمیتی نمی دهند، تطبیق داد.

جاوا 

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

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

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

جاوا 

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

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

نمونه کد جزئی زیر نشان می دهد که چگونه یک برگه خاص را در یک Request هدف قرار دهید. این کد بر اساس نمونه موجود در راهنمای درج، حذف و حرکت متن است.

جاوا 

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