Class DocumentTab

DocumentTab

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

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

// Get a specific document tab based on the tab ID.
var documentTab = DocumentApp.openById('abc123456').getTab('t.0').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 by its ID and retrieves the tab with ID 't.0'. If you created your
// script from within a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the doc ID and the tab ID with your own.
const documentTab = DocumentApp.openById('abc123456').getTab('t.0').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());

المعلمات

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

الإرجاع

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

التفويض

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

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

---

addFooter()

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

// Opens the Docs file by its ID and retrieves the tab with ID 't.0'. If you created your
// script from within a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the doc ID and the tab ID with your own.
const documentTab = DocumentApp.openById('abc123456').getTab('t.0').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 by its ID and retrieves the tab with ID 't.0'. If you created your
// script from within a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the doc ID and the tab ID with your own.
const documentTab = DocumentApp.openById('abc123456').getTab('t.0').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 the tab with tab ID 't.0'.
var documentTab = DocumentApp.openById('abc123456').getTab('t.0').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());

المعلمات

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

الإرجاع

NamedRange — NamedRange

التفويض

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

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

---

getBody()

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

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

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

// Opens the Docs file by its ID and retrieves the tab with ID 't.0'. If you created your
// script from within a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the doc ID and the tab ID with your own.
const documentTab = DocumentApp.openById('abc123456').getTab('t.0').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 by its ID and retrieves the tab with ID 't.0'. If you created your
// script from within a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the doc ID and the tab ID with your own.
const documentTab = DocumentApp.openById('abc123456').getTab('t.0').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.');
}

المعلمات

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

الإرجاع

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

التفويض

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

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

---

getBookmarks()

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

// Opens the Docs file by its ID and retrieves the tab with ID 't.0'. If you created your
// script from within a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the doc ID and the tab ID with your own.
const documentTab = DocumentApp.openById('abc123456').getTab('t.0').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 by its ID and retrieves the tab with ID 't.0'. If you created your
// script from within a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the doc ID and the tab ID with your own.
const documentTab = DocumentApp.openById('abc123456').getTab('t.0').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 by its ID and retrieves the tab with ID 't.0'. If you created your
// script from within a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the doc ID and the tab ID with your own.
const documentTab = DocumentApp.openById('abc123456').getTab('t.0').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 by its ID and retrieves the tab with ID 't.0'. If you created your
// script from within a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the doc ID and the tab ID with your own.
const documentTab = DocumentApp.openById('abc123456').getTab('t.0').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.

المعلمات

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

الإرجاع

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

المعلمات

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

الإرجاع

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.
var doc = DocumentApp.openById('abc123456');
var documentTab = doc.getTab('t.0').asDocumentTab();
var paragraph = documentTab.getBody().appendParagraph('My new paragraph.');
var position = documentTab.newPosition(paragraph.getChild(0), 2);
doc.setCursor(position);

المعلمات

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

الإرجاع

Position — Position الجديد

التفويض

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

• 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.
var doc = DocumentApp.openById('abc123456');
var documentTab = doc.getTab('t.0').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