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

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

الأساسيات

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

وفي كلتا الحالتين، من السهل التفاعل مع أي مستند في محرر مستندات Google من خلال لبرمجة التطبيقات خدمة المستندات، كما في المثال التالي ما يوضحه.

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()

بنية المستند

من منظور برمجة التطبيقات، يتم تنظيم مستند مستندات Google مستند HTML إلى حد كبير — أي أن المستند يتكون من مستند واحد أو أكثر Tab كائنات، يحتوي كل منها على (مثل Paragraph أو Table) التي غالبًا ما تتضمّن غير ذلك عناصر. تبدأ معظم النصوص البرمجية التي تعدِّل مستندًا في محرّر مستندات Google باستدعاء إلى getTab() و asDocumentTab() يليها getBody()، لأن Body عنصرًا أساسيًا تحتوي على جميع العناصر الأخرى في علامة تبويب باستثناء HeaderSection, FooterSection، وأي Footnotes.

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

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

استبدال النص

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

هناك العديد من الطرق لاستبدال النص، ولكن أبسطها هو 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"

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

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

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