Class DocumentTab

DocumentTab

علامة تبويب في "مستند" تحتوي على نص منسَّق وعناصر مثل الجداول والقوائم.

يمكنك استرداد علامة تبويب مستند باستخدام Document.getTabs()[tabIndex].asDocumentTab().

// Get a specific document tab based on the tab ID.
// TODO(developer): Replace the IDs with your own.
var documentTab = DocumentApp.openById(DOCUMENT_ID).getTab(TAB_ID).asDocumentTab();

الطُرق

الطريقةنوع الإرجاعوصف قصير
addBookmark(position)Bookmarkلإضافة Bookmark عند السمة Position المحددة.
addFooter()FooterSectionتضيف قسمًا لتذييل علامة التبويب، في حال عدم توفّرها.
addHeader()HeaderSectionتضيف قسمًا لعنوان علامة التبويب، في حال عدم توفّرها.
addNamedRange(name, range)NamedRangeإضافة NamedRange، وهو Range الذي يحمل اسمًا ورقم تعريف يمكن استخدامهما والاسترداد اللاحق.
getBody()Bodyيسترد Body لعلامة التبويب.
getBookmark(id)Bookmarkالحصول على Bookmark مع المعرّف المحدّد.
getBookmarks()Bookmark[]الحصول على كل العناصر البالغ عددها Bookmark في علامة التبويب
getFooter()FooterSectionلاسترداد قسم تذييل علامة التبويب، في حال توفّره.
getFootnotes()Footnote[]لاسترداد جميع عناصر Footnote في النص الأساسي لعلامة التبويب
getHeader()HeaderSectionلاسترداد قسم عنوان علامة التبويب، إن وجد.
getNamedRangeById(id)NamedRangeالحصول على NamedRange مع المعرّف المحدّد.
getNamedRanges()NamedRange[]الحصول على كل العناصر البالغ عددها NamedRange في علامة التبويب
getNamedRanges(name)NamedRange[]جلب جميع العناصر NamedRange في علامة التبويب التي تحمل الاسم المحدّد
newPosition(element, offset)Positionتنشئ Position جديدة، وهي إشارة إلى موقع جغرافي في علامة التبويب، بالنسبة إلى العنصر المحدد.
newRange()RangeBuilderتنشئ أداة إنشاء تُستخدم لإنشاء كائنات Range من عناصر علامة التبويب.

الوثائق التفصيلية

addBookmark(position)

لإضافة Bookmark عند السمة Position المحددة.

// Opens the Docs file and retrieves the tab by its IDs. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument().getActiveTab() instead.
// TODO(developer): Replace the IDs with your own.
const documentTab = DocumentApp.openById(DOCUMENT_ID).getTab(TAB_ID).asDocumentTab();

// Gets the tab body and adds a paragraph.
const paragraph = documentTab.getBody().appendParagraph('My new paragraph.');

// Creates a position at the first character of the paragraph text.
const position = documentTab.newPosition(paragraph.getChild(0), 0);

// Adds a bookmark at the first character of the paragraph text.
const bookmark = documentTab.addBookmark(position);

// Logs the bookmark ID to the console.
console.log(bookmark.getId());

المعلمات

الاسمالنوعالوصف
positionPositionتمثّل هذه السمة موضع الإشارة الجديدة.

الإرجاع

Bookmark — الإشارة المرجعية الجديدة

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة إذنًا باستخدام واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

addFooter()

تضيف قسمًا لتذييل علامة التبويب، في حال عدم توفّرها.

// Opens the Docs file and retrieves the tab by its IDs. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument().getActiveTab() instead.
// TODO(developer): Replace the IDs with your own.
const documentTab = DocumentApp.openById(DOCUMENT_ID).getTab(TAB_ID).asDocumentTab();

// Adds a footer to the tab.
const footer = documentTab.addFooter();

// Sets the footer text to 'This is a footer.'
footer.setText('This is a footer');

الإرجاع

FooterSection: تذييل علامة التبويب

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة إذنًا باستخدام واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

addHeader()

تضيف قسمًا لعنوان علامة التبويب، في حال عدم توفّرها.

// Opens the Docs file and retrieves the tab by its IDs. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument().getActiveTab() instead.
// TODO(developer): Replace the IDs with your own.
const documentTab = DocumentApp.openById(DOCUMENT_ID).getTab(TAB_ID).asDocumentTab();

// Adds a header to the tab.
const header = documentTab.addHeader();

// Sets the header text to 'This is a header.'
header.setText('This is a header');

الإرجاع

HeaderSection: عنوان علامة التبويب

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة إذنًا باستخدام واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

addNamedRange(name, range)

إضافة NamedRange، وهو Range الذي يحمل اسمًا ورقم تعريف يمكن استخدامهما والاسترداد اللاحق. الأسماء ليست بالضرورة فريدة، حتى عبر علامات التبويب؛ عدة نطاقات مختلفة في يمكن أن يشترك المستند ذاته في الاسم ذاته، مثل فئة في HTML إلى حد كبير. على النقيض من ذلك، تعتبر المعرفات فريدة داخل المستند، مثل معرف في HTML. بعد إضافة NamedRange، لا يمكنك أو تعديله، يمكنك فقط إزالته.

يمكن لأي نص برمجي يدخل إلى علامة التبويب الوصول إلى NamedRange. لتجنُّب الزيارات غير المقصودة التعارضات بين النصوص البرمجية، ننصحك ببادئة أسماء النطاقات بسلسلة فريدة.

// Creates a named range that includes every table in a tab by its ID.
// TODO(developer): Replace the IDs with your own.
var documentTab = DocumentApp.openById(DOCUMENT_ID).getTab(TAB_ID).asDocumentTab();
var rangeBuilder = documentTab.newRange();
var tables = documentTab.getBody().getTables();
for (var i = 0; i < tables.length; i++) {
  rangeBuilder.addElement(tables[i]);
}
documentTab.addNamedRange('Tab t.0 tables', rangeBuilder.build());

المعلمات

الاسمالنوعالوصف
nameStringاسم النطاق، ولا يلزم أن يكون فريدًا؛ يجب أن تكون أسماء النطاقات بين حرف واحد و256 حرفًا.
rangeRangeنطاق العناصر المراد ربطها بالاسم؛ يمكن أن يكون النطاق نتيجة بحث أو تم إنشاؤه يدويًا باستخدام newRange().

الإرجاع

NamedRangeNamedRange

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة إذنًا باستخدام واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

getBody()

يسترد Body لعلامة التبويب.

يمكن أن تحتوي علامات التبويب على أنواع مختلفة من الأقسام (على سبيل المثال، HeaderSection وFooterSection). القسم النشط لعلامة التبويب هو Body.

تؤدي طرق العناصر في DocumentTab إلى تفويض Body.

// Opens the Docs file and retrieves the tab by its IDs. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument().getActiveTab() instead.
// TODO(developer): Replace the IDs with your own.
const documentTab = DocumentApp.openById(DOCUMENT_ID).getTab(TAB_ID).asDocumentTab();

// Gets the tab body.
const body = documentTab.getBody();

// Gets the body text and logs it to the console.
console.log(body.getText());

الإرجاع

Body — قسم النص الأساسي لعلامة التبويب

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة إذنًا باستخدام واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

getBookmark(id)

الحصول على Bookmark مع المعرّف المحدّد. تعرض هذه الطريقة القيمة null في حال عدم توفّر Bookmark في علامة التبويب هذه.

// Opens the Docs file and retrieves the tab by its IDs. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument().getActiveTab() instead.
// TODO(developer): Replace the IDs with your own.
const documentTab = DocumentApp.openById(DOCUMENT_ID).getTab(TAB_ID).asDocumentTab();

// Gets the bookmark by its ID.
const bookmark = documentTab.getBookmark('id.xyz654321');

// If the bookmark exists within the tab, logs the character offset of its position to the
// console. Otherwise, logs 'No bookmark exists with the given ID.' to the console.
if (bookmark) {
  console.log(bookmark.getPosition().getOffset());
} else {
  console.log('No bookmark exists with the given ID.');
}

المعلمات

الاسمالنوعالوصف
idStringرقم تعريف Bookmark.

الإرجاع

BookmarkBookmark مع رقم التعريف المحدد أو null إذا لم يكن ذلك هو Bookmark في علامة التبويب هذه.

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة إذنًا باستخدام واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

getBookmarks()

الحصول على كل العناصر البالغ عددها Bookmark في علامة التبويب

// Opens the Docs file and retrieves the tab by its IDs. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument().getActiveTab() instead.
// TODO(developer): Replace the IDs with your own.
const documentTab = DocumentApp.openById(DOCUMENT_ID).getTab(TAB_ID).asDocumentTab();

// Gets all of the bookmarks in the tab.
const bookmarks = documentTab.getBookmarks();

// Logs the number of bookmarks in the tab to the console.
console.log(bookmarks.length);

الإرجاع

Bookmark[]: مصفوفة من عناصر Bookmark في علامة التبويب.

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة إذنًا باستخدام واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

getFooter()

لاسترداد قسم تذييل علامة التبويب، في حال توفّره.

// Opens the Docs file and retrieves the tab by its IDs. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument().getActiveTab() instead.
// TODO(developer): Replace the IDs with your own.
const documentTab = DocumentApp.openById(DOCUMENT_ID).getTab(TAB_ID).asDocumentTab();

// Gets the text of the tab's footer and logs it to the console.
console.log(documentTab.getFooter().getText());

الإرجاع

FooterSection: تذييل علامة التبويب

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة إذنًا باستخدام واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

getFootnotes()

لاسترداد جميع عناصر Footnote في النص الأساسي لعلامة التبويب

تؤدي استدعاءات getFootnotes إلى تكرار عناصر علامة التبويب. بالنسبة لعلامات التبويب الكبيرة، تجنب الطلبات غير الضرورية لهذه الطريقة.

// Opens the Docs file and retrieves the tab by its IDs. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument().getActiveTab() instead.
// TODO(developer): Replace the IDs with your own.
const documentTab = DocumentApp.openById(DOCUMENT_ID).getTab(TAB_ID).asDocumentTab();

// Gets the first footnote.
const footnote = documentTab.getFootnotes()[0];

// Logs footnote contents to the console.
console.log(footnote.getFootnoteContents().getText());

الإرجاع

Footnote[] - الحواشي السفلية لعلامة التبويب.

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة إذنًا باستخدام واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

getHeader()

لاسترداد قسم عنوان علامة التبويب، إن وجد.

// Opens the Docs file and retrieves the tab by its IDs. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument().getActiveTab() instead.
// TODO(developer): Replace the IDs with your own.
const documentTab = DocumentApp.openById(DOCUMENT_ID).getTab(TAB_ID).asDocumentTab();

// Gets the text of the tab's header and logs it to the console.
console.log(documentTab.getHeader().getText());

الإرجاع

HeaderSection — عنوان علامة التبويب

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة إذنًا باستخدام واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

getNamedRangeById(id)

الحصول على NamedRange مع المعرّف المحدّد. تعرض هذه الطريقة null في حالة عدم وجود مثل هناك NamedRange في علامة التبويب. الأسماء ليست بالضرورة فريدة، حتى عبر علامات التبويب؛ قد تشترك عدة نطاقات مختلفة في المستند ذاته في نفس الاسم، ويشبه إلى حد كبير فئة في HTML. في المقابل، تكون المعرّفات فريدة داخل علامة التبويب، مثل المعرّف في HTML.

المعلمات

الاسمالنوعالوصف
idStringمعرّف النطاق، وهو فريد داخل علامة التبويب.

الإرجاع

NamedRangeNamedRange مع رقم التعريف المحدد أو null إذا لم يكن هذا النطاق موجودًا فيه علامة التبويب.

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة إذنًا باستخدام واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

getNamedRanges()

الحصول على كل العناصر البالغ عددها NamedRange في علامة التبويب

يمكن الوصول إلى NamedRange من خلال أي نص برمجي يصل إلى علامة التبويب. لتجنُّب التعارضات غير المقصودة بين النصوص البرمجية، ننصحك ببادئة أسماء النطاقات بسلسلة فريدة.

الإرجاع

NamedRange[] - مصفوفة من عناصر NamedRange في علامة التبويب، بما في ذلك عناصر متعددة النطاقات بنفس الاسم.

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة إذنًا باستخدام واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

getNamedRanges(name)

جلب جميع العناصر NamedRange في علامة التبويب التي تحمل الاسم المحدّد الأسماء ليست بالضرورة فريدة، حتى عبر علامات التبويب قد تشترك عدة نطاقات مختلفة في نفس المستند في نفس يشبه إلى حد كبير فئة في HTML. على النقيض من ذلك، تكون المعرفات فريدة داخل علامة التبويب، مثل معرف في HTML.

يمكن الوصول إلى NamedRange من خلال أي نص برمجي يصل إلى علامة التبويب. لتجنُّب التعارضات غير المقصودة بين النصوص البرمجية، ننصحك ببادئة أسماء النطاقات بسلسلة فريدة.

المعلمات

الاسمالنوعالوصف
nameStringاسم النطاق، وهو ليس فريدًا بالضرورة.

الإرجاع

NamedRange[] - مصفوفة من عناصر NamedRange في علامة التبويب بالاسم المحدّد.

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة إذنًا باستخدام واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

newPosition(element, offset)

تنشئ Position جديدة، وهي إشارة إلى موقع جغرافي في علامة التبويب، بالنسبة إلى العنصر المحدد. يتم تمثيل مؤشر المستخدم على أنّه Position، بالإضافة إلى استخدامات أخرى.

// Append a paragraph, then place the user's cursor after the first word of the new paragraph.
// TODO(developer): Replace the IDs with your own.
var doc = DocumentApp.openById(DOCUMENT_ID);
var documentTab = doc.getTab(TAB_ID).asDocumentTab();
var paragraph = documentTab.getBody().appendParagraph('My new paragraph.');
var position = documentTab.newPosition(paragraph.getChild(0), 2);
doc.setCursor(position);

المعلمات

الاسمالنوعالوصف
elementElementالعنصر الذي يحتوي على سمة Position التي تم إنشاؤها حديثًا يجب أن يكون هذا إما عنصر Text أو عنصر حاوية مثل Paragraph.
offsetIntegerفي ما يتعلق بعناصر Text، يتم عرض عدد الأحرف قبل Position. للعناصر الأخرى، وهو عدد العناصر الفرعية قبل Position داخل العلامة عنصر الحاوية نفسه.

الإرجاع

PositionPosition الجديد

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة إذنًا باستخدام واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

newRange()

تنشئ أداة إنشاء تُستخدم لإنشاء كائنات Range من عناصر علامة التبويب.

// Change the user's selection to a range that includes every table in the tab.
// TODO(developer): Replace the IDs with your own.
var doc = DocumentApp.openById(DOCUMENT_ID);
var documentTab = doc.getTab(TAB_ID).asDocumentTab();
var rangeBuilder = documentTab.newRange();
var tables = documentTab.getBody().getTables();
for (var i = 0; i < tables.length; i++) {
  rangeBuilder.addElement(tables[i]);
}
doc.setSelection(rangeBuilder.build());

الإرجاع

RangeBuilder — أداة الإنشاء الجديدة.

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة إذنًا باستخدام واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents