تتيح لك واجهة برمجة تطبيقات "مستندات Google" الوصول إلى المحتوى من أي علامة تبويب في المستند.
ما هي علامات التبويب؟
يتميز تطبيق "مستندات Google" بطبقة تنظيمية تُسمى علامات التبويب. يتيح تطبيق "مستندات Google" للمستخدمين إنشاء علامة تبويب واحدة أو أكثر في علامة تبويب واحدة. تشبه كيفية وجود علامات تبويب في "جداول بيانات Google" اليوم. لكل علامة تبويب اسمها العنوان ورقم التعريف (ملحقان بعنوان URL). يمكن أن تحتوي علامة التبويب أيضًا على علامات التبويب الفرعية، وهي وعلامات تبويب متداخلة أسفل علامة تبويب أخرى.
تتوفّر حاليًا إمكانية استخدام واجهة برمجة التطبيقات لعلامات التبويب الفرعية، ولكن ستتوفر قريبًا إمكانية استخدام واجهة المستخدم. يمكنك حاليًا التعامل مع علامات التبويب الفرعية في الرمز الخاص بك، وبذلك عندما تتم إتاحة واجهة المستخدم. ولن تحتاج إلى إجراء تعديلات إضافية على الرمز
تغييرات هيكلية في كيفية تمثيل محتوى المستندات في مورد المستند
في الماضي، لم يكن للوثائق مفهوم علامات التبويب، وبالتالي
Document
تم تضمين المرجع مباشرةً.
كل المحتوى النصي من خلال الحقول التالية:
document.body
document.headers
document.footers
document.footnotes
document.documentStyle
document.suggestedDocumentStyleChanges
document.namedStyles
document.suggestedNamedStylesChanges
document.lists
document.namedRanges
document.inlineObjects
document.positionedObjects
ومع التسلسل الهرمي الهيكلي لعلامات التبويب، لم تعد هذه الحقول
يمثلان دلاليًا المحتوى النصي من كل علامات التبويب في المستند. تشير رسالة الأشكال البيانية
يتم الآن تمثيل المحتوى النصي في طبقة مختلفة. خصائص علامة التبويب
إلى المحتوى في مستندات 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(); }