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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

إنّ نموذج التفويض لإضافات المحرّرين هو أكثر تعقيدًا. نظرًا لأن هذه الإضافات تعمل على الملفات المتوفرة في Google Drive، وهي ملفات يمكن مشاركتها مع الآخرين، يجب إنشاء إضافات المحرِّرين مع وضع أوضاع التفويض المختلفة في الاعتبار. وتوفّر تطبيقات محرّر Google Workspace أيضًا قائمة الإضافات في واجهات المستخدم التي تتم تعبئتها بواسطة الإضافات التي ثبّتها، حتى في حال عدم السماح بهذه الإضافات. ويؤدي ذلك إلى إضافة المزيد من التعقيد إلى نموذج التفويض.

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

إنّ خاصيتين من إضافات المحرِّر تسهّلان مشاركة واستخدامهما على وجه الخصوص:

  • بعد الحصول على إضافة محرر من المتجر، ستظهر لك في قائمة "الإضافات" لكل مستند تفتحه أو تنشئه. يرى المتعاونون في هذه المستندات # هذه الإضافة باستثناء المستندات التي تستخدمها بشكل فعلي.
  • بعد استخدام إضافة محرِّر في مستند، يطّلع المتعاونون عليها أيضًا في قائمة الإضافات، ولكن لهذا المستند فقط (ما لم يكونوا قد ثبَّتوا هذه الإضافة أيضًا).

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

مقارنة بين التطبيقات المثبَّتة والمفعَّلة

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

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

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

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

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

وعلى وجه التحديد، تحدّد حالات التثبيت والمفعّل وضع التفويض الذي يتم تشغيل دالة onOpen(e) فيه. تسجِّل "برمجة التطبيقات" وضع التفويض كخاصية authMode في برمجة تطبيقات مَعلمة الحدث، e. وتتطابق قيمة e.authMode مع ثابت في تعداد "برمجة تطبيقات Google" ScriptApp.AuthMode.

إذا تم تفعيل إضافة المحرِّر في المستند الحالي، سيتم تشغيل onOpen(e) في AuthMode.LIMITED. إذا لم يتم تفعيل الإضافة وتم تثبيتها فقط، سيتم تشغيل onOpen(e) في AuthMode.NONE.

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

NONE LIMITED CUSTOM_FUNCTION FULL
يُحدث في onOpen(e) (إذا ثبّت المستخدم إضافة ولكن لم يفعّلها في المستند) onOpen(e) (جميع الأوقات الأخرى)
onEdit(e) (في "جداول بيانات Google" فقط)
الدوال المخصّصة جميع الأوقات الأخرى، بما في ذلك:
المشغّلات القابلة للتثبيت
onInstall(e)
google.script.run
الوصول إلى بيانات المستخدم اللغة فقط اللغة فقط اللغة فقط نعم
إمكانية الوصول إلى المستند لا نعم نعم — للقراءة فقط نعم
الوصول إلى واجهة المستخدم إضافة أصناف في القائمة إضافة أصناف في القائمة لا نعم
الوصول إلى Properties لا نعم نعم نعم
الوصول إلى Jdbc وUrlFetch لا لا نعم نعم
خدمات أخرى Logger
Utilities
أي خدمات لا يمكنها الوصول إلى بيانات المستخدم أي خدمات لا يمكنها الوصول إلى بيانات المستخدم جميع الخدمات

مراحل النشاط الكاملة

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

جارٍ التثبيت

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

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

فتح

عندما يتم فتح مستند، يحمِّل كل إضافة من ميزات المحرّر التي ثبّتها المستخدم الحالي أو فعّلها أي متعاون في المستند، واستدعى كل وظيفة من وظائف onOpen(e). يعتمد وضع التفويض الذي تستخدمه onOpen(e) على ما إذا كانت الإضافة مثبّتة أو مفعّلة.

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

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

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

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

ركض

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