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

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

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

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

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

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

مع التسلسل الهرمي الهيكلي الإضافي للعلامات التبويب، لم تعُد هذه الحقول represent دلاليًا محتوى النص من جميع علامات التبويب في المستند. يتم الآن تمثيل المحتوى المستنِد إلى النص في طبقة مختلفة. يمكن الوصول إلى سمات علامات التبويب ومحتوى "مستندات Google" باستخدام document.tabs، وهي قائمة بعناصر 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 represent إشارة مرجعية أو عنوانًا في علامة تبويب معيّنة في المستند.

على المطوّرين تعديل الرمز البرمجي لاستخدام 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();
}