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

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

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

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

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

غالبًا ما يتم استخدام برمجة التطبيقات لاستبدال النص في "مستندات 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 ورغبتك في مشاركته مع جميع المستخدمين، تتيح لك "برمجة التطبيقات" نشر نصك البرمجي كإضافة حتى يتمكّن المستخدمون الآخرون من تثبيته من متجر الإضافات.

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

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

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

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