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

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

الأساسيات

يستطيع النص البرمجي لـ Apps التفاعل مع محرر مستندات 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 مخصصة لكل عميل. (يُسمى هذا النوع من العمليات غالبًا دمج البريد).

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

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

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

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

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