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 الحالي على شكل كائن ثنائي كبير (blob) من النوع المحدد.
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());

}

المَعلمات

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

استرجاع الكرة

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

التفويض

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

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

addEditor(emailAddress)

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

المَعلمات

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

استرجاع الكرة

Document - جهاز Document هذا للسلاسل

التفويض

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

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

addEditor(user)

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

المَعلمات

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

استرجاع الكرة

Document - جهاز Document هذا للسلاسل

التفويض

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

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

addEditors(emailAddresses)

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

المَعلمات

الاسمTypeالوصف
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());

المَعلمات

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

استرجاع الكرة

NamedRangeNamedRange.

التفويض

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

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

addViewer(emailAddress)

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

المَعلمات

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

استرجاع الكرة

Document - جهاز Document هذا للسلاسل

التفويض

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

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

addViewer(user)

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

المَعلمات

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

استرجاع الكرة

Document - جهاز Document هذا للسلاسل

التفويض

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

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

addViewers(emailAddresses)

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

المَعلمات

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

استرجاع الكرة

Document - جهاز Document هذا للسلاسل

التفويض

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

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

getAs(contentType)

لاسترداد محتوى 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');

// 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());

المَعلمات

الاسمTypeالوصف
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.');
}

المَعلمات

الاسمTypeالوصف
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.

المَعلمات

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

المَعلمات

الاسمTypeالوصف
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);

المَعلمات

الاسمTypeالوصف
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، سيؤدي هذا أيضًا إلى إزالة المستخدم من قائمة العارضين.

المَعلمات

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

استرجاع الكرة

Document - جهاز Document هذا للسلاسل

التفويض

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

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

removeEditor(user)

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

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

المَعلمات

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

استرجاع الكرة

Document - جهاز Document هذا للسلاسل

التفويض

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

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

removeViewer(emailAddress)

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

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

المَعلمات

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

استرجاع الكرة

Document - جهاز Document هذا للسلاسل

التفويض

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

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

removeViewer(user)

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

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

المَعلمات

الاسمTypeالوصف
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);

المَعلمات

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

استرجاع الكرة

Document — جهاز Document هذا للسلاسل

التفويض

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

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

setLanguage(languageCode)

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

المَعلمات

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

استرجاع الكرة

Document - جهاز Document هذا للسلاسل

التفويض

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

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

setName(name)

لتعيين عنوان المستند.

المَعلمات

الاسمTypeالوصف
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());

المَعلمات

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

استرجاع الكرة

Document — جهاز Document هذا للسلاسل

التفويض

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

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