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

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