خدمات Google المُدمَجة

توفّر خدمة Google Apps Script أكثر من 30 خدمة مضمّنة للتفاعل مع بيانات المستخدمين وأنظمة Google الأخرى والأنظمة الخارجية. يتم توفير هذه الخدمات كعناصر عامة مشابهة لعنصر Math JavaScript العادي. على سبيل المثال، كما يوفّر Math طرقًا مثل random() وثوابت مثل PI، يوفّر خدمة جداول بيانات في Apps Script طرقًا مثل openById(id) وفئات (عناصر فرعية) مثل Range وقيم تعدادية مثل DataValidationCriteria.

يتم جمع المستندات المرجعية للخدمات التي تتحكّم في منتجات Google Workspace في قسم "خدمات Google Workspace" ضمن العنوان "مرجع" في الشريط الجانبي لهذا الموقع الإلكتروني. يتم جمع الخدمات المساعدة (مثل إنشاء واجهات المستخدمين أو تحليل XML أو كتابة بيانات السجلّ) في قسم "خدمات البرامج النصية".

ميزات JavaScript الحديثة

تتوافق Apps Script مع وقتَي تشغيل JavaScript، وهما وقت التشغيل الحديث V8 ووقت التشغيل القديم الذي يعتمد على مفسّر Rhino JavaScript من Mozilla.

يتوافق وقت التشغيل V8 مع بنية وميزات ECMAScript الحديثة. يستند وقت تشغيل Rhino إلى معيار JavaScript 1.6 الأقدم، بالإضافة إلى بعض الميزات من 1.7 و 1.8. يمكنك اختيار وقت التشغيل الذي تريده لاستخدامه مع البرنامج النصي، ولكن ننصحك بشدة باستخدام وقت تشغيل V8.

يتيح كل وقت تشغيل فئات JavaScript وعناصر متاحة للبرنامج النصي بالإضافة إلى خدمات Google المضمَّنة والمتقدّمة. يمكن أن تستخدم النصوص البرمجية كائنات شائعة، مثل Array وDate وRegExp ووغيرها، بالإضافة إلى الكائنَين العامَين Math وObject.

استخدام ميزة "الإكمال التلقائي"

يوفّر محرِّر النصوص البرمجية ميزة "مساعدة المحتوى"، والتي تُعرف باسم "الإكمال التلقائي"، وتكشف عن العناصر العامة بالإضافة إلى الطرق والقيم الثابتة الصالحة في السياق الحالي للنص البرمجي. تظهر اقتراحات الإكمال التلقائي تلقائيًا عندما تكتب نقطة بعد كائن عام أو تعداد أو استدعاء طريقة تعرض فئة Apps Script. على سبيل المثال:

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

التعرّف على العناصر العامة

تقدّم كل خدمة عنصرًا واحدًا على الأقل على مستوى العالم (المستوى الأعلى)؛ على سبيل المثال، لا يمكن الوصول إلى خدمة Gmail إلا من خلال العنصر GmailApp. تقدّم بعض الخدمات عدة عناصر عامة، مثلاً، تتضمّن الخدمة الأساسية أربعة عناصر عامة: Browser وLogger وMimeType وSession.

طُرق الاتصال

تتضمّن العناصر العامة في جميع الخدمات المتقدّمة أو المضمّنة تقريبًا طرقًا تعرض بيانات أو فئة من فئات Apps Script. تجري النصوص البرمجية عمليات استدعاء الطرق بهذا التنسيق:

GlobalObjectName.methodName(argument1, argument2, ..., argumentN);

على سبيل المثال، يمكن لبرنامج نصي إرسال رسالة إلكترونية من خلال استدعاء طريقة sendEmail(recipient, subject, body) الخاصة بخدمة Gmail على النحو التالي:

GmailApp.sendEmail('claire@example.com', 'Subject line', 'This is the body.');

إذا عرضت إحدى الطرق فئة أخرى من فئات "برمجة التطبيقات"، يمكنك ربط استدعاءات الطرق في سطر واحد. (يتم عرض أنواع الإرجاع في كلّ من الإكمال التلقائي وفي مستندات مرجع الطريقة). على سبيل المثال، تعرض الطريقة DocumentApp.create() القيمة Document، وبالتالي، فإنّ القسمَين التاليَين من الرمز البرمجي متكافئان:

var doc = DocumentApp.create('New document');
var body = doc.getTab('t.0').asDocumentTab().getBody();
body.appendParagraph('New paragraph.');

// Same result as above.
DocumentApp.create('New document').getTab('t.0').asDocumentTab().getBody()
    .appendParagraph('New paragraph.');

الوصول إلى الصفوف الثانوية

تتضمّن كل خدمة فئة واحدة أو أكثر من الفئات الثانوية التي لا يمكن الوصول إليها من المستوى الأعلى كما يمكن الوصول إلى عنصر عام. لا يمكنك استخدام الكلمة الأساسية new لإنشاء هذه الفئات، كما يمكنك مع فئات JavaScript العادية مثل Date؛ يمكنك فقط الوصول إلى فئة فرعية من خلال استدعاء طريقة تعرضها. إذا لم تكن متأكدًا من كيفية الوصول إلى فئة معيّنة، انتقِل إلى صفحة الجذر الخاصة بالمستندات المرجعية للخدمة وابحث عن طريقة تعرض الفئة التي تريدها.

التعامل مع الواجهات

تتضمّن بعض الخدمات فئات خاصة تحمل التصنيف "واجهات" في المستندات المرجعية. هذه فئات عامة تُستخدَم كأنواع إرجاع للطُرق التي لا يمكنها تحديد النوع الدقيق مسبقًا، على سبيل المثال، تعرض طريقة خدمة المستندات Body.getChild(childIndex) كائن Element عام. Element هي واجهة تمثّل فئة أخرى، ربما تكون Paragraph أو Table. ونادرًا ما تكون عناصر الواجهة مفيدة بمفردها، بل تحتاج عادةً إلى استدعاء طريقة مثل Element.asParagraph() لتحويل العنصر مرة أخرى إلى فئة دقيقة.

العمل باستخدام تعدادات

تتضمّن معظم الخدمات بعض القيم الثابتة (أنواع تعدادية) للقيم المسماة. على سبيل المثال، تستخدم خدمة Drive القيمتين Access و Permission لتحديد المستخدمين الذين يمكنهم الوصول إلى ملف أو مجلد. في جميع الحالات تقريبًا، يمكنك الوصول إلى هذه القيم الثابتة من العنصر العام. على سبيل المثال، تبدو الدعوة إلى الطريقة Folder.setSharing(accessType, permissionType) على النحو التالي:

// Creates a folder that anyone on the Internet can read from and write to. (Domain administrators can
// prohibit this setting for Google Workspace users.)
var folder = DriveApp.createFolder('Shared Folder');
folder.setSharing(DriveApp.Access.ANYONE, DriveApp.Permission.EDIT);