تفويض إضافة المحرّر

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

نموذج التفويض إضافات المحرّر هي أكثر تعقيدًا لعدة أسباب منها:

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

• تعمل هذه الإضافات على الملفات في Google Drive الذي يمكن مشاركته مع المتعاونين المتعاونون غير المتعاونين تثبيت إضافة المحرّر للاطّلاع عليها في المستندات حيث استخدم منشئ الملف هذا الملف.

• تُشغِّل إضافات المحرر onOpen() تلقائيًا الدوال عند فتح مستند.

لحماية بيانات المستخدمين، يتم تطبيق أوضاع التفويض التي تجعل بعض الخدمات غير متاح لـ onOpen(). يمكن أن يساعدك هذا الدليل في فهم ماهية التعليمات البرمجية القيام به ومتى.

نموذج التفويض

يعتمد وضع التفويض لإضافة محرِّر على حالتها، والذي يعتمد على من يستخدمه: المستخدم الذي ثبَّت الإضافة أو متعاون.

حالات إضافات المحرّر

إضافات "محرّر إعلانات Google" في قائمة الإضافات: المثبتة أو المُمَكّنة أو كليهما.

• تثبيت إضافة على جهاز معيّن المستخدم بعد أن يحصل عليه أو مشرفه من خلال Google Workspace Marketplace ومنحه الإذن بالوصول إلى بياناته على Google
• يتم تفعيل أي إضافة في مستند أو نموذج أو عرض تقديمي أو جدول بيانات عندما يستخدمه أي شخص هناك.
• عندما يتعاون المستخدمون في ملف ويستخدم أحدهم الإضافية، فإنه يتم تثبيتها للمستخدم الواحد مفعَّل للملف.

يلخّص الجدول التالي أوجه الاختلاف بين عمليات التثبيت والتفعيل. لاحظ أنه عند اختبار نص برمجي كإضافة يمكنك إجراء الاختبار في إحدى هاتين الحالتين أو كلتيهما.

أوضاع التفويض

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

إذا كانت إحدى إضافات "محرّر إعلانات Google" مفعّلة في الملف، أو عرض تقديمي أو جدول بيانات، يتم تشغيل onOpen() في AuthMode.LIMITED إذا لم يتم تفعيل الإضافة مثبَّت فقط، ويتم تشغيل onOpen() في AuthMode.NONE.

في AuthMode.NONE، لا يمكن تشغيل إضافة معينة الخدمات حتى يتفاعل المستخدم مع الإضافة من خلال النقر على الدوال المخصصة أو تشغيلها. إذا كان تحاول الإضافة استخدام هذه الخدمات في onOpen()، onInstall()، أو على النطاق العام، تعذّر إكمال الأذونات وطلبات أخرى، مثل ملء القوائم، توقف. المساعدة هي الخيار الوحيد المتاح.

لإجراء مكالمات خدمة محظورة، عليك استخدام تفويض AuthMode.FULL. الحالي. وظائف تفاعل المستخدم، مثل النقر فوق أحد خيارات القائمة، لا يتم تشغيلها إلا في هذا الوضع. بعد تشغيل الرمز في وضع AuthMode.FULL، الإضافية استخدام جميع النطاقات التي صرح بها المستخدم.

تجتاز "برمجة التطبيقات" وضع التفويض باعتباره السمة authMode في "برمجة تطبيقات Google" مَعلمة حدث، e والقيمة e.authMode يتوافق مع ثابت في برمجة التطبيقات تعداد ScriptApp.AuthMode

تنطبق أوضاع التفويض على جميع طرق تنفيذ برمجة التطبيقات، بما في ذلك التشغيل من خلال أداة تعديل النصوص البرمجية أو من عنصر في القائمة أو من خلال "برمجة تطبيقات Google" مكالمة google.script.run. ومع ذلك، لا يمكن فحص السمة e.authMode إلا إذا تم تشغيل النص البرمجي على النحو التالي: لعامل تشغيل مثل onOpen() أو onEdit() أو onInstall(). الدوال المخصّصة في جداول بيانات Google يستخدمون وضع التفويض الخاص بها، AuthMode.CUSTOM_FUNCTION، والذي يشبه LIMITED ولكن له قيود مختلفة قليلاً. للجميع في حالات أخرى، يتم تشغيل النصوص البرمجية في AuthMode.FULL، كما هو موضح في ما يلي المؤقت.

دورة حياة تفويض إضافة "المحرِّر"

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

تم تثبيت إضافة "المحرِّر".

عند تثبيت إحدى إضافات المحرر من المتجر، يتم تشغيل الدالة onInstall() في AuthMode.FULL. في وضع التفويض هذا، تشغيل سلسلة إجراءات إعداد معقدة. يجب عليك أيضًا استخدام onInstall() لإنشاء عناصر القائمة، حيث إن المستند أو النموذج أو العرض التقديمي أو جدول البيانات مفتوح من قبل ولم يتم تشغيل دالة onOpen(). يوضح المثال التالي كيفية استدعاء الدالة onOpen() من الدالة onInstall():

function onInstall(e) {
  onOpen(e);
  // Perform additional setup as needed.
}

تم فتح إضافة "المحرِّر".

عندما يتم فتح مستند أو نموذج أو عرض تقديمي أو جدول بيانات، يتم تحميل كل إضافة المحرّر التي ثبّتها المستخدم الحالي أو التي فعّلها أي متعاون في الملف، ثم يستدعي لكل دالة من دوال onOpen(). وضع التفويض الذي onOpen() يعمل فيها على ما إذا كانت الوظيفة الإضافية مثبتة أو مُفعَّلة.

إذا أنشأت إحدى الإضافات قائمة أساسية فقط، فإن الوضع لا يهم. يعرض النموذج التالي دالة onOpen() أساسية:

function onOpen(e) {
  SpreadsheetApp.getUi().createAddonMenu() // Or DocumentApp.
      .addItem('Insert chart', 'insertChart')
      .addItem('Update charts', 'updateCharts')
      .addToUi();
}

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

يعرض النموذج التالي دالة onOpen() متقدّمة تغيّر إجراء مستند إلى وضع التفويض:

function onOpen(e) {
  var menu = SpreadsheetApp.getUi().createAddonMenu(); // Or DocumentApp.
  if (e && e.authMode == ScriptApp.AuthMode.NONE) {
    // Add a normal menu item (works in all authorization modes).
    menu.addItem('Start workflow', 'startWorkflow');
  } else {
    // Add a menu item based on properties (doesn't work in AuthMode.NONE).
    var properties = PropertiesService.getDocumentProperties();
    var workflowStarted = properties.getProperty('workflowStarted');
    if (workflowStarted) {
      menu.addItem('Check workflow status', 'checkWorkflow');
    } else {
      menu.addItem('Start workflow', 'startWorkflow');
    }
  }
  menu.addToUi();
}

تجدر الإشارة إلى أنّه لا يمكن للإضافات فتح الأشرطة الجانبية أو مربّعات الحوار أثناء التنفيذ في AuthMode.LIMITED يمكنك استخدام أصناف في القائمة لفتح الأشرطة الجانبية ومربّعات الحوار منذ تشغيلها في AuthMode.FULL

يشغِّل مستخدم إضافة "المحرِّر"

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

تحديد المشاكل وحلّها في ما يتعلق بعدم عرض قوائم الإضافات

قد لا يتم عرض قائمة الإضافات إذا كان الرمز لا يدير أوضاع التفويض بشكلٍ صحيح. على سبيل المثال:

• تحاول إحدى الإضافات تشغيل "برمجة تطبيقات Google" غير مدعومة في وضع التفويض الحالي.

• تحاول إحدى الإضافات تشغيل استدعاء خدمة قبل مستخدم يتفاعل معه.

لإزالة أو إعادة ترتيب استدعاء خدمة يتسبب في حدوث أخطاء في الأذونات في AuthMode.NONE، جرِّب الإجراءات التالية:

1. افتح مشروع "برمجة تطبيقات Google" للإضافة وحدِّد موقعها الدالة onOpen().
2. البحث في الدالة onOpen() عن الإشارات إلى "برمجة تطبيقات Google" الخدمات أو الكائنات المرتبطة بها، مثل PropertiesService أو SpreadsheetApp أو GmailApp
3. إذا تم استخدام خدمة لأي شيء بخلاف إنشاء عناصر واجهة المستخدم، إزالته أو التفافه في كتلة تعليق. يمكنك ترك هذه الطرق فقط: .getUi() و.createMenu() و.addItem() و و.addToUi(). يمكنك أيضًا العثور على أي خدمة خارج الدالة وإزالتها.
4. تحديد الدوال التي يمكن أن تحتوي على سطور الرمز التي تم التعليق عليها أو إزالتها في الخطوة السابقة، لا سيما تلك التي تستخدم المعلومات التي تقدّمها وننقل طلبات الخدمة إلى الدوال التي تحتاج إليها. إعادة الترتيب أو إعادة الكتابة قاعدة التعليمات البرمجية لاستيعاب التغييرات التي تم إجراؤها في الخطوات السابقة.

5. احفظ الرمز وأنشئ عملية نشر تجريبية.

   عند إنشاء عملية نشر تجريبية، تأكَّد من أنّ الحقل الإعداد مثبّت للمستخدم الحالي وأنّ النص الظاهر أسفل مربع "الإعداد" ينص على الاختبار في AuthMode.None

6. ابدأ عملية النشر التجريبية وافتح قائمة الإضافات.

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

مواضيع ذات صلة

• تطبيقات الويب
• أنواع الإضافات
• اختبار إضافة "محرّر"