التعامل مع علامات التبويب

تتيح لك واجهة برمجة تطبيقات "مستندات Google" الوصول إلى المحتوى من أي علامة تبويب في المستند.

ما هي علامات التبويب؟

يتميز تطبيق "مستندات Google" بطبقة تنظيمية تُسمى علامات التبويب. يتيح "مستندات Google" للمستخدمين إنشاء علامة تبويب واحدة أو أكثر في علامة تبويب واحدة. تشبه كيفية وجود علامات تبويب في "جداول بيانات Google" اليوم. لكل علامة تبويب اسمها العنوان ورقم التعريف (ملحقان بعنوان URL). يمكن أن تحتوي علامة التبويب أيضًا على علامات التبويب الفرعية، وهي وعلامات تبويب متداخلة أسفل علامة تبويب أخرى.

تتوفّر حاليًا إمكانية استخدام واجهة برمجة التطبيقات لعلامات التبويب الفرعية، ولكن ستتوفر قريبًا إمكانية استخدام واجهة المستخدم. يمكنك التعامل مع علامات التبويب الفرعية في الرمز البرمجي اليوم لكي لا تضطر إلى إجراء المزيد من تعديلات الرمز البرمجي عند إطلاق واجهة المستخدم.

تغييرات هيكلية في كيفية تمثيل محتوى المستند في مورد المستند

في الماضي، لم يكن للوثائق مفهوم علامات التبويب، وبالتالي Document تم تضمين المرجع مباشرةً. كل المحتوى النصي من خلال الحقول التالية:

ومع التسلسل الهرمي الهيكلي لعلامات التبويب، لم تعد هذه الحقول يمثلان دلاليًا المحتوى النصي من كل علامات التبويب في المستند. تشير رسالة الأشكال البيانية يتم الآن تمثيل المحتوى النصي في طبقة مختلفة. خصائص علامة التبويب إلى المحتوى في مستندات Google من خلال document.tabs، وهي قائمة Tab كائنات، كل منها يحتوي على جميع حقول المحتوى النصي المذكورة أعلاه. تعطي الأقسام اللاحقة ونظرة عامة مختصرة الـ تمثيل Tab JSON أيضًا معلومات أكثر تفصيلاً.

الوصول إلى خصائص علامة التبويب

الوصول إلى خصائص علامة التبويب باستخدام tab.tabProperties، التي تتضمن معلومات، مثل رقم التعريف والعنوان وموضع علامة التبويب.

الوصول إلى المحتوى النصي ضمن علامة تبويب

ويتم عرض محتوى المستند الفعلي داخل علامة التبويب tab.documentTab كل يمكن الوصول إلى حقول المحتوى النصي المذكورة أعلاه باستخدام tab.documentTab. على سبيل المثال، بدلاً من استخدام document.body، يجب عليك استخدام document.tabs[indexOfTab].documentTab.body

التدرّج الهرمي لعلامات التبويب

يتم تمثيل علامات التبويب الفرعية في واجهة برمجة التطبيقات على أنها الحقل tab.childTabs مفعّل Tab الوصول إلى جميع علامات التبويب في المستند يتطلب اجتياز "الشجرة" من علامات التبويب الفرعية. على سبيل المثال، ضع في اعتبارك مستند يحتوي على تسلسل هرمي لعلامة التبويب على النحو التالي:

واجهة مستخدم قائمة علامات التبويب تحتوي على ثلاث علامات تبويب من المستوى الأعلى، بعضها يحتوي على علامات تبويب فرعية

لاسترداد Body من علامة التبويب 3.1.2، ستتمكن من الوصول إلى document.tabs[2].childTabs[0].childTabs[1].documentTab.body الاطّلاع على العيّنة مجموعات رموز برمجية في القسم التالي، والتي توفر لك نموذج التعليمات البرمجية للتكرار في جميع علامات التبويب في المستند

التغييرات في الطرق

مع مقدمة علامات التبويب، تشتمل كل طريقة من طرق المستند على بعض التغييرات التي قد تتطلّب منك تحديث الرمز

documents.get

ولا يتم عرض بعض محتوى علامات التبويب تلقائيًا. يجب أن يعدّل المطوّرون الرمز للوصول إلى جميع علامات التبويب. تشير رسالة الأشكال البيانية تعرض الطريقة documents.get معلَمة includeTabsContent تسمح بضبط ما إذا كان هناك محتوى من يتم توفير جميع علامات التبويب في الرد.

  • إذا تم ضبط includeTabsContent على true، سيتم سيتم عرض طريقة documents.get مصدر Document مع تمت تعبئة الحقل document.tabs. جميع الحقول النصية مباشرةً على document (مثال: document.body) يمكن تركه فارغًا.
  • في حال عدم تقديم includeTabsContent، ستتم تعبئة الحقول النصية في مورد Document (مثل document.body) بالمحتوى من علامة التبويب الأولى فقط. سيكون الحقل document.tabs فارغًا ولن يتم عرض المحتوى من علامات التبويب الأخرى.

documents.create

الطريقة 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. الجزئي التالي بالاستناد إلى عيّنة الرمز إلى المقتطف استخراج النص من مستند إنه يعرض كيفية طباعة كل المحتوى النصي من كل علامة تبويب في مستند يمكن تعديل رمز تنقّل علامات التبويب هذا لاستخدامه في العديد من حالات الاستخدام الأخرى التي لا تهتم بالبنية الفعلية لعلامات التبويب.

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

قراءة محتوى علامة التبويب من علامة التبويب الأولى في المستند

وهذا يشبه قراءة جميع علامات التبويب.

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

تقديم طلب لتعديل علامة التبويب الأولى

يوضح نموذج الرمز الجزئي التالي كيفية استهداف علامة تبويب معينة في Request تستند هذه التعليمات البرمجية إلى العيّنة الواردة في دليل إدراج النص وحذفه ونقله.

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