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

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

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

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

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

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