تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

Class Ui

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

// 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.');
}

أماكن إقامة

الموقع	النوع	الوصف
`Button`	`Button`	فهرس يمثّل أزرار مربّعات الحوار المترجَمة والمحدّدة مسبقًا التي يعرضها التنبيه أو `PromptResponse.getSelectedButton()` للإشارة إلى الزر الذي نقر عليه المستخدم في مربّع الحوار
`ButtonSet`	`ButtonSet`	فهرس يمثّل مجموعات مُحدَّدة مسبقًا ومُترجَمة من زرّ واحد أو أكثر من أزرار مربّع الحوار يمكن إضافتها إلى تنبيه أو طلب

الطُرق

الطريقة	نوع القيمة التي يتم عرضها	وصف قصير
`alert(prompt)`	`Button`	يفتح مربّع حوار في محرِّر المستخدم يتضمّن الرسالة المحدّدة وزر "حسنًا".
`alert(prompt, buttons)`	`Button`	يفتح مربّع حوار في محرِّر المستخدم يتضمّن الرسالة المحدّدة ومجموعة الأزرار.
`alert(title, prompt, buttons)`	`Button`	يفتح مربّع حوار في محرِّر المستخدم يتضمّن العنوان والرسالة ومجموعة الأزرار المحدّدة.
`createAddonMenu()`	`Menu`	تُنشئ هذه الميزة أداة إنشاء يمكن استخدامها لإدراج قائمة فرعية في قائمة "الإضافات" في المحرّر.
`createMenu(caption)`	`Menu`	تُنشئ أداة إنشاء يمكن استخدامها لإضافة قائمة إلى واجهة مستخدم المحرِّر.
`prompt(prompt)`	`PromptResponse`	يفتح مربّع حوار إدخال في محرِّر المستخدم يتضمّن الرسالة المحدّدة وزر "حسنًا".
`prompt(prompt, buttons)`	`PromptResponse`	يفتح مربّع حوار إدخال في محرِّر المستخدم يتضمّن الرسالة المحدّدة ومجموعة من الأزرار.
`prompt(title, prompt, buttons)`	`PromptResponse`	يفتح مربّع حوار إدخال في محرِّر المستخدم يتضمّن العنوان والرسالة ومجموعة buttons.
`showModalDialog(userInterface, title)`	`void`	يفتح مربّع حوار مشروطًا في محرِّر المستخدم يتضمّن محتوى مخصّصًا من جهة العميل.
`showModelessDialog(userInterface, title)`	`void`	يفتح مربّع حوار بدون وضع في محرِّر المستخدم يحتوي على محتوى مخصّص من جهة العميل.
`showSidebar(userInterface)`	`void`	يؤدي هذا الإجراء إلى فتح شريط جانبي في محرِّر المستخدم يتضمّن محتوى مخصّصًا من جهة العميل.

الطرق المتوقّفة

الطريقة	نوع القيمة التي يتم عرضها	وصف قصير
`showDialog(userInterface)`	`void`	يفتح مربّع حوار في محرِّر المستخدم يحتوي على محتوى مخصّص من جهة العميل.

مستندات تفصيلية

`alert(prompt)`

يفتح مربّع حوار في محرِّر المستخدم يتضمّن الرسالة المحدّدة وزر "حسنًا". تعمل هذه الطريقة على تعليق النص البرمجي من جهة الخادم عندما يكون مربّع الحوار مفتوحًا. يستأنف النص البرمجي بعد أن يُغلق المستخدم مربع الحوار، ولكن لا تظل 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');

المعلَمات

الاسم	النوع	الوصف
`prompt`	`String`	الرسالة المطلوب عرضها في مربّع الحوار

الإرجاع

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

`alert(prompt, buttons)`

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

المعلَمات

الاسم	النوع	الوصف
`prompt`	`String`	الرسالة المطلوب عرضها في مربّع الحوار
`buttons`	`ButtonSet`	الزر الذي تم ضبطه للظهور في مربّع الحوار

الإرجاع

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

`alert(title, prompt, buttons)`

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

المعلَمات

الاسم	النوع	الوصف
`title`	`String`	العنوان الذي سيتم عرضه أعلى مربّع الحوار
`prompt`	`String`	الرسالة المطلوب عرضها في مربّع الحوار
`buttons`	`ButtonSet`	الزر الذي تم ضبطه للظهور في مربّع الحوار

الإرجاع

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

`createAddonMenu()`

تُنشئ هذه الميزة أداة إنشاء يمكن استخدامها لإدراج قائمة فرعية في قائمة "الإضافات" في المحرّر. لا يتم تعديل 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 - أداة إنشاء القوائم الجديدة

`createMenu(caption)`

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

المعلَمات

الاسم	النوع	الوصف
`caption`	`String`	تصنيف القائمة، مع كتابة جميع الكلمات الرئيسية بأحرف كبيرة في القائمة ذات المستوى الأعلى، أو كتابة الكلمة الأولى فقط بأحرف كبيرة في القائمة الفرعية

الإرجاع

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

`prompt(prompt)`

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

المعلَمات

الاسم	النوع	الوصف
`prompt`	`String`	الرسالة المطلوب عرضها في مربّع الحوار

الإرجاع

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

`prompt(prompt, buttons)`

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

المعلَمات

الاسم	النوع	الوصف
`prompt`	`String`	الرسالة المطلوب عرضها في مربّع الحوار
`buttons`	`ButtonSet`	الزر الذي تم ضبطه للظهور في مربّع الحوار

الإرجاع

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

`prompt(title, prompt, buttons)`

يفتح مربّع حوار إدخال في محرِّر المستخدم يتضمّن العنوان والرسالة ومجموعة 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.');
}

المعلَمات

الاسم	النوع	الوصف
`title`	`String`	العنوان الذي سيتم عرضه أعلى مربّع الحوار
`prompt`	`String`	الرسالة المطلوب عرضها في مربّع الحوار
`buttons`	`ButtonSet`	الزر الذي تم ضبطه للظهور في مربّع الحوار

الإرجاع

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

`showModalDialog(userInterface, title)`

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

المعلَمات

الاسم	النوع	الوصف
`userInterface`	`Object`	`HtmlOutput` يمثّل الواجهة المطلوب عرضها.
`title`	`String`	عنوان مربّع الحوار، ويلغي أي عنوان تم ضبطه من خلال استدعاء `setTitle()` على عنصر `userInterface`.

التفويض

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

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

`showModelessDialog(userInterface, title)`

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

المعلَمات

الاسم	النوع	الوصف
`userInterface`	`Object`	`HtmlOutput` يمثّل الواجهة المطلوب عرضها.
`title`	`String`	عنوان مربّع الحوار، ويلغي أي عنوان تم ضبطه من خلال استدعاء `setTitle()` على عنصر `userInterface`.

التفويض

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

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

`showSidebar(userInterface)`

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

المعلَمات

الاسم	النوع	الوصف
`userInterface`	`Object`	`HtmlOutput` يمثّل الواجهة المطلوب عرضها.

التفويض

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

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

الطرق المتوقّفة

`showDialog(userInterface)`

تمّ إيقاف هذا العمود نهائيًا. اعتبارًا من آذار (مارس) 2014، تم إيقاف هذه الطريقة نهائيًا. البديل المباشر هو showModelessDialog(userInterface, title)، ولكن showModalDialog(userInterface, title) هو خيار أفضل في جميع الحالات تقريبًا.

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

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

المعلَمات

الاسم	النوع	الوصف
`userInterface`	`Object`	`HtmlOutput` يمثّل الواجهة المطلوب عرضها.

التفويض

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

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