Class Ui

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

// Display "Hello, world" in a dialog box with an "OK" button. The user can also
// close the dialog by clicking the close button in its title bar.
SpreadsheetApp.getUi().alert('Hello, world');

المعلمات

الإرجاع

Button: الزر الذي نقر عليه المستخدم

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

// Display a dialog box with a message and "Yes" and "No" buttons. The user can
// also close the dialog by clicking the close button in its title bar.
const ui = SpreadsheetApp.getUi();
const response = ui.alert(
    'Are you sure you want to continue?',
    ui.ButtonSet.YES_NO,
);

// Process the user's response.
if (response === ui.Button.YES) {
  Logger.log('The user clicked "Yes."');
} else {
  Logger.log(
      'The user clicked "No" or the close button in the dialog\'s title bar.',
  );
}

المعلمات

الإرجاع

Button: الزر الذي نقر عليه المستخدم

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

// Display a dialog box with a title, message, and "Yes" and "No" buttons. The
// user can also close the dialog by clicking the close button in its title bar.
const ui = SpreadsheetApp.getUi();
const response = ui.alert(
    'Confirm',
    'Are you sure you want to continue?',
    ui.ButtonSet.YES_NO,
);

// Process the user's response.
if (response === ui.Button.YES) {
  Logger.log('The user clicked "Yes."');
} else {
  Logger.log(
      'The user clicked "No" or the close button in the dialog\'s title bar.',
  );
}

المعلمات

الإرجاع

Button: الزر الذي نقر عليه المستخدم

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

// Add an item to the Add-on menu, under a sub-menu whose name is set
// automatically.
function onOpen(e) {
  SpreadsheetApp.getUi()
      .createAddonMenu()
      .addItem('Show', 'showSidebar')
      .addToUi();
}

الإرجاع

Menu - أداة إنشاء القوائم الجديدة

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

// Add a custom menu to the active document, including a separator and a
// sub-menu.
function onOpen(e) {
  SpreadsheetApp.getUi()
      .createMenu('My Menu')
      .addItem('My menu item', 'myFunction')
      .addSeparator()
      .addSubMenu(
          SpreadsheetApp.getUi()
              .createMenu('My sub-menu')
              .addItem('One sub-menu item', 'mySecondFunction')
              .addItem('Another sub-menu item', 'myThirdFunction'),
          )
      .addToUi();
}

المعلمات

الإرجاع

Menu - أداة إنشاء القوائم الجديدة

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

// Display a dialog box with a message, input field, and an "OK" button. The
// user can also close the dialog by clicking the close button in its title bar.
const ui = SpreadsheetApp.getUi();
const response = ui.prompt('Enter your name:');

// Process the user's response.
if (response.getSelectedButton() === ui.Button.OK) {
  Logger.log('The user\'s name is %s.', response.getResponseText());
} else {
  Logger.log('The user clicked the close button in the dialog\'s title bar.');
}

المعلمات

الإرجاع

PromptResponse - تمثيل لردّ المستخدم

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

// Display a dialog box with a message, input field, and "Yes" and "No" buttons.
// The user can also close the dialog by clicking the close button in its title
// bar.
const ui = SpreadsheetApp.getUi();
const response = ui.prompt('May I know your name?', ui.ButtonSet.YES_NO);

// Process the user's response.
if (response.getSelectedButton() === ui.Button.YES) {
  Logger.log('The user\'s name is %s.', response.getResponseText());
} else if (response.getSelectedButton() === ui.Button.NO) {
  Logger.log('The user didn\'t want to provide a name.');
} else {
  Logger.log('The user clicked the close button in the dialog\'s title bar.');
}

المعلمات

الإرجاع

PromptResponse - تمثيل لردّ المستخدم

يفتح مربّع حوار إدخال في محرِّر المستخدم يتضمّن العنوان والرسالة ومجموعة buttons. تعمل هذه الطريقة على تعليق النص البرمجي من جهة الخادم عندما يكون مربّع الحوار مفتوحًا. تتم معالجة النص البرمجي مجددًا بعد أن يغلق المستخدم مربّع الحوار، ولكن لا تستمر عمليات Jdbc الربط وLockService القفل أثناء التعليق. لمزيد من المعلومات، اطّلِع على دليل مربّعات الحوار والأشرطة الجانبية.

// Display a dialog box with a title, message, input field, and "Yes" and "No"
// buttons. The user can also close the dialog by clicking the close button in
// its title bar.
const ui = SpreadsheetApp.getUi();
const response = ui.prompt(
    'Getting to know you',
    'May I know your name?',
    ui.ButtonSet.YES_NO,
);

// Process the user's response.
if (response.getSelectedButton() === ui.Button.YES) {
  Logger.log('The user\'s name is %s.', response.getResponseText());
} else if (response.getSelectedButton() === ui.Button.NO) {
  Logger.log('The user didn\'t want to provide a name.');
} else {
  Logger.log('The user clicked the close button in the dialog\'s title bar.');
}

المعلمات

الإرجاع

PromptResponse - تمثيل لردّ المستخدم

يفتح مربّع حوار مشروطًا في محرِّر المستخدم يتضمّن محتوى مخصّصًا من جهة العميل. لا يؤدي استخدام هذه الطريقة إلى تعليق النص البرمجي من جهة الخادم عندما يكون مربّع الحوار مفتوحًا. للتواصل مع النص البرمجي من جهة الخادم، يجب أن يُجري المكوّن من جهة العميل عمليات استدعاء غير متزامنة باستخدام واجهة برمجة التطبيقات google.script لخدمة HtmlService. لإغلاق مربّع الحوار برمجيًا، استخدِم google.script.host.close() من جهة العميل في تطبيق HtmlService على الويب. لمزيد من المعلومات، اطّلِع على دليل مربّعات الحوار والادراجات الجانبية.

تمنع مربّعات الحوار المشروطة المستخدم من التفاعل مع أي عنصر آخر غير مربّع الحوار. وبالمقابل، تتيح مربّعات الحوار التي لا تتضمّن وضعًا وأشرطة الصفحات الجانبية للمستخدم التفاعل مع المحرِّر. في جميع الحالات تقريبًا، يُعدّ مربّع الحوار المشروط أو الشريط الجانبي خيارًا أفضل من مربّع الحوار بدون وضع.

// Display a modal dialog box with custom HtmlService content.
const htmlOutput = HtmlService
                       .createHtmlOutput(
                           '<p>A change of speed, a change of style...</p>',
                           )
                       .setWidth(250)
                       .setHeight(300);
SpreadsheetApp.getUi().showModalDialog(htmlOutput, 'My add-on');

المعلمات

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

• https://www.googleapis.com/auth/script.container.ui

يفتح مربّع حوار بدون وضع في محرِّر المستخدم يحتوي على محتوى مخصّص من جهة العميل. لا تعمل هذه الطريقة على تعليق النص البرمجي من جهة الخادم عندما يكون مربّع الحوار مفتوحًا. للتواصل مع النص البرمجي من جهة الخادم، يجب أن يُجري المكوّن من جهة العميل عمليات استدعاء غير متزامنة باستخدام واجهة برمجة التطبيقات google.script لخدمة HtmlService. لإغلاق مربّع الحوار برمجيًا، استخدِم google.script.host.close() من جهة العميل في تطبيق HtmlService على الويب. لمزيد من المعلومات، اطّلِع على دليل مربّعات الحوار والادراجات الجانبية.

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

// Display a modeless dialog box with custom HtmlService content.
const htmlOutput = HtmlService
                       .createHtmlOutput(
                           '<p>A change of speed, a change of style...</p>',
                           )
                       .setWidth(250)
                       .setHeight(300);
SpreadsheetApp.getUi().showModelessDialog(htmlOutput, 'My add-on');

المعلمات

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

• https://www.googleapis.com/auth/script.container.ui

يؤدي هذا الإجراء إلى فتح شريط جانبي في محرِّر المستخدم يتضمّن محتوى مخصّصًا من جهة العميل. لا يؤدي استخدام هذه الطريقة إلى تعليق النص البرمجي من جهة الخادم عندما يكون الشريط الجانبي مفتوحًا. للتواصل مع النص البرمجي من جهة الخادم، يجب أن يُجري المكوّن من جهة العميل عمليات استدعاء غير متزامنة باستخدام واجهة برمجة التطبيقات google.script لخدمة HtmlService. لإغلاق الشريط الجانبي برمجيًا، استخدِم google.script.host.close() من جهة العميل في أحد تطبيقات الويب HtmlService. لمزيد من المعلومات، اطّلِع على دليل مربّعات الحوار والشريط الجانبي.

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

// Display a sidebar with custom HtmlService content.
const htmlOutput = HtmlService
                       .createHtmlOutput(
                           '<p>A change of speed, a change of style...</p>',
                           )
                       .setTitle('My add-on');
SpreadsheetApp.getUi().showSidebar(htmlOutput);

المعلمات

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

• https://www.googleapis.com/auth/script.container.ui