توسيع مستندات 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.

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

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

استبدال النص

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

يمكنك استبدال النص باستخدام طريقة replaceText التي تتوافق مع معظم ميزات التعبيرات العادية في JavaScript. في المثال التالي، تضيف الدالة الأولى نصًا نائبًا إلى المستند، وتستبدل الدالة الثانية هذا النص بخصائص من عنصر 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" من خلال إضافة قوائم مخصّصة ومربّعات حوار وأشرطة جانبية. يُرجى العِلم أنّه لا يمكن للبرنامج النصي التفاعل إلا مع واجهة مستخدم المستند الذي يرتبط به.

لمزيد من المعلومات حول إنشاء واجهات مخصّصة باستخدام HTML وCSS، يُرجى الاطّلاع على دليل خدمة HTML. إذا كنت تخطّط لنشر واجهتك كـ إضافة، اتّبِع دليل الأسلوب لضمان أن يكون مظهرها متوافقًا مع أدوات تحرير المستندات.

إضافات "مستندات Google"

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

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

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

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

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