Class DocumentTab

علامة التبويبالمستند

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

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

// Get a specific document tab based on the tab ID.
// TODO(developer): Replace the IDs with your own.
const documentTab =
    DocumentApp.openById('123abc').getTab('123abc').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('123abc').getTab('123abc').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('123abc').getTab('123abc').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('123abc').getTab('123abc').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.
const documentTab =
    DocumentApp.openById('123abc').getTab('123abc').asDocumentTab();
const rangeBuilder = documentTab.newRange();
const tables = documentTab.getBody().getTables();
for (let i = 0; i < tables.length; i++) {
  rangeBuilder.addElement(tables[i]);
}
documentTab.addNamedRange('Tab t.0 tables', rangeBuilder.build());

المعلمات

الاسمالنوعالوصف
nameStringاسم النطاق، والذي لا يلزم أن يكون فريدًا، ويجب أن تتراوح أسماء النطاقات بين 1 و256 حرفًا.
rangeRangeنطاق العناصر المطلوب ربطها بالاسم، ويمكن أن يكون النطاق نتيجة بحث أو تم إنشاؤه يدويًا باستخدام 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 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('123abc').getTab('123abc').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('123abc').getTab('123abc').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.

الإرجاع

Bookmark: Bookmark الذي يحمل رقم التعريف المحدّد، أو 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('123abc').getTab('123abc').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('123abc').getTab('123abc').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('123abc').getTab('123abc').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('123abc').getTab('123abc').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رقم تعريف النطاق، وهو فريد داخل علامة التبويب.

الإرجاع

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

المعلمات

الاسمالنوعالوصف
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.
const doc = DocumentApp.openById('123abc');
const documentTab = doc.getTab('123abc').asDocumentTab();
const paragraph = documentTab.getBody().appendParagraph('My new paragraph.');
const position = documentTab.newPosition(paragraph.getChild(0), 2);
doc.setCursor(position);

المعلمات

الاسمالنوعالوصف
elementElementالعنصر الذي يحتوي على Position الذي تم إنشاؤه حديثًا إلى؛ يجب أن يكون إما عنصر Text أو عنصر حاوية مثل Paragraph.
offsetIntegerبالنسبة إلى عناصر 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.
// TODO(developer): Replace the IDs with your own.
const doc = DocumentApp.openById('123abc');
const documentTab = doc.getTab('123abc').asDocumentTab();
const rangeBuilder = documentTab.newRange();
const tables = documentTab.getBody().getTables();
for (let 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