توسيع نطاق مستندات 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 Docs بطلب إلى getTab() و asDocumentTab() متبوعًا بـ getBody()، لأنّ Body هو عنصر أساسي يحتوي على جميع العناصر الأخرى في علامة تبويب باستثناء HeaderSection و FooterSection وأي Footnotes.

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

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

استبدال النص

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

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

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

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

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