مستند يحتوي على عنصر Tab
واحد أو أكثر، يحتوي كلٌّ منها على نص غني وعناصر
مثل الجداول والقوائم
يمكن فتح المستندات أو إنشاؤها باستخدام Document
.
// Open a document by ID. let doc = DocumentApp.openById('<my-id>'); // Create and open a document. doc = DocumentApp.create('Document Title');
تعمل طُرق فئة Document
التي تُدخل مباشرةً إلى محتوى النص وتُعدّله على
إما علامة التبويب النشطة (في النصوص البرمجية المرتبطة بأحد
المستندات المحدّدة) أو علامة التبويب الأولى (إذا لم تكن علامة تبويب نشطة متاحة). يمكن نقل النصوص البرمجية التي تعتمد على
هذه الطرق (مثل get
) إلى علامات التبويب المتوافقة باستخدام
get
ثم Tab.asDocumentTab()
.
الطُرق
الطريقة | نوع القيمة التي يتم عرضها | وصف قصير |
---|---|---|
add | Bookmark | تُضيف Bookmark في Position المحدَّد إلى علامة التبويب الأولى أو علامة التبويب النشطة في النصوص البرمجية التي يتم
ربطها بمستند. |
add | Document | تُضيف هذه السمة المستخدم المحدَّد إلى قائمة المحرِّرين في Document . |
add | Document | تُضيف هذه السمة المستخدم المحدَّد إلى قائمة المحرِّرين في Document . |
add | Document | تُضيف الصفيف المحدَّد من المستخدمين إلى قائمة المحرِّرين في Document . |
add | Footer | تُضيف هذه السمة قسم تذييل، في حال عدم توفّره، إلى علامة التبويب الأولى أو علامة التبويب النشطة في النصوص البرمجية التي تكون مرتبطة بمستند. |
add | Header | تُضيف هذه السمة قسمًا للعنوان، إذا لم يكن متوفّرًا، إلى علامة التبويب الأولى أو علامة التبويب النشطة في النصوص البرمجية التي تكون مرتبطة بمستند. |
add | Named | تُضيف Named ، وهي Range لها اسم ورقم تعريف لاستخدامهما في
الاسترداد لاحقًا، في علامة التبويب الأولى أو علامة التبويب النشطة للنص البرمجي المرتبط بمستند. |
add | Document | تُضيف هذه السمة المستخدم المحدّد إلى قائمة المشاهدين في Document . |
add | Document | تُضيف هذه السمة المستخدم المحدّد إلى قائمة المشاهدين في Document . |
add | Document | تُضيف الصفيف المحدّد من المستخدِمين إلى قائمة المشاهدين في Document . |
get | Tab | تحصل على Tab النشطة حاليًا للمستخدم في المستند. |
get | Blob | يسترجع محتوى Document الحالي ككتلة بيانات من النوع المحدّد. |
get | Blob | يسترجع محتوى Document الحالي ككتلة بيانات. |
get | Body | يسترجع Body علامة التبويب الأولى أو Document علامة التبويب النشطة للنصوص البرمجية التي تكون مرتبطة بمستند. |
get | Bookmark | تحصل على Bookmark التي تحمل المعرّف المحدّد في علامة التبويب الأولى أو علامة التبويب النشطة للنصوص البرمجية التي تكون مرتبطة بمستند. |
get | Bookmark[] | تحصل على جميع عناصر Bookmark في علامة التبويب الأولى أو علامة التبويب النشطة في النصوص البرمجية التي تكون مرتبطة بمستند. |
get | Position | تحصل على مؤشر المستخدم في علامة التبويب النشطة. |
get | User[] | تحصل على قائمة بالمحرِّرين لهذا Document . |
get | Footer | يسترجع القسم الخاص بآخر صفحة في علامة التبويب الأولى، أو القسم الخاص بآخر صفحة في علامة التبويب النشطة، في حال النصوص البرمجية المرتبطة بمستند. |
get | Footnote[] | يسترجع هذا الإجراء جميع عناصر Footnote في نص علامة التبويب الأولى أو نص علامة التبويب النشطة في النصوص البرمجية التي تكون مرتبطة بمستند. |
get | Header | يسترجع قسم العنوان في علامة التبويب الأولى أو قسم العنوان في علامة التبويب النشطة للنص البرمجي المرتبط بمستند. |
get | String | يسترجع المعرّف الفريد للمستند. |
get | String | تحصل على رمز لغة المستند. |
get | String | استرداد عنوان المستند |
get | Named | تحصل على Named التي تحمل المعرّف المحدّد في علامة التبويب الأولى أو علامة التبويب النشطة للنصوص البرمجية التي تكون مرتبطة بمستند. |
get | Named | تحصل على جميع عناصر Named في علامة التبويب الأولى أو علامة التبويب النشطة في النصوص البرمجية التي تكون مرتبطة بمستند. |
get | Named | تحصل على جميع عناصر Named التي تحمل الاسم المحدّد في علامة التبويب الأولى أو علامة التبويب النشطة في النصوص البرمجية التي
ترتبط بمستند. |
get | Range | تحصل على اختيار المستخدم في علامة التبويب "نشط". |
get | String[] | تحصل على جميع رموز اللغات المتوافقة مع ملفات "مستندات Google". |
get | Tab | تحصل على Tab بالمعرّف المحدّد. |
get | Tab[] | تحصل على كل Tab غير المُدمجة التي تشكّل جزءًا من المستند. |
get | String | يسترجع عنوان URL للوصول إلى المستند الحالي. |
get | User[] | تحصل على قائمة بالمشاهدين والمعلقين لهذا Document . |
new | Position | لإنشاء Position جديد، وهو إشارة إلى موضع في علامة التبويب، بالنسبة إلى
عنصر معيّن في علامة التبويب الأولى أو علامة التبويب النشطة في النصوص البرمجية التي تكون مرتبطة بمستند. |
new | Range | تُنشئ هذه الوظيفة أداة إنشاء تُستخدَم لإنشاء كائنات Range من عناصر علامات التبويب في
العلامة التبويب الأولى أو العلامة التبويب النشطة في حالة النصوص البرمجية التي تكون مرتبطة بأحد
المستندات. |
remove | Document | تزيل هذه الدالة المستخدم المحدَّد من قائمة المحرِّرين في Document . |
remove | Document | تزيل هذه الدالة المستخدم المحدَّد من قائمة المحرِّرين في Document . |
remove | Document | تزيل هذه السمة المستخدم المحدّد من قائمة المشاهدين والمعلّقين في Document . |
remove | Document | تزيل هذه السمة المستخدم المحدّد من قائمة المشاهدين والمعلّقين في Document . |
save | void | تحفظ Document الحالية. |
set | void | تُستخدَم لضبط Tab التي اختارها المستخدم في المستند الحالي على علامة التبويب التي تحمل المعرّف المحدّد. |
set | Document | تُحدِّد مؤشر المستخدِم، مع الأخذ في الاعتبار Position . |
set | Document | لضبط رمز لغة المستند. |
set | Document | لضبط عنوان المستند |
set | Document | تُستخدَم لضبط اختيار المستخدِم في علامة التبويب "نشط"، مع الأخذ في الاعتبار Range . |
مستندات تفصيلية
add Bookmark(position)
تُضيف Bookmark
في Position
المحدَّد إلى علامة التبويب الأولى أو علامة التبويب النشطة في النصوص البرمجية التي يتم
ربطها بمستند. لإضافة bookmarked
إلى أي علامة تبويب، استخدِم الطريقة 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('123abc'); // Gets the active or first tab's 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());
المعلمات
الاسم | النوع | الوصف |
---|---|---|
position | Position | موضع الإشارة المرجعية الجديدة. |
الإرجاع
Bookmark
: الإشارة المرجعية الجديدة
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
add Editor(emailAddress)
تُضيف هذه السمة المستخدم المحدَّد إلى قائمة المحرِّرين في Document
. إذا كان المستخدم مُدرَجًا في قائمة المشاهدين، تُخرج هذه الطريقة المستخدم من قائمة المشاهدين.
المعلمات
الاسم | النوع | الوصف |
---|---|---|
email | String | عنوان البريد الإلكتروني للمستخدم الذي تريد إضافته |
الإرجاع
Document
— هذا الرمز Document
، لإنشاء سلسلة.
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
add Editor(user)
تُضيف هذه السمة المستخدم المحدَّد إلى قائمة المحرِّرين في Document
. إذا كان المستخدم مُدرَجًا في قائمة المشاهدين، تُخرج هذه الطريقة المستخدم من قائمة المشاهدين.
المعلمات
الاسم | النوع | الوصف |
---|---|---|
user | User | تمثيل للمستخدم المطلوب إضافته |
الإرجاع
Document
— هذا الرمز Document
، لإنشاء سلسلة.
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
add Editors(emailAddresses)
تُضيف الصفيف المحدَّد من المستخدمين إلى قائمة المحرِّرين في Document
. إذا كان أيّ من
المستخدِمين مدرَجًا في قائمة المشاهدين، ستؤدي هذه الطريقة إلى إزالته من قائمة
المشاهدين.
المعلمات
الاسم | النوع | الوصف |
---|---|---|
email | String[] | صفيف من عناوين البريد الإلكتروني للمستخدمين المطلوب إضافتهم |
الإرجاع
Document
— هذا الرمز Document
، لإنشاء سلسلة.
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
add Header()
تُضيف هذه السمة قسمًا للعنوان، إذا لم يكن متوفّرًا، إلى علامة التبويب الأولى أو علامة التبويب النشطة في النصوص البرمجية التي تكون مرتبطة بمستند. لإضافة قسم عنوان
إلى أي علامة تبويب، استخدِم الطريقة 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('123abc'); // Adds a header to the document's active or first tab. const header = doc.addHeader(); // Sets the header text to 'This is a header.' header.setText('This is a header');
الإرجاع
Header
: عنوان علامة التبويب
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
add Named Range(name, range)
تُضيف Named
، وهي Range
لها اسم ورقم تعريف لاستخدامهما في
الاسترداد لاحقًا، في علامة التبويب الأولى أو علامة التبويب النشطة للنص البرمجي المرتبط بمستند. لإضافة Named
في أي علامة تبويب، استخدِم الطريقة Document
. لا تكون الأسماء
فريدة بالضرورة، إذ يمكن أن تتشارك عدة نطاقات مختلفة في المستند نفسه الاسم نفسه، تمامًا
مثل فئة في HTML. في المقابل، تكون المعرّفات فريدة داخل المستند، مثل المعرّف في HTML.
بعد إضافة Named
إلى مستند، لا يمكنك تعديله، بل يمكنك إزالته فقط.
يمكن لأي نص برمجي يصل إلى المستند الوصول إلى Named
. لتجنّب التعارضات العميقة بين النصوص البرمجية، ننصحك بإضافة سلسلة فريدة إلى أسماء النطاقات.
// Creates a named range that includes every table in the active tab. const doc = DocumentApp.getActiveDocument(); const rangeBuilder = doc.newRange(); const tables = doc.getBody().getTables(); for (let i = 0; i < tables.length; i++) { rangeBuilder.addElement(tables[i]); } // Adds the named range to the document's active tab. doc.addNamedRange('Document tables', rangeBuilder.build());
المعلمات
الاسم | النوع | الوصف |
---|---|---|
name | String | اسم النطاق، والذي لا يلزم أن يكون فريدًا، ويجب أن تتراوح أسماء النطاقات بين 1 و256 حرفًا. |
range | Range | نطاق العناصر المطلوب ربطها بالاسم، ويمكن أن يكون النطاق الاختيار النشط أو نتيجة بحث أو نطاقًا تم إنشاؤه يدويًا باستخدام new . |
الإرجاع
Named
— Named
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
add Viewer(emailAddress)
تُضيف هذه السمة المستخدم المحدّد إلى قائمة المشاهدين في Document
. إذا كان المستخدم مُدرَجًا في قائمة المحرِّرين، لن يكون لهذه الطريقة أي تأثير.
المعلمات
الاسم | النوع | الوصف |
---|---|---|
email | String | عنوان البريد الإلكتروني للمستخدم الذي تريد إضافته |
الإرجاع
Document
— هذا الرمز Document
، لإنشاء سلسلة.
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
add Viewer(user)
تُضيف هذه السمة المستخدم المحدّد إلى قائمة المشاهدين في Document
. إذا كان المستخدم مُدرَجًا في قائمة المحرِّرين، لن يكون لهذه الطريقة أي تأثير.
المعلمات
الاسم | النوع | الوصف |
---|---|---|
user | User | تمثيل للمستخدم المطلوب إضافته |
الإرجاع
Document
— هذا الرمز Document
، لإنشاء سلسلة.
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
add Viewers(emailAddresses)
تُضيف الصفيف المحدّد من المستخدِمين إلى قائمة المشاهدين في Document
. إذا كان أي من
المستخدِمين مدرَجًا في قائمة المحرِّرين، لن يكون لهذه الطريقة أي تأثير عليه.
المعلمات
الاسم | النوع | الوصف |
---|---|---|
email | String[] | صفيف من عناوين البريد الإلكتروني للمستخدمين المطلوب إضافتهم |
الإرجاع
Document
— هذا الرمز Document
، لإنشاء سلسلة.
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
get Active Tab()
تحصل على Tab
النشطة حاليًا للمستخدم في المستند. لا يمكن للنص البرمجي الوصول إلا إلى
علامة التبويب النشطة للمستخدم الذي يشغّل النص البرمجي، وذلك فقط إذا كان النص البرمجي مرتبطًا بالمستند.
// Display a dialog box that shows the title of the tab that the // user is currently viewing. const tab = DocumentApp.getActiveDocument().getActiveTab(); DocumentApp.getUi().alert(`ID of selected tab: ${tab.getTitle()}`);
الإرجاع
Tab
: Tab
النشط حاليًا للمستخدم، أو null
إذا لم يكن النص البرمجي مرتبطًا
بالمستند
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
get As(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('123abc'); // 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());
المعلمات
الاسم | النوع | الوصف |
---|---|---|
content | String | نوع MIME المطلوب التحويل إليه: 'application/pdf' و'text/markdown' متاحان. |
الإرجاع
Blob
: المستند الحالي ككتلة بيانات
get Blob()
يسترجع محتوى 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('123abc'); // Retrieves the current document's contents as a blob and logs it to the // console. console.log(doc.getBlob().getContentType());
الإرجاع
Blob
: المستند الحالي ككتلة بيانات
get Body()
يسترجع Body
علامة التبويب الأولى أو Document
علامة التبويب النشطة للنصوص البرمجية التي تكون مرتبطة بمستند. للحصول على Document
لأي علامة تبويب، استخدِم طريقة Document
.
قد تحتوي علامات التبويب على أنواع مختلفة من الأقسام (على سبيل المثال، Header
وFooter
). القسم النشط لعلامة التبويب هو 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('123abc'); // Gets the active or first tab's 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
get Bookmark(id)
تحصل على Bookmark
التي تحمل المعرّف المحدّد في علامة التبويب الأولى أو علامة التبويب النشطة للنصوص البرمجية التي تكون مرتبطة بمستند. للحصول على bookmarked في أي علامة تبويب، استخدِم الطريقة Document
. تعرِض هذه الطريقة القيمة 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('123abc'); // Gets the bookmark by its ID in the document's active or first tab. 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.'); }
المعلمات
الاسم | النوع | الوصف |
---|---|---|
id | String | رقم تعريف Bookmark . |
الإرجاع
Bookmark
: Bookmark
الذي يحمل رقم التعريف المحدّد، أو null
إذا لم يكن هناك Bookmark
ضمن علامة التبويب.
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
get Bookmarks()
تحصل على جميع عناصر Bookmark
في علامة التبويب الأولى أو علامة التبويب النشطة في النصوص البرمجية التي تكون مرتبطة بمستند. للحصول على كل
الإشارات المرجعية في أي علامة تبويب، استخدِم الطريقة 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. const doc = DocumentApp.openById('123abc'); // Gets all of the bookmarks in the document's active or first tab. const bookmarks = doc.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
get Cursor()
تحصل على مؤشر المستخدم في علامة التبويب النشطة. لا يمكن للنص البرمجي الوصول إلى مؤشر المستخدم الذي يشغّل النص البرمجي إلا إذا كان النص البرمجي مرتبطًا بالمستند.
// Insert some text at the cursor position and make it bold. const 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. const 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
get Editors()
تحصل على قائمة بالمحرِّرين لهذا Document
.
الإرجاع
User[]
: صفيف من المستخدمين الذين لديهم إذن التعديل
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
get Footnotes()
يسترجع هذا الإجراء جميع عناصر Footnote
في نص علامة التبويب الأولى أو نص علامة التبويب النشطة في النصوص البرمجية التي تكون مرتبطة بمستند. للحصول على
كل الحواشي السفلية في أي علامة تبويب، استخدِم الطريقة Document
.
تؤدي طلبات get
إلى تكرار عناصر علامة التبويب. بالنسبة إلى علامات التبويب الكبيرة،
تجنَّب إجراء مكالمات غير ضرورية إلى هذه الطريقة.
// 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('123abc'); // Gets the first footnote in the active or first tab's body. 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
get Header()
يسترجع قسم العنوان في علامة التبويب الأولى أو قسم العنوان
في علامة التبويب النشطة للنص البرمجي المرتبط بمستند. للحصول على قسم العنوان لأي علامة تبويب، استخدِم الطريقة 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('123abc'); // Gets the text of the active or first tab's header and logs it to the console. console.log(doc.getHeader().getText());
الإرجاع
Header
: عنوان علامة التبويب
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
get Id()
يسترجع المعرّف الفريد للمستند. يتم استخدام معرّف المستند مع Document
لفتح مثيل مستند معيّن.
الإرجاع
String
: رقم تعريف المستند
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
get Language()
تحصل على رمز لغة المستند. هذه هي اللغة المعروضة في ملف > اللغة في محرِّر المستندات، وقد لا تكون هي اللغة الفعلية التي يتضمّنها المستند.
الإرجاع
String
: لغة المستند، أو null
في حال عدم تحديدها
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
get Name()
استرداد عنوان المستند
الإرجاع
String
: عنوان المستند.
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
get Named Range By Id(id)
تحصل على Named
التي تحمل المعرّف المحدّد في علامة التبويب الأولى أو علامة التبويب النشطة للنصوص البرمجية التي تكون مرتبطة بمستند. للحصول على
Named
بالرقم التعريفي المحدّد في أي علامة تبويب، استخدِم الطريقة Document
. تعرِض هذه الطريقة null
إذا لم يكن هناك Named
في علامة التبويب. إنّ الأسماء
ليست فريدة بالضرورة، حتى في علامات التبويب المختلفة، إذ قد تشترك عدة نطاقات مختلفة في علامة التبويب نفسها
بالاسم نفسه، تمامًا مثل فئة في HTML. في المقابل، تكون الأرقام التعريفية فريدة داخل علامة التبويب،
مثل رقم تعريف في HTML.
المعلمات
الاسم | النوع | الوصف |
---|---|---|
id | String | رقم تعريف النطاق، وهو فريد داخل علامة التبويب. |
الإرجاع
Named
: Named
التي تحمل رقم التعريف المحدّد، أو null
إذا لم يكن هناك نطاق مماثل في
التبويب
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
get Named Ranges()
تحصل على جميع عناصر Named
في علامة التبويب الأولى أو علامة التبويب النشطة في النصوص البرمجية التي تكون مرتبطة بمستند. للحصول على كل كائنات
Named
في أي علامة تبويب، استخدِم الطريقة Document
.
يمكن الوصول إلى Named
من خلال أي نص برمجي يصل إلى علامة التبويب. لتجنُّب
التعارضات غير المقصودة بين النصوص البرمجية، ننصحك بإضافة سلسلة فريدة إلى أسماء النطاقات.
الإرجاع
Named
: صفيف من عناصر Named
في علامة التبويب، قد يتضمّن نطاقات متعددة
تحمل الاسم نفسه.
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
get Named Ranges(name)
تحصل على جميع عناصر Named
التي تحمل الاسم المحدّد في علامة التبويب الأولى أو علامة التبويب النشطة في النصوص البرمجية التي
ترتبط بمستند. للحصول على
جميع عناصر Named
في أي علامة تبويب، استخدِم الطريقة Document
. لا تكون الأسماء فريدة بالضرورة، حتى في علامات التبويب المختلفة، إذ قد تتشارك عدة نطاقات مختلفة في
علامة التبويب نفسها الاسم نفسه، تمامًا مثل فئة في HTML. في المقابل، تكون المعرّفات فريدة
داخل علامة التبويب، مثل المعرّف في HTML.
يمكن الوصول إلى Named
من خلال أي نص برمجي يصل إلى المستند. لتجنُّب
التعارضات غير المقصودة بين النصوص البرمجية، ننصحك بإضافة سلسلة فريدة إلى أسماء النطاقات.
المعلمات
الاسم | النوع | الوصف |
---|---|---|
name | String | اسم النطاق، الذي لا يكون فريدًا بالضرورة |
الإرجاع
Named
: صفيف من عناصر Named
في علامة التبويب التي تحمل الاسم المحدّد
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
get Selection()
تحصل على اختيار المستخدم في علامة التبويب "نشط". لا يمكن للنص البرمجي الوصول إلا إلى اختيار المستخدم الذي يشغّل النص البرمجي، ولا يمكنه ذلك إلا إذا كان النص البرمجي مرتبطًا بالمستند.
// Display a dialog box that tells the user how many elements are included in // the selection. const selection = DocumentApp.getActiveDocument().getSelection(); if (selection) { const 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
get Supported Language Codes()
تحصل على جميع رموز اللغات المتوافقة مع ملفات "مستندات Google".
الإرجاع
String[]
: صفيف من رموز اللغات
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
get Tab(tabId)
تحصل على Tab
بالمعرّف المحدّد. تعرِض هذه الطريقة القيمة null
إذا لم يكن هناك Tab
من هذا النوع. يمكن الوصول إلى علامات التبويب على أي مستوى من مستويات الدمج.
المعلمات
الاسم | النوع | الوصف |
---|---|---|
tab | String | رقم تعريف علامة التبويب المطلوب الحصول عليها. |
الإرجاع
Tab
: Tab
الذي يحمل رقم التعريف المحدّد، أو null
إذا لم يكن هناك Tab
بهذا الرقم
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
get Tabs()
تحصل على كل Tab
غير المُدمجة التي تشكّل جزءًا من المستند.
يمكن أن تحتوي علامات التبويب على علامات تبويب فرعية، وهي علامة تبويب مضمّنة في علامة تبويب أخرى. يمكن الوصول إلى علامات التبويب الفرعية
باستخدام Tab.getChildTabs()
.
الإرجاع
Tab[]
: قائمة بجميع Tab
التي تشكّل جزءًا من المستند
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
get Url()
يسترجع عنوان URL للوصول إلى المستند الحالي.
const 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
get Viewers()
تحصل على قائمة بالمشاهدين والمعلقين لهذا Document
.
الإرجاع
User[]
: صفيف من المستخدمين الذين لديهم إذن بالاطّلاع أو التعليق
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
new Position(element, offset)
لإنشاء Position
جديد، وهو إشارة إلى موضع في علامة التبويب، بالنسبة إلى
عنصر معيّن في علامة التبويب الأولى أو علامة التبويب النشطة في النصوص البرمجية التي تكون مرتبطة بمستند. لإنشاء
Position
نسبةً إلى موقع في أي علامة تبويب، استخدِم الطريقة Document
. يتم تمثيل مؤشر المستخدم على شكل Position
، من بين استخدامات أخرى.
// Append a paragraph to the active tab, then place the user's cursor after the // first word of the new paragraph. const doc = DocumentApp.getActiveDocument(); const paragraph = doc.getBody().appendParagraph('My new paragraph.'); const position = doc.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
new Range()
تُنشئ هذه الوظيفة أداة إنشاء تُستخدَم لإنشاء كائنات Range
من عناصر علامات التبويب في
العلامة التبويب الأولى أو العلامة التبويب النشطة في حالة النصوص البرمجية التي تكون مرتبطة بأحد
المستندات. لإنشاء أداة إنشاء تُستخدَم لإنشاء كائنات Document
من عناصر علامة التبويب في أي علامة تبويب، استخدِم طريقة Document
.
// Change the user's selection to a range that includes every table in the // active tab. const doc = DocumentApp.getActiveDocument(); const rangeBuilder = doc.newRange(); const tables = doc.getBody().getTables(); for (let i = 0; i < tables.length; i++) { rangeBuilder.addElement(tables[i]); } doc.setSelection(rangeBuilder.build());
الإرجاع
Range
- أداة الإنشاء الجديدة
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
remove Editor(emailAddress)
تزيل هذه الدالة المستخدم المحدَّد من قائمة المحرِّرين في Document
. لا تؤدي هذه الطريقة إلى منع المستخدمين من الوصول إلى Document
إذا كانوا ينتمون إلى فئة من المستخدمين الذين لديهم إذن بالوصول العام، على سبيل المثال، إذا تمت مشاركة Document
مع Document
للمستخدم بالكامل، أو إذا كان Document
في مساحة تخزين سحابي مشتركة يمكن للمستخدم الوصول إليها.
بالنسبة إلى ملفات Drive، يؤدي ذلك أيضًا إلى إزالة المستخدم من قائمة المشاهدين.
المعلمات
الاسم | النوع | الوصف |
---|---|---|
email | String | عنوان البريد الإلكتروني للمستخدم المطلوب إزالته |
الإرجاع
Document
— هذا الرمز Document
، لإنشاء سلسلة.
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
remove Editor(user)
تزيل هذه الدالة المستخدم المحدَّد من قائمة المحرِّرين في Document
. لا تؤدي هذه الطريقة إلى منع المستخدمين من الوصول إلى Document
إذا كانوا ينتمون إلى فئة من المستخدمين الذين لديهم إذن بالوصول العام، على سبيل المثال، إذا تمت مشاركة Document
مع Document
للمستخدم بالكامل، أو إذا كان Document
في مساحة تخزين سحابي مشتركة يمكن للمستخدم الوصول إليها.
بالنسبة إلى ملفات Drive، يؤدي ذلك أيضًا إلى إزالة المستخدم من قائمة المشاهدين.
المعلمات
الاسم | النوع | الوصف |
---|---|---|
user | User | تمثيل للمستخدم المطلوب إزالته |
الإرجاع
Document
— هذا الرمز Document
، لإنشاء سلسلة.
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
remove Viewer(emailAddress)
تزيل هذه السمة المستخدم المحدّد من قائمة المشاهدين والمعلّقين في Document
. لا تؤثّر هذه المحاولة في حال كان المستخدم محرِّرًا وليس مشاهدًا أو معلِقًا. لا تحظر هذه الطريقة أيضًا
المستخدمين من الوصول إلى Document
إذا كانوا ينتمون إلى فئة من المستخدمين الذين لديهم
إذن وصول عام، على سبيل المثال، إذا تمت مشاركة Document
مع
نطاق المستخدم بالكامل، أو إذا كان Document
في مساحة تخزين سحابي مشتركة يمكن للمستخدم الوصول إليها.Document
بالنسبة إلى ملفات Drive، يؤدي ذلك أيضًا إلى إزالة المستخدم من قائمة المحرِّرين.
المعلمات
الاسم | النوع | الوصف |
---|---|---|
email | String | عنوان البريد الإلكتروني للمستخدم المطلوب إزالته |
الإرجاع
Document
— هذا Document
لإنشاء سلسلة.
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
remove Viewer(user)
تزيل هذه السمة المستخدم المحدّد من قائمة المشاهدين والمعلّقين في Document
. لا تؤثر هذه المحاولة في حال كان المستخدم محرِّرًا وليس مُشاهدًا. لا تحظر هذه الطريقة أيضًا
المستخدمين من الوصول إلى Document
إذا كانوا ينتمون إلى فئة من المستخدمين الذين لديهم
إذن وصول عام، على سبيل المثال، إذا تمت مشاركة Document
مع نطاق المستخدم بالكامل، أو
إذا كان Document
في مساحة تخزين سحابي مشتركة يمكن للمستخدم الوصول إليها.
بالنسبة إلى ملفات Drive، يؤدي ذلك أيضًا إلى إزالة المستخدم من قائمة المحرِّرين.
المعلمات
الاسم | النوع | الوصف |
---|---|---|
user | User | تمثيل للمستخدم المطلوب إزالته |
الإرجاع
Document
— هذا Document
لإنشاء سلسلة.
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
save And Close()
تحفظ Document
الحالية. يؤدي هذا الإجراء إلى إزالة التحديثات المعلّقة وتطبيقها.
يتم استدعاء الطريقة save
تلقائيًا في نهاية تنفيذ النص البرمجي
لكل Document
مفتوح قابل للتعديل.
لا يمكن تعديل Document
مغلق. استخدِم Document
لإعادة فتح
مستند معيّن لتعديله.
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
set Active Tab(tabId)
تُستخدَم لضبط Tab
التي اختارها المستخدم في المستند الحالي على علامة التبويب التي تحمل المعرّف المحدّد.
const doc = DocumentApp.getActiveDocument(); // Sets the user's selected tab by its ID. // TODO(developer): Replace the ID with your own. const tab = doc.setActiveTab('123abc');
المعلمات
الاسم | النوع | الوصف |
---|---|---|
tab | String | رقم تعريف علامة التبويب المطلوب ضبطها على أنّها نشطة. |
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
set Cursor(position)
تُحدِّد مؤشر المستخدِم، مع الأخذ في الاعتبار Position
. لا يمكن للنص البرمجي الوصول إلى مؤشر الماوس الخاص
بالمستخدم الذي يشغّل النص البرمجي إلا إذا كان النص البرمجي مرتبطًا بالمستند.
يؤدي تقديم Position
من Tab
غير نشط إلى تبديل علامة التبويب النشطة للمستخدم.
const doc = DocumentApp.getActiveDocument(); const documentTab = doc.getActiveTab().asDocumentTab(); // Append a paragraph, then place the user's cursor after the first word of the // new paragraph. const paragraph = documentTab.getBody().appendParagraph('My new paragraph.'); const position = documentTab.newPosition(paragraph.getChild(0), 2); doc.setCursor(position);
المعلمات
الاسم | النوع | الوصف |
---|---|---|
position | Position | موقع المؤشر الجديد. |
الإرجاع
Document
— هذا الرمز Document
، لإنشاء سلسلة.
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
set Language(languageCode)
لضبط رمز لغة المستند. هذه هي اللغة المعروضة في ملف
> اللغة في محرِّر المستندات، وقد لا تكون هي اللغة الفعلية التي يتضمّنها المستند. استخدِم get
للحصول على جميع رموز اللغة الصالحة.
المعلمات
الاسم | النوع | الوصف |
---|---|---|
language | String | رمز اللغة |
الإرجاع
Document
— هذا الرمز Document
، لإنشاء سلسلة.
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
set Name(name)
لضبط عنوان المستند
المعلمات
الاسم | النوع | الوصف |
---|---|---|
name | String | عنوان المستند الجديد. |
الإرجاع
Document
: المستند الحالي
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
set Selection(range)
تُستخدَم لضبط اختيار المستخدِم في علامة التبويب "نشط"، مع الأخذ في الاعتبار Range
. لا يمكن للنص البرمجي سوى
الوصول إلى اختيار المستخدم الذي يشغّل النص البرمجي، وذلك فقط إذا كان النص البرمجي مرتبطًا بالمستند.
const doc = DocumentApp.getActiveDocument(); const documentTab = doc.getActiveTab().asDocumentTab(); // Change the user's selection to a range that includes every table in the // document. 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());
المعلمات
الاسم | النوع | الوصف |
---|---|---|
range | Range | النطاق الجديد للعناصر التي سيتم اختيارها. |
الإرجاع
Document
— هذا الرمز Document
، لإنشاء سلسلة.
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents