Class Document

المستند

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

يمكن فتح المستندات أو إنشاؤها باستخدام DocumentApp.

// Open a document by ID.
var doc = DocumentApp.openById("<my-id>");

// Create and open a document.
doc = DocumentApp.create("Document Title");

الطُرق

الطريقةنوع الإرجاعوصف قصير
addBookmark(position)Bookmarkلإضافة Bookmark في Position المحدّد.
addEditor(emailAddress)Documentلإضافة المستخدم المحدد إلى قائمة محرري Document.
addEditor(user)Documentلإضافة المستخدم المحدد إلى قائمة محرري Document.
addEditors(emailAddresses)Documentلإضافة مصفوفة محددة من المستخدمين إلى قائمة المحرِّرين في Document.
addFooter()FooterSectionلإضافة قسم تذييل المستند، في حال عدم توفّر أي قسم.
addHeader()HeaderSectionإضافة قسم رؤوس المستندات، في حال عدم توفّر قسم
addNamedRange(name, range)NamedRangeتتم إضافة NamedRange، وهو Range يتضمن اسمًا ورقم تعريف لاستخدامهان لاسترداده لاحقًا.
addViewer(emailAddress)Documentلإضافة المستخدم المحدد إلى قائمة مشاهدي Document.
addViewer(user)Documentلإضافة المستخدم المحدد إلى قائمة مشاهدي Document.
addViewers(emailAddresses)Documentلإضافة الصفيف المحدد من المستخدمين إلى قائمة مشاهدي Document.
getAs(contentType)Blobلاسترداد المحتوى الحالي في Document ككائن الكائن من النوع المحدد.
getBlob()Blobاسترداد محتوى Document الحالي ككائنات ثنائية (blob)
getBody()Bodyلاسترداد Body للمستند النشط
getBookmark(id)Bookmarkالحصول على Bookmark بالمعرّف المحدّد
getBookmarks()Bookmark[]لعرض جميع عناصر Bookmark في المستند.
getCursor()Positionتحصل على مؤشر المستخدم في المستند النشط.
getEditors()User[]الحصول على قائمة المحرِّرين لـ Document
getFooter()FooterSectionيسترد قسم تذييل المستند، في حال توفّره.
getFootnotes()Footnote[]استرداد جميع عناصر Footnote في نص المستند
getHeader()HeaderSectionيسترجع قسم رأس المستند، في حال وجوده.
getId()Stringلاسترداد المعرّف الفريد للمستند
getLanguage()Stringللحصول على رمز لغة المستند
getName()Stringلاسترداد عنوان المستند
getNamedRangeById(id)NamedRangeالحصول على NamedRange بالمعرّف المحدّد
getNamedRanges()NamedRange[]لعرض جميع عناصر NamedRange في المستند.
getNamedRanges(name)NamedRange[]الحصول على جميع عناصر NamedRange في المستند بالاسم الذي تم إدخاله
getSelection()Rangeيحصل على اختيار المستخدم في المستند النشط.
getSupportedLanguageCodes()String[]الحصول على جميع رموز اللغات المتوافقة مع ملفات "مستندات Google"
getUrl()Stringلاسترداد عنوان URL للوصول إلى المستند الحالي.
getViewers()User[]الحصول على قائمة المشاهدين والمعلقين لجهاز Document هذا.
newPosition(element, offset)Positionتنشئ السمة Position جديدة، وهي إشارة إلى موقع جغرافي في المستند، بالنسبة إلى عنصر محدّد.
newRange()RangeBuilderتعمل هذه السياسة على إنشاء أداة إنشاء تُستخدَم لإنشاء عناصر Range من عناصر المستندات.
removeEditor(emailAddress)Documentيزيل المستخدم المحدد من قائمة أدوات تحرير Document.
removeEditor(user)Documentيزيل المستخدم المحدد من قائمة أدوات تحرير Document.
removeViewer(emailAddress)Documentإزالة مستخدم معيّن من قائمة المشاهدين والمعلقين في Document
removeViewer(user)Documentإزالة مستخدم معيّن من قائمة المشاهدين والمعلقين في Document
saveAndClose()voidحفظ بيانات Document الحالية
setCursor(position)Documentتضبط هذه السياسة مؤشر المستخدم في المستند النشط، من خلال Position.
setLanguage(languageCode)Documentلضبط رمز لغة المستند.
setName(name)Documentلضبط عنوان المستند.
setSelection(range)Documentتُحدِّد هذه السياسة اختيار المستخدم في المستند النشط، بالنسبة إلى Range.

المستندات التفصيلية

addBookmark(position)

لإضافة Bookmark في Position المحدّد.

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('abc123456');

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

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

// Adds a bookmark at the first character of the paragraph text.
const bookmark = doc.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

addEditor(emailAddress)

لإضافة المستخدم المحدد إلى قائمة محرري Document. إذا كان المستخدم مدرجًا في قائمة المشاهدين، ستنقل هذه الطريقة المستخدم إلى قائمة المشاهدين.

المعلّمات

الاسمالنوعالوصف
emailAddressStringعنوان البريد الإلكتروني للمستخدم الذي تريد إضافته.

رحلة العودة

Document: هذا Document، لسلسلة الكتب.

التفويض

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

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

addEditor(user)

لإضافة المستخدم المحدد إلى قائمة محرري Document. إذا كان المستخدم مدرجًا في قائمة المشاهدين، ستنقل هذه الطريقة المستخدم إلى قائمة المشاهدين.

المعلّمات

الاسمالنوعالوصف
userUserتمثيل المستخدم المراد إضافته.

رحلة العودة

Document: هذا Document، لسلسلة الكتب.

التفويض

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

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

addEditors(emailAddresses)

لإضافة مصفوفة محددة من المستخدمين إلى قائمة المحرِّرين في Document. وإذا كان أيٌّ من المستخدمين مُدرَجًا في قائمة المشاهدين، ستنقلهم هذه الطريقة خارج قائمة المشاهدين.

المعلّمات

الاسمالنوعالوصف
emailAddressesString[]مصفوفة من عناوين البريد الإلكتروني للمستخدمين المطلوب إضافتها.

رحلة العودة

Document: هذا Document، لسلسلة الكتب.

التفويض

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

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

addFooter()

لإضافة قسم تذييل المستند، في حال عدم توفّر أي قسم.

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('abc123456');

// Adds a footer to the document.
const footer = doc.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. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('abc123456');

// Adds a header to the document.
const header = doc.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 document.
var doc = DocumentApp.getActiveDocument();
var rangeBuilder = doc.newRange();
var tables = doc.getBody().getTables();
for (var i = 0; i < tables.length; i++) {
  rangeBuilder.addElement(tables[i]);
}
doc.addNamedRange('Document tables', rangeBuilder.build());

المعلّمات

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

رحلة العودة

NamedRange: NamedRange

التفويض

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

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

addViewer(emailAddress)

لإضافة المستخدم المحدد إلى قائمة مشاهدي Document. إذا كان المستخدم مدرَجًا في قائمة المحرِّرين، لن يكون لهذه الطريقة أي تأثير.

المعلّمات

الاسمالنوعالوصف
emailAddressStringعنوان البريد الإلكتروني للمستخدم الذي تريد إضافته.

رحلة العودة

Document: هذا Document، لسلسلة الكتب.

التفويض

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

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

addViewer(user)

لإضافة المستخدم المحدد إلى قائمة مشاهدي Document. إذا كان المستخدم مدرَجًا في قائمة المحرِّرين، لن يكون لهذه الطريقة أي تأثير.

المعلّمات

الاسمالنوعالوصف
userUserتمثيل المستخدم المراد إضافته.

رحلة العودة

Document: هذا Document، لسلسلة الكتب.

التفويض

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

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

addViewers(emailAddresses)

لإضافة الصفيف المحدد من المستخدمين إلى قائمة مشاهدي Document. إذا كان أي من المستخدمين مُدرجًا في قائمة المحرّرين، لن يكون لهذه الطريقة أي تأثير.

المعلّمات

الاسمالنوعالوصف
emailAddressesString[]مصفوفة من عناوين البريد الإلكتروني للمستخدمين المطلوب إضافتها.

رحلة العودة

Document: هذا Document، لسلسلة الكتب.

التفويض

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

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

getAs(contentType)

لاسترداد المحتوى الحالي في Document ككائن الكائن من النوع المحدد.

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('abc123456');

// Gets the document as a PDF.
const pdf = doc.getAs('application/pdf');

// Logs the name of the PDF to the console.
console.log(pdf.getName());

المعلّمات

الاسمالنوعالوصف
contentTypeStringنوع MIME المطلوب التحويل إليه، ولا يتوفّر في الوقت الحالي سوى 'application/pdf'.

رحلة العودة

Blob: المستند الحالي ككائنات ثنائية (blob)


getBlob()

استرداد محتوى Document الحالي ككائنات ثنائية (blob)

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('abc123456');

// Retrieves the current document's contents as a blob and logs it to the console.
console.log(doc.getBlob().getContentType());

رحلة العودة

Blob: المستند الحالي ككائنات ثنائية (blob)


getBody()

لاسترداد Body للمستند النشط

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

تفويض العناصر في Document إلى تفويض Body النشط.

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('abc123456');

// Gets the document body.
const body = doc.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. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('abc123456');

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

// If the bookmark exists, 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 by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
const doc = DocumentApp.openById('abc123456');

// Gets all of the bookmarks in the document.
const bookmarks = doc.getBookmarks();

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

رحلة العودة

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

التفويض

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

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

getCursor()

تحصل على مؤشر المستخدم في المستند النشط. ولا يمكن للنص البرمجي الوصول إلا إلى مؤشر المستخدم الذي يشغِّل النص البرمجي، فقط إذا تم ربط النص البرمجي بالمستند.

// Insert some text at the cursor position and make it bold.
var cursor = DocumentApp.getActiveDocument().getCursor();
if (cursor) {
  // Attempt to insert text at the cursor position. If the insertion returns null, the cursor's
  // containing element doesn't allow insertions, so show the user an error message.
  var element = cursor.insertText('ಠ‿ಠ');
  if (element) {
    element.setBold(true);
  } else {
    DocumentApp.getUi().alert('Cannot insert text here.');
  }
} else {
  DocumentApp.getUi().alert('Cannot find a cursor.');
}

رحلة العودة

Position - تمثيل بمؤشّر المستخدم أو null إذا لم يكن لدى المستخدم مؤشر ما في المستند أو إذا لم يكن النص البرمجي مرتبطًا بالمستند.

التفويض

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

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

getEditors()

الحصول على قائمة المحرِّرين لـ Document

رحلة العودة

User[]: مصفوفة من المستخدمين الذين لديهم إذن تعديل.

التفويض

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

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

getFooter()

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

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('abc123456');

// Gets the text of the document's footer and logs it to the console.
console.log(doc.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. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('abc123456');

// Gets the first footnote.
const footnote = doc.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. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('abc123456');

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

رحلة العودة

HeaderSection: عنوان المستند.

التفويض

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

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

getId()

لاسترداد المعرّف الفريد للمستند يتم استخدام معرّف المستند مع DocumentApp.openById() لفتح مثيل مستند معيّن.

رحلة العودة

String: رقم تعريف المستند

التفويض

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

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

getLanguage()

للحصول على رمز لغة المستند هذه هي اللغة المعروضة في ملف > لغة محرر المستندات، وقد لا تكون اللغة الفعلية التي يحتوي عليها المستند.

رحلة العودة

String: لغة المستند أو null إذا لم يتم تحديدها

التفويض

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

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

getName()

لاسترداد عنوان المستند

رحلة العودة

String: عنوان المستند

التفويض

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

  • 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

getSelection()

يحصل على اختيار المستخدم في المستند النشط. ولا يمكن للنص البرمجي الوصول إلا إلى تحديد المستخدم الذي يشغّل النص البرمجي، فقط إذا كان النص البرمجي مرتبطًا بالمستند.

// Display a dialog box that tells the user how many elements are included in the selection.
var selection = DocumentApp.getActiveDocument().getSelection();
if (selection) {
  var elements = selection.getRangeElements();
  DocumentApp.getUi().alert('Number of selected elements: ' + elements.length);
} else {
  DocumentApp.getUi().alert('Nothing is selected.');
}

رحلة العودة

Range - تمثيل لاختيار المستخدم أو null إذا لم يكن لدى المستخدم أي عنصر تم اختياره في المستند، أو في حال اختيار نهاية الفقرة فقط، أو في حال اختيار نهاية الفقرة والسطر الجديد فقط، أو في حال عدم ارتباط النص البرمجي بالمستند.

التفويض

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

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

getSupportedLanguageCodes()

الحصول على جميع رموز اللغات المتوافقة مع ملفات "مستندات Google"

رحلة العودة

String[]: مصفوفة من رموز اللغات.

التفويض

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

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

getUrl()

لاسترداد عنوان URL للوصول إلى المستند الحالي.

var doc = DocumentApp.getActiveDocument();

// Send out the link to open the document.
MailApp.sendEmail("<email-address>", doc.getName(), doc.getUrl());

رحلة العودة

String: عنوان URL للوصول إلى المستند الحالي

التفويض

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

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

getViewers()

الحصول على قائمة المشاهدين والمعلقين لجهاز Document هذا.

رحلة العودة

User[]: مصفوفة من المستخدمين الذين لديهم إذن للعرض أو التعليق.

التفويض

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

  • 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.getActiveDocument();
var paragraph = doc.getBody().appendParagraph('My new paragraph.');
var position = doc.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 document.
var doc = DocumentApp.getActiveDocument();
var rangeBuilder = doc.newRange();
var tables = doc.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

removeEditor(emailAddress)

يزيل المستخدم المحدد من قائمة أدوات تحرير Document. ولا تمنع هذه الطريقة المستخدمين من الوصول إلى Document إذا كانوا ينتمون إلى فئة مستخدمين لديهم إذن الوصول العام، مثلاً في حال مشاركة Document مع نطاق المستخدم بالكامل، أو إذا كانت Document في مساحة تخزين سحابي مشتركة يمكن للمستخدم الوصول إليها.

بالنسبة إلى ملفات Drive، يؤدي ذلك أيضًا إلى إزالة المستخدم من قائمة المشاهدين.

المعلّمات

الاسمالنوعالوصف
emailAddressStringعنوان البريد الإلكتروني للمستخدم المطلوب إزالته.

رحلة العودة

Document: هذا Document، لسلسلة الكتب.

التفويض

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

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

removeEditor(user)

يزيل المستخدم المحدد من قائمة أدوات تحرير Document. ولا تمنع هذه الطريقة المستخدمين من الوصول إلى Document إذا كانوا ينتمون إلى فئة مستخدمين لديهم إذن الوصول العام، مثلاً في حال مشاركة Document مع نطاق المستخدم بالكامل، أو إذا كانت Document في مساحة تخزين سحابي مشتركة يمكن للمستخدم الوصول إليها.

بالنسبة إلى ملفات Drive، يؤدي ذلك أيضًا إلى إزالة المستخدم من قائمة المشاهدين.

المعلّمات

الاسمالنوعالوصف
userUserتمثيل للمستخدم المطلوب إزالته

رحلة العودة

Document: هذا Document، لسلسلة الكتب.

التفويض

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

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

removeViewer(emailAddress)

إزالة مستخدم معيّن من قائمة المشاهدين والمعلقين في Document ليس لهذه الطريقة أي تأثير إذا كان المستخدم محرِّرًا، وليس مشاهدًا أو معلِّقًا. ولا تحظر هذه الطريقة أيضًا المستخدمين من الوصول إلى Document إذا كانوا ينتمون إلى فئة مستخدمين لديهم إذن الوصول العام، مثلاً في حال مشاركة Document مع النطاق الكامل للمستخدم أو إذا كانت Document في مساحة تخزين سحابي مشتركة يمكن للمستخدم الوصول إليها.

بالنسبة إلى ملفات Drive، يؤدي ذلك أيضًا إلى إزالة المستخدم من قائمة المحرِّرين.

المعلّمات

الاسمالنوعالوصف
emailAddressStringعنوان البريد الإلكتروني للمستخدم المطلوب إزالته.

رحلة العودة

Document: هذا Document لسلسلة الكتب.

التفويض

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

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

removeViewer(user)

إزالة مستخدم معيّن من قائمة المشاهدين والمعلقين في Document ليس لهذه الطريقة أي تأثير إذا كان المستخدم محرِّرًا، وليس مشاهدًا. ولا تحظر هذه الطريقة أيضًا المستخدمين من الوصول إلى Document إذا كانوا ينتمون إلى فئة من المستخدمين لديهم إذن وصول عام، مثل في حال مشاركة Document مع نطاق المستخدم بالكامل، أو إذا كانت Document في مساحة تخزين سحابي مشتركة يمكن للمستخدم الوصول إليها.

بالنسبة إلى ملفات Drive، يؤدي ذلك أيضًا إلى إزالة المستخدم من قائمة المحرِّرين.

المعلّمات

الاسمالنوعالوصف
userUserتمثيل للمستخدم المطلوب إزالته

رحلة العودة

Document: هذا Document لسلسلة الكتب.

التفويض

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

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

saveAndClose()

حفظ بيانات Document الحالية يؤدي إلى محو بيانات تطبيق التحديثات في انتظار المراجعة.

تُستدعى الطريقة saveAndClose() تلقائيًا في نهاية تنفيذ النص البرمجي لكل Document مفتوحة وقابلة للتعديل.

لا يمكن تعديل Document مغلقة. يمكنك استخدام DocumentApp.openById() لإعادة فتح مستند مُخصص للتعديل.

التفويض

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

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

setCursor(position)

تضبط هذه السياسة مؤشر المستخدم في المستند النشط، من خلال Position. ولا يمكن للنص البرمجي الوصول إلا إلى مؤشر المستخدم الذي يشغِّل النص البرمجي، فقط إذا كان النص البرمجي مرتبطًا بالمستند.

// Append a paragraph, then place the user's cursor after the first word of the new paragraph.
var doc = DocumentApp.getActiveDocument();
var paragraph = doc.getBody().appendParagraph('My new paragraph.');
var position = doc.newPosition(paragraph.getChild(0), 2);
doc.setCursor(position);

المعلّمات

الاسمالنوعالوصف
positionPositionالموقع الجغرافي الجديد للمؤشر

رحلة العودة

Document: هذا Document، لسلسلة الكتب

التفويض

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

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

setLanguage(languageCode)

لضبط رمز لغة المستند. هذه هي اللغة المعروضة في ملف > لغة محرر المستندات، وقد لا تكون اللغة الفعلية التي يحتوي عليها المستند. يمكنك استخدام getSupportedLanguageCodes() للحصول على جميع رموز اللغات الصالحة.

المعلّمات

الاسمالنوعالوصف
languageCodeStringرمز اللغة.

رحلة العودة

Document: هذا Document، لسلسلة الكتب.

التفويض

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

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

setName(name)

لضبط عنوان المستند.

المعلّمات

الاسمالنوعالوصف
nameStringعنوان المستند الجديد

رحلة العودة

Document: المستند الحالي

التفويض

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

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

setSelection(range)

تُحدِّد هذه السياسة اختيار المستخدم في المستند النشط، بالنسبة إلى Range. ولا يمكن للنص البرمجي الوصول إلا إلى اختيار المستخدم الذي يشغِّل النص البرمجي، فقط إذا كان النص البرمجي مرتبطًا بالمستند.

// Change the user's selection to a range that includes every table in the document.
var doc = DocumentApp.getActiveDocument();
var rangeBuilder = doc.newRange();
var tables = doc.getBody().getTables();
for (var i = 0; i < tables.length; i++) {
  rangeBuilder.addElement(tables[i]);
}
doc.setSelection(rangeBuilder.build());

المعلّمات

الاسمالنوعالوصف
rangeRangeالنطاق الجديد من العناصر للاختيار

رحلة العودة

Document: هذا Document، لسلسلة الكتب

التفويض

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

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