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

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

الأساسيات

يمكن أن تتفاعل "برمجة التطبيقات" مع "مستندات Google" بطريقتَين واسعتَين: يمكن لأي نص برمجي إنشاء مستند أو تعديله إذا كان مستخدم النص البرمجي لديه الأذونات المناسبة الوثيقة ويمكن أيضًا كتابة bound بمستند، والذي يعطي قدرات خاصة للنص البرمجي لتغيير واجهة المستخدم أو الاستجابة عند تم فتح المستند. لإنشاء نص برمجي مرتبط بحاوية من داخل "مستندات 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 لكل برنامج. (غالبًا ما يُطلق على هذا النوع من العملية اسم merge.)

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

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

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

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