توسيع نطاق مستندات Google

تتيح لك لغة برمجة Google Apps إنشاء مستندات Google وتعديلها آليًا، بالإضافة إلى تخصيص واجهة المستخدم بقوائم ومربعات حوار وأشرطة جانبية جديدة.

الأساسيات

يمكن لبرمجة التطبيقات التفاعل مع "مستندات Google" بطريقتين واسعتين: يمكن لأي نص برمجي إنشاء مستند أو تعديله إذا كان مستخدم النص البرمجي يملك الأذونات المناسبة للمستند، ويمكن أيضًا ربط نص برمجي بمستند، ما يمنح النص البرمجي إمكانيات خاصة لتغيير واجهة المستخدم أو الاستجابة عند فتح المستند. لإنشاء نص برمجي مرتبط بحاوية من داخل "مستندات Google"، انقر على الإضافات > برمجة التطبيقات.

في كلتا الحالتين، من السهل التفاعل مع مستند Google من خلال خدمة المستندات في "برمجة التطبيقات"، كما يبيِّن المثال التالي.

function createDoc() {
  var doc = DocumentApp.create('Sample Document');
  var body = doc.getBody();
  var rowsData = [['Plants', 'Animals'], ['Ficus', 'Goat'], ['Basil', 'Cat'], ['Moss', 'Frog']];
  body.insertParagraph(0, doc.getName())
      .setHeading(DocumentApp.ParagraphHeading.HEADING1);
  table = body.appendTable(rowsData);
  table.getRow(0).editAsText().setBold(true);
}

يعمل النص البرمجي أعلاه على إنشاء مستند جديد في Google Drive للمستخدم، ثم يدرج فقرة تحتوي على نفس نص اسم المستند، والأنماط التي تكون فيها الفقرة عنوانًا، ثم إلحاق جدول بناءً على القيم في مصفوفة ثنائية الأبعاد. يمكن للنص البرمجي إجراء هذه التغييرات على مستند حالي بنفس السهولة عن طريق استبدال الطلب إلى DocumentApp.create() بـ DocumentApp.openById() أو openByUrl(). بالنسبة إلى النصوص البرمجية التي تم إنشاؤها داخل مستند (محاط بالحاوية)، استخدِم DocumentApp.getActiveDocument().

بنية المستند

من منظور "برمجة التطبيقات"، تكون بنية مستند Google أشبه إلى حد كبير بمستند HTML، أي أنّ مستند Google يتكوّن من عناصر (مثل Paragraph أو Table) تحتوي غالبًا على عناصر أخرى. تبدأ معظم النصوص البرمجية التي تعدِّل "مستند Google" باستدعاء getBody()، لأنّ Body هو عنصر رئيسي يحتوي على جميع العناصر الأخرى باستثناء HeaderSection وFooterSection وأيّ Footnotes.

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

يمكن إدراج العناصر المعروضة بالخط الغامق؛ ولا يمكن معالجة العناصر غير الغامقة إلا في مكانها.

جارٍ استبدال النص

غالبًا ما يتم استخدام لغة "برمجة تطبيقات Google" لاستبدال النص في "مستندات Google". لنفترض أن لديك جدول بيانات مليء بمعلومات العميل وتريد إنشاء مستند مخصص لمستندات Google لكل عميل. (غالبًا ما يُطلق على هذا النوع من العمليات اسم دمج البريد).

هناك العديد من الطرق لاستبدال النص، ولكن أبسطها هو طريقة replaceText() الموضّحة في المثال أدناه. يتوافق replaceText مع معظم ميزات التعبير العادي في JavaScript. تضيف الدالة الأولى أدناه عدة أسطر من نص العنصر النائب إلى مستندات Google؛ في العالم الحقيقي، من المرجح أن تكتب العناصر النائبة في المستند بنفسك. وتستبدل الدالة الثانية العناصر النائبة بخصائص محدّدة في كائن client.

تجدر الإشارة إلى أنّ كلتا الدالتَين تستخدمان الطريقة getActiveDocument() التي لا تنطبق إلا على النصوص البرمجية التي تم إنشاؤها داخل مستند Google. وفي نص برمجي مستقل، يمكنك استخدام DocumentApp.create() أو openById() أو openByUrl() بدلاً من ذلك.

إضافة بعض العناصر النائبة

function createPlaceholders() {
  var body = DocumentApp.getActiveDocument().getBody();
  body.appendParagraph('{name}');
  body.appendParagraph('{address}');
  body.appendParagraph('{city} {state} {zip}');
}

استبدال العناصر النائبة

function searchAndReplace() {
  var body = DocumentApp.getActiveDocument()
      .getBody();
  var client = {
    name: 'Joe Script-Guru',
    address: '100 Script Rd',
    city: 'Scriptville',
    state: 'GA',
    zip: 94043
  };

  body.replaceText('{name}', client.name);
  body.replaceText('{address}', client.address);
  body.replaceText('{city}', client.city);
  body.replaceText('{state}', client.state);
  body.replaceText('{zip}', client.zip);
}

قوائم مخصّصة وواجهات مستخدم

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

تعرّف على طريقة إضافة قوائم مخصّصة ومربّعات حوار إلى "مستندات Google". لمعرفة المزيد من المعلومات عن إنشاء واجهات مخصّصة لمربّع حوار أو شريط جانبي، يمكنك الاطّلاع على دليل استخدام خدمة HTML. إذا كنت تنوي نشر واجهتك المخصّصة كجزء من إضافة، يمكنك اتّباع دليل الأنماط للحفاظ على اتساق نمط "أداة تحرير مستندات Google" وتنسيقها.

إضافات "مستندات Google"

يتم تشغيل الإضافات داخل مستندات Google ويمكن تثبيتها من متجر إضافات مستندات Google. إذا كنت قد طوّرت نصًا برمجيًا لـ "مستندات Google" وتريد مشاركته مع الجميع، تتيح لك "برمجة التطبيقات" publish النص البرمجي كإضافة حتى يتمكّن المستخدمون الآخرون من تثبيته من متجر الإضافات.

لمعرفة كيفية إنشاء إضافة لمستندات Google، يُرجى الاطّلاع على البدء السريع لإنشاء إضافات "مستندات Google".

أسباب طلب المساعدة

يمكن للنصوص البرمجية المرتبطة بمستند Google استخدام عامل تشغيل بسيط للاستجابة إلى حدث onOpen للمستند، والذي يحدث عندما يفتحه مستخدم لديه الإذن بتعديل المستند في "مستندات Google".

لإعداد المشغِّل، ما عليك سوى كتابة دالة تسمى onOpen(). للاطّلاع على مثال على هذا المشغِّل، راجِع القوائم المخصّصة في Google Workspace. على الرغم من أنّ المشغِّل البسيط مفيد لإضافة القوائم، إلا أنه لا يمكنه استخدام أي من خدمات "برمجة التطبيقات" التي تتطلب إذنًا.