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

تتيح لك Google Docs API الوصول إلى المحتوى من أي علامة تبويب في المستند.

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

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

تغييرات هيكلية على طريقة عرض محتوى المستند في "مرجع المستند"

في السابق، لم تكن المستندات تتضمّن علامات تبويب، لذا كان Document المرجع يحتوي مباشرةً على جميع محتوى النص من خلال الحقول التالية:

مع التسلسل الهرمي الهيكلي الإضافي للعلامات التبويب، لم تعُد هذه الحقول represent دلاليًا لمحتوى النص من جميع علامات التبويب في المستند. يتم الآن تمثيل المحتوى المستنِد إلى النص في طبقة مختلفة. يمكن الوصول إلى سمات علامة التبويب ومحتوى "مستندات 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/workspace/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();
}