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

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

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

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

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

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

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

التطبيقات المثبّتة مقابل التطبيقات المثبّتة

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

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

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

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

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

تحدّد الولايات المثبّتة والمفعّلة تحديدًا وضع التفويض الذي تعمل فيه دالة onOpen(e). تمرر برمجة التطبيقات وضع التفويض كسمة authMode في معلمة حدث "برمجة تطبيقات Google"، e؛ وتقابل قيمة e.authMode قيمة ثابتة في تعداد برمجة التطبيقات ScriptApp.AuthMode.

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

ينطبق مفهوم أوضاع التفويض على جميع عمليات تنفيذ "برمجة التطبيقات"، مثل التشغيل من محرِّر النصوص البرمجية، أو من عنصر قائمة، أو من استدعاء برمجة تطبيقات 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();
}

ومع ذلك، إذا كنت تريد إضافة عناصر قائمة ديناميكية استنادًا إلى خصائص برمجة التطبيقات المخزنة، أو قراءة محتويات المستند الحالي أو إجراء مهام متقدمة أخرى، فستحتاج إلى اكتشاف وضع التفويض والتعامل معه بشكل مناسب. يوضّح هذا النموذج الشكل المحتمل لوظيفة 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();
}

ركض

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