مثال لبيئة واجهة المستخدم لتطبيق 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.'); }
أماكن إقامة
الموقع | Type | الوصف |
---|---|---|
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 | لفتح مربع حوار إدخال في محرر المستخدم مع العنوان والرسالة ومجموعة الأزرار المعينة. |
showModalDialog(userInterface, title) | void | يفتح مربع حوار نمطي في محرِّر المستخدم مع محتوى مخصَّص من جهة العميل. |
showModelessDialog(userInterface, title) | void | يتم فتح مربع حوار بلا نمط في محرِّر المستخدم ويتضمّن محتوى مخصّصًا من جهة العميل. |
showSidebar(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');
المَعلمات
الاسم | Type | الوصف |
---|---|---|
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.'); }
المَعلمات
الاسم | Type | الوصف |
---|---|---|
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.'); }
المَعلمات
الاسم | Type | الوصف |
---|---|---|
title | String | العنوان الذي سيتم عرضه أعلى مربع الحوار. |
prompt | String | الرسالة التي سيتم عرضها في مربّع الحوار. |
buttons | ButtonSet | الزر الذي يتم عرضه في مربع الحوار. |
استرجاع الكرة
Button
- الزر الذي نقر عليه المستخدم
createAddonMenu()
تنشئ أداة إنشاء يمكن استخدامها لإدراج قائمة فرعية في قائمة "الإضافات" بالمحرر. لن يتم تحديث
القائمة إلا بعد استدعاء 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(); }
المَعلمات
الاسم | Type | الوصف |
---|---|---|
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. 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.'); }
المَعلمات
الاسم | Type | الوصف |
---|---|---|
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.'); }
المَعلمات
الاسم | Type | الوصف |
---|---|---|
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.'); }
المَعلمات
الاسم | Type | الوصف |
---|---|---|
title | String | العنوان الذي سيتم عرضه أعلى مربع الحوار. |
prompt | String | الرسالة التي سيتم عرضها في مربّع الحوار. |
buttons | ButtonSet | الزر الذي يتم عرضه في مربع الحوار. |
استرجاع الكرة
PromptResponse
- تمثيل لردّ المستخدم
showModalDialog(userInterface, title)
يفتح مربع حوار نمطي في محرِّر المستخدم مع محتوى مخصَّص من جهة العميل. لا تعلِّق هذه الطريقة النص البرمجي من جهة الخادم عندما يكون مربّع الحوار مفتوحًا. للاتصال بالنص البرمجي من جهة الخادم، يجب أن يجري المكوّن من جهة العميل عمليات استدعاء غير متزامنة باستخدام google.script
API لـ 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');
المَعلمات
الاسم | Type | الوصف |
---|---|---|
userInterface | Object | تمثّل هذه السمة HtmlOutput
الواجهة المطلوب عرضها. |
title | String | عنوان مربّع الحوار، ويؤدي إلى إلغاء أي عنوان تم ضبطه من خلال استدعاء setTitle() على الكائن userInterface . |
التفويض
تتطلب النصوص البرمجية التي تستخدم هذه الطريقة الحصول على تفويض باستخدام واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/script.container.ui
showModelessDialog(userInterface, title)
يتم فتح مربع حوار بلا نمط في محرِّر المستخدم ويتضمّن محتوى مخصّصًا من جهة العميل. لا تعلّق هذه الطريقة النص البرمجي من جهة الخادم عندما يكون مربّع الحوار مفتوحًا. للاتصال بالنص البرمجي من جهة الخادم، يجب أن يجري المكوِّن من جهة العميل عمليات استدعاء غير متزامنة باستخدام google.script
API لـ 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');
المَعلمات
الاسم | Type | الوصف |
---|---|---|
userInterface | Object | تمثّل هذه السمة HtmlOutput
الواجهة المطلوب عرضها. |
title | String | عنوان مربّع الحوار، ويؤدي إلى إلغاء أي عنوان تم ضبطه من خلال استدعاء setTitle() على الكائن userInterface . |
التفويض
تتطلب النصوص البرمجية التي تستخدم هذه الطريقة الحصول على تفويض باستخدام واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/script.container.ui
showSidebar(userInterface)
يفتح هذا الزر شريطًا جانبيًا في محرّر المستخدم يضم محتوى مخصّصًا من جهة العميل. لا تعلّق هذه الطريقة النص البرمجي من جهة الخادم عندما يكون الشريط الجانبي مفتوحًا. للاتصال بالنص البرمجي من جهة الخادم، يجب أن يجري المكوّن من جهة العميل عمليات استدعاء غير متزامنة باستخدام google.script
API لـ 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);
المَعلمات
الاسم | Type | الوصف |
---|---|---|
userInterface | Object | تمثّل هذه السمة HtmlOutput
الواجهة المطلوب عرضها. |
التفويض
تتطلب النصوص البرمجية التي تستخدم هذه الطريقة الحصول على تفويض باستخدام واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/script.container.ui