تمت ترجمة هذه الصفحة بواسطة 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.
var ui = SpreadsheetApp.getUi();
var 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`	يفتح مربع حوار في محرر المستخدم يحتوي على الرسالة المحددة، فضلاً عن الزر "حسنًا&quot.
`alert(prompt, buttons)`	`Button`	يفتح مربع حوار في محرر أدوات المستخدم يحتوي على الرسالة المحددة ومجموعة من الأزرار.
`alert(title, prompt, buttons)`	`Button`	يفتح مربع حوار في محرر المستخدم بعنوان الصفحة والرسالة ومجموعة من الأزرار.
`createAddonMenu()`	`Menu`	يُنشئ أداة إنشاء يمكن استخدامها لإدراج قائمة فرعية في قائمة الإضافات في "محرّر إعلانات Google".
`createMenu(caption)`	`Menu`	تنشئ أداة إنشاء يمكن استخدامها لإضافة قائمة إلى واجهة مستخدم المحرّر.
`prompt(prompt)`	`PromptResponse`	يفتح مربّع حوار إدخال في محرِّر المستخدم يحتوي على الرسالة المحدّدة وزر "OK&quot؛
`prompt(prompt, buttons)`	`PromptResponse`	يفتح مربع حوار إدخال في محرر المستخدم يحتوي على الرسالة المحددة ومجموعة من الأزرار.
`prompt(title, prompt, buttons)`	`PromptResponse`	يفتح مربع حوار إدخال في محرر المستخدم بالعنوان والرسالة ومجموعة من الأزرار المحددة.
`showModalDialog(userInterface, title)`	`void`	فتح مربع حوار نمطي في محرر المستخدم الذي يضم محتوى مخصص من جهة العميل.
`showModelessDialog(userInterface, title)`	`void`	يفتح مربع حوار بلا نمط في محرر المستخدم مع محتوى مخصص من جهة العميل.
`showSidebar(userInterface)`	`void`	يفتح شريطًا جانبيًا في محرِّر "المستخدمون" مع محتوى مخصّص من جهة العميل.

الطرق التي تم إيقافها نهائيًا

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

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

`alert(prompt)`

يفتح مربع حوار في محرر المستخدم يحتوي على الرسالة المحددة، فضلاً عن الزر "حسنًا&quot. تعلِّق هذه الطريقة النص البرمجي من جهة الخادم أثناء فتح مربّع الحوار. ويتم استئناف النص البرمجي بعد إغلاق المستخدم لمربّع الحوار، إلا أنّ الاتصالات 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.
var ui = SpreadsheetApp.getUi();
var 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.
var ui = SpreadsheetApp.getUi();
var 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()`

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

يفتح مربّع حوار إدخال في محرِّر المستخدم يحتوي على الرسالة المحدّدة وزر "OK&quot؛ تعلِّق هذه الطريقة النص البرمجي من جهة الخادم أثناء فتح مربّع الحوار. ويتم استئناف النص البرمجي بعد إغلاق المستخدم لمربّع الحوار، إلا أنّ الاتصالات 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.
var ui = SpreadsheetApp.getUi();
var 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.
var ui = SpreadsheetApp.getUi();
var 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)`

يفتح مربع حوار إدخال في محرر المستخدم بالعنوان والرسالة ومجموعة من الأزرار المحددة. تعلِّق هذه الطريقة النص البرمجي من جهة الخادم أثناء فتح مربع الحوار. ويتم استئناف النص البرمجي بعد إغلاق المستخدم لمربّع الحوار، ولكن لا تستمر اتصالات 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.
var ui = SpreadsheetApp.getUi();
var 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.
var 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.
var 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.
var 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.
var 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