توسيع مستندات 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". لنفترض أن لديك جدول بيانات مليء بمعلومات العميل وتريد إنشاء مستند 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"، يمكنك الاطّلاع على البدء السريع لإنشاء إضافات "مستندات Google".

الكائن Triggers

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

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