القوائم المُخصَّصة لإضافات المحرر

يمكن أن تؤدي إضافات المحرّرين المنشورة إلى إنشاء عناصر قائمة مخصّصة ضمن قائمة الإضافات في أدوات التعديل التي يستخدمونها. يمكنك إدراج قائمة إضافة باستخدام طريقة Ui.createAddonMenu() وإضافة عناصر إليها باستخدام طريقة Menu.addItem(). يتم إنشاء القوائم عادةً باستخدام طريقة الإضافة onOpen(e).

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

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

تحذير: إذا حاولت اتخاذ إجراءات تتطلب إذنًا عندما يكون وضع التفويض ScriptApp.AuthMode.NONE، سيؤدي ذلك إلى حدوث خطأ. وقد يمنع ذلك عرض قوائم الإضافات.

يوضح المثال التالي كيفية إنشاء قائمة إضافات ديناميكية لأوضاع التفويض المختلفة:

function onOpen(e) {
  var menu = SpreadsheetApp.getUi().createAddonMenu(); // Or DocumentApp or SlidesApp or FormApp.
  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');
    }
    // Record analytics.
    UrlFetchApp.fetch('http://www.example.com/analytics?event=open');
  }
  menu.addToUi();
}