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

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

الأساسيات

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

وفي كلتا الحالتَين، من السهل التفاعل مع مستند "مستندات Google" من خلال خدمة المستندات في Apps Script، كما يوضّح المثال التالي.

function createDoc() {
  var doc = DocumentApp.create('Sample Document');
  var documentTab = doc.getTab('t.0').asDocumentTab();
  var body = documentTab.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 الخاص بالمستخدم، ثم يُسترجع علامة التبويب التي تحمل رقم التعريف t.0 (علامة التبويب الأولى التلقائية)، ويُدرج فقرة تحتوي على النص نفسه الذي يحمله اسم المستند، ويُعدّل تنسيق هذه الفقرة ليكون عنوانًا، ويُلحق جدولاً استنادًا إلى القيم في صفيف ثنائي الأبعاد. يمكن للملفّ الشخصي إجراء هذه التغييرات بسهولة على مستند حالي من خلال استبدال طلب DocumentApp.create() بـ DocumentApp.openById() أو openByUrl(). بالنسبة إلى النصوص البرمجية التي تم إنشاؤها داخل مستند (مرتبطة بالحاويات)، استخدِم DocumentApp.getActiveDocument() وDocument.getActiveTab().

بنية المستند

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

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

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

استبدال النص

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

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

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

أضِف بعض العناصر النائبة.

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

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

function searchAndReplace() {
  var body = DocumentApp.getActiveDocument().getActiveTab().asDocumentTab().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 Script نشر النص البرمجي كأحد الإضافات حتى يتمكّن المستخدمون الآخرون من تثبيته من متجر الإضافات.

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

العوامل التي تؤدي إلى الظهور

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

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