يقدم النص البرمجي لتطبيقات Google أكثر من 30 خدمة مضمنة للتفاعل مع بيانات المستخدم وأنظمة Google الأخرى والأنظمة الخارجية. ويتم تقديم هذه الخدمات ككائنات عامة شبيهة بكائن JavaScript العادي Math
. على سبيل المثال، بالطريقة نفسها التي يقدّم بها Math
طُرقًا مثل random()
وثوابت مثل PI
، توفّر
خدمة جداول البيانات في "برمجة تطبيقات Google" طرقًا مثل
openById(id)
،
وفئات (عناصر فرعية)، مثل
Range
واحصائيات مثل
DataValidationCriteria
.
يتم جمع المستندات المرجعية للخدمات التي تتحكم في Google Workspace المنتجات في قسم "Google Workspace الخدمات" ضمن العنوان "المرجع" في الشريط الجانبي لهذا الموقع الإلكتروني. يتم جمع خدمات الأداة المساعدة (لأشياء مثل إنشاء واجهات المستخدم، أو تحليل XML، أو كتابة بيانات السجل) في قسم "خدمات النص البرمجي".
ميزات JavaScript الحديثة
تتوافق "برمجة التطبيقات" مع وقتَي تشغيل JavaScript: وقت تشغيل V8 الحديث وآخر أقدم بدعم من مترجم JavaScript بلغة Rhino من Mozilla.
يتوافق وقت تشغيل V8 مع بنية ECMAScript وميزاتها الحديثة. يعتمد وقت تشغيل Rhino على معيار JavaScript 1.6 القديم، بالإضافة إلى بعض الميزات من 1.7 و1.8. يمكنك اختيار وقت التشغيل بحرية لاستخدامه مع النص البرمجي، إلا أننا ننصح بشدة باستخدام وقت تشغيل V8.
يتوافق كل وقت تشغيل مع فئات JavaScript وكائنات متاحة لنصك البرمجي بالإضافة إلى خدمات Google المتقدمة والمُدمجة. يمكن أن تستخدم النصوص البرمجية كائنات شائعة مثل Array
، وDate
، وRegExp
، وما إلى ذلك، بالإضافة إلى الكائنات العامة Math
وObject
.
استخدام الإكمال التلقائي
يوفّر محرّر النص البرمجي ميزة "المساعدة في المحتوى"، والتي يُطلق عليها عادةً اسم "الإكمال التلقائي"، والتي تكشف عن الكائنات العامة وكذلك الطرق والأعداد التي تعدّ صالحة في السياق الحالي للنص البرمجي. تظهر اقتراحات الإكمال التلقائي تلقائيًا كلما كتبت نقطة بعد كائن عام أو تعداد أو استدعاء لأسلوب عرض فئة برمجة التطبيقات. مثلاً:
- إذا كتبت الاسم الكامل لكائن عام أو حددت واحدًا من الإكمال التلقائي،
ثم اكتب
.
(نقطة)، فسترى جميع الطرق والإحصاءات لتلك الفئة. - إذا كتبت بضعة أحرف، فسترى جميع الاقتراحات الصالحة التي تبدأ بتلك الأحرف.
فهم العناصر العامة
وتوفِّر كل خدمة كائنًا عموميًا واحدًا على الأقل (المستوى الأعلى)، على سبيل المثال، يتم الوصول إلى خدمة Gmail من الكائن GmailApp
فقط. وتوفّر بعض الخدمات عناصر متعدّدة عمومية، على سبيل المثال، تتضمّن الخدمة الأساسية أربعة عناصر عمومية:
Browser
وLogger
وMimeType
وSession
.
طرق الاتصال
وتتضمن الكائنات العامة تقريبًا جميع الخدمات المتقدمة المضمَّنة أو تقريبًا الطرق التي تعرض البيانات أو فئة برمجة التطبيقات. تُجري النصوص البرمجية عمليات استدعاء الطريقة بالتنسيق التالي:
GlobalObjectName.methodName(argument1, argument2, ..., argumentN);
على سبيل المثال، يمكن للنص البرمجي إرسال رسالة إلكترونية من خلال استدعاء طريقة sendEmail(recipient, subject, body)
لخدمة Gmail على النحو التالي:
GmailApp.sendEmail('claire@example.com', 'Subject line', 'This is the body.');
إذا كانت إحدى الطرق تعرض فئة أخرى من "برمجة تطبيقات Google"، يمكنك ربط استدعاءات الطريقة في سطر واحد. (يتم عرض أنواع الإرجاع في كل من الإكمال التلقائي والوثائق
المرجعية للطريقة.) على سبيل المثال، تعرض الطريقة
DocumentApp.create()
رمز Document
، وبالتالي
يتساوى قسما الرمز التاليان:
var doc = DocumentApp.create('New document');
var body = doc.getBody();
body.appendParagraph('New paragraph.');
// Same result as above.
DocumentApp.create('New document').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);