nsIPromptService

2 位贡献者:

该接口用来显示一些简单的对话框.在chrome上下文,你应该使用该接口的所属方法来替代常规的DOM方法,例如 window.alert, window.confirm, 等.
继承于: nsISupports 最后修改于Gecko 1.7.5

You can define access keys (or keyboard shortcuts) for buttons by including an ampersand ("&") in front of the character that should be the access key for that button. If you need to include an ampersand in the button's text, use two of them, like this: "&&".

Note: Some of these interface methods use out and inout parameters. In C++, out parameters are pointers. For JavaScript, they are extra work, as you can't use an out parameter directly. You need to wrap them in a temporary object, which can be either empty or have a value property set to the out parameter type. For more information on out parameters and JavaScript refer to Working with out parameters.

该接口由: @mozilla.org/embedcomp/prompt-service;1 组件实现,下面的代码可以得到一个promptService对象实例:

var promptService = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                              .getService(Components.interfaces.nsIPromptService);

方法概述

void alert(in nsIDOMWindow aParent, in wstring aDialogTitle, in wstring aText);
void alertCheck(in nsIDOMWindow aParent, in wstring aDialogTitle, in wstring aText, in wstring aCheckMsg, inout boolean aCheckState);
boolean confirm(in nsIDOMWindow aParent, in wstring aDialogTitle, in wstring aText);
boolean confirmCheck(in nsIDOMWindow aParent, in wstring aDialogTitle, in wstring aText, in wstring aCheckMsg, inout boolean aCheckState);
PRInt32 confirmEx(in nsIDOMWindow aParent,in wstring aDialogTitle,in wstring aText, in unsigned long aButtonFlags,in wstring aButton0Title, in wstring aButton1Title,in wstring aButton2Title,in wstring aCheckMsg, inout boolean aCheckState);
boolean prompt(in nsIDOMWindow aParent, in wstring aDialogTitle, in wstring aText, inout wstring aValue, in wstring aCheckMsg, inout boolean aCheckState);
boolean promptUsernameAndPassword(in nsIDOMWindow aParent, in wstring aDialogTitle, in wstring aText, inout wstring aUsername, inout wstring aPassword, in wstring aCheckMsg, inout boolean aCheckState);
boolean promptPassword(in nsIDOMWindow aParent, in wstring aDialogTitle, in wstring aText, inout wstring aPassword, in wstring aCheckMsg, inout boolean aCheckState);
boolean select(in nsIDOMWindow aParent, in wstring aDialogTitle, in wstring aText, in PRUint32 aCount, [array, size_is(aCount)] in wstring aSelectList, out long aOutSelection);

常量

The following flags are combined to form the aButtonFlags parameter passed to confirmEx. All flags are defined as unsigned long constants and can be accessed as Components.interfaces.nsIPromptService.flagname from JavaScript and as nsIPromptService::flagname from C++.

Button position flags

On Linux and Mac, button 2 is on the left of the prompt, while buttons 1 and 0 are on the right. On Windows and OS/2, the buttons are centred in the order 0, 2, 1.

Constant Value Description
BUTTON_POS_0 1 This is usually the button used to confirm the prompt. It typically has the label "OK", "Yes" or "Save".
BUTTON_POS_1 256 This is the button used to cancel the prompt. It typically has the label "Cancel" or "No". It is equivalent to pressing the Escape key (or Cmd+. on the Mac), or closing the window through the OS controls.
BUTTON_POS_2 65536 This button can be used to give the user a choice of options, but still allowing the user to cancel the prompt. For instance, it might have the label "Don't Save".

Button title flags

These flags are used along with Button position flags to set the labels of buttons in the prompt.

Constant Value Description
BUTTON_TITLE_OK 1  These flags are used to select standard labels from the user's current locale.
BUTTON_TITLE_CANCEL 2
BUTTON_TITLE_YES 3
BUTTON_TITLE_NO 4
BUTTON_TITLE_SAVE 5
BUTTON_TITLE_DONT_SAVE 6
BUTTON_TITLE_REVERT 7
BUTTON_TITLE_IS_STRING 127 This flag indicates that the label is passed as a separate string. Use this for labels that don't match one of the constants above.

Button default flags

These flags are used to select which button is the default.

Constant Value Description
BUTTON_POS_0_DEFAULT 0  
BUTTON_POS_1_DEFAULT 16777216  
BUTTON_POS_2_DEFAULT 33554432  

BUTTON_DELAY_ENABLE

BUTTON_DELAY_ENABLE causes the buttons to be initially disabled. They are enabled after a timeout expires. The implementation may interpret this loosely, as the intent is to ensure that the user does not click through a security dialog too quickly. Strictly speaking, the implementation could choose to ignore this flag. A delay can be useful not only to give the user more time to think before acting, but also as a countermeasure against malicious web sites that intentionally create a race condition whereby the user intends to click or type a key responding, for example, to the web site's prompt but the security dialog pops up unexpectedly and its button is unintentionally activated.

Constant Value Description
BUTTON_DELAY_ENABLE 67108864  

Standard Buttons flags

Constant Value Description
STD_OK_CANCEL_BUTTONS 513

selects the standard set of OK/Cancel buttons.

(BUTTON_TITLE_OK *BUTTON_POS_0) +(BUTTON_TITLE_CANCEL * BUTTON_POS_1)
STD_YES_NO_BUTTONS 1027

selects the standard set of Yes/No buttons.

(BUTTON_TITLE_YES *BUTTON_POS_0) +(BUTTON_TITLE_NO * BUTTON_POS_1)

方法

alert()

alert 方法显示一个警告对话框,包含一个确认按钮. 除了可以设置对话框的标题以外,效果和window.alert全都相同 . 在chrome上下文,你应该使用该xpcom方法来替代window.alert.

void alert(
  in nsIDOMWindow aParent,
  in wstring aDialogTitle,
  in wstring aText
);
参数
aParent
对话框的父窗口,如果该值设为 null,则父窗口为当前激活的窗口 nsIWindowWatcher.activeWindow.
aDialogTitle
对话框的标题文字.
aText
对话框的内容文字.

代码示例:alert_example.

alertCheck()

显示一个警告对话框,包含一个确认按钮和一个复选框.

void alertCheck(
  in nsIDOMWindow aParent,
  in wstring aDialogTitle,
  in wstring aText,
  in wstring aCheckMsg,
  inout boolean aCheckState
);
参数
aParent
对话框的父窗口,如果该值设为 null,则父窗口为当前激活的窗口 nsIWindowWatcher.activeWindow..
aDialogTitle
对话框的标题文字.
aText
对话框的内容文字.
aCheckMsg
复选框的说明文字.
aCheckState
该变量是一个对象引用,当对话框打开时,变量的value属性控制了复选框的初始选择状态.当对话框关闭时,变量的value属性会存储下复选框的最后选择状态.该变量初始化时可以包含一个类型为布尔值的value属性或者是空对象.

代码示例:alertCheck_example.

confirm()

显示一个确认对话框,包含一个确认按钮和一个取消按钮.

boolean confirm(
  in nsIDOMWindow aParent,
  in wstring aDialogTitle,
  in wstring aText
);
参数
aParent
对话框的父窗口,如果该值设为 null,则父窗口为当前激活的窗口 nsIWindowWatcher.activeWindow.
aDialogTitle
对话框的标题文字.
aText
对话框的内容文字.
返回值
点确定按钮返回 true , 点取消按钮返回 false

代码示例:confirm_example.

confirmCheck()

显示一个对话框,包含一个确认按钮,一个取消按钮和一个复选框.

代码示例:confirm_example.

boolean confirmCheck(
  in nsIDOMWindow aParent,
  in wstring aDialogTitle,
  in wstring aText,
  in wstring aCheckMsg,
  inout boolean aCheckState
);
参数
aParent
对话框的父窗口,如果该值设为 null,则父窗口为当前激活的窗口 nsIWindowWatcher.activeWindow.
aDialogTitle
对话框的标题文字.
aText
对话框的内容文字.
aCheckMsg
复选框的说明文字.
aCheckState
该变量是一个对象引用,当对话框打开时,变量的value属性控制了复选框的初始选择状态.当对话框关闭时,变量的value属性会存储下复选框的最后选择状态.该变量初始化时可以包含一个类型为布尔值的value属性或者是空对象.
返回值
点确定按钮返回 true , 点取消按钮返回 false

confirmEx()

Puts up a dialog with up to 3 buttons and an optional, labeled checkbox.

The Buttons are numbered 0 - 2. The implementation can decide what order the buttons appear in, and it may not be simply right-to-left (2, 1, 0) or left-to-right (0, 1, 2). See bug 624043 for more on this. Button 0 is the default button unless one of the Button Default Flags is specified (see Button default flags).

A button may use a predefined title, specified by one of the Button Title Flags values. Each title value can be multiplied by a position value to assign the title to a particular button. If BUTTON_TITLE_IS_STRING is used for a button, the string parameter for that button will be used. If the value for a button position is zero, the button will not be shown.

The following Example creates a Dialog with an OK button an an custom button description.

aButtonFlags = (BUTTON_POS_0) * (BUTTON_TITLE_OK) +
(BUTTON_POS_1) * (BUTTON_TITLE_IS_STRING) +
BUTTON_POS_1_DEFAULT;

confirmEx always returns 1 if the user closes the window using the close button in the titlebar! bug 345067
PRInt32 confirmEx(
  in nsIDOMWindow  aParent,
  in wstring aDialogTitle,
  in wstring aText,
  in unsigned long aButtonFlags,
  in wstring aButton0Title,
  in wstring aButton1Title,
  in wstring aButton2Title,
  in wstring aCheckMsg,
  inout boolean aCheckState
);
参数
aParent
对话框的父窗口,如果该值设为 null,则父窗口为当前激活的窗口 nsIWindowWatcher.activeWindow.
aDialogTitle
对话框的标题文字.
aText
对话框的内容文字.
aButtonFlags
aButtonFlags is a combination of Button flags as described in Using the button flags below.
aButton0Title
caption displayed for button 0 if(BUTTON_TITLE_IS_STRING*BUTTON_TITLE_POS_0) flags are set in aButtonFlags
aButton1Title
caption displayed for button 1 if(BUTTON_TITLE_IS_STRING*BUTTON_TITLE_POS_1) flags are set in aButtonFlags
aButton2Title
caption displayed for button 2 if(BUTTON_TITLE_IS_STRING*BUTTON_TITLE_POS_2) flags are set in aButtonFlags
aCheckMsg
 复选框的说明文字. 如果值设为Null,则复选框不会显示.
aCheckState
该变量是一个对象引用,当对话框打开时,变量的value属性控制了复选框的初始选择状态.当对话框关闭时,变量的value属性会存储下复选框的最后选择状态.该变量初始化时可以包含一个类型为布尔值的value属性或者是空对象.
返回值
按下按钮的索引.

prompt()

显示一个对话框,包含一个文本框,一个可选的复选框.

代码示例:prompt_example.

boolean prompt(
  in nsIDOMWindow aParent,
  in wstring aDialogTitle,
  in wstring aText,
  inout wstring aValue,
  in wstring aCheckMsg,
  inout boolean aCheckState
);
参数
aParent
对话框的父窗口,如果该值设为 null,则父窗口为当前激活的窗口 nsIWindowWatcher.activeWindow.
aDialogTitle
对话框的标题文字.
aText
对话框的内容文字.
aValue
该变量是一个对象引用,当对话框打开时,变量的value属性值就是文本输入框的的初始值.当用户点击确认按钮关闭对话框时,变量的value属性会存储下文本输入框的最后确定值.其他方法关闭对话框时,变量的value属性值不会改变.该变量初始化时可以包含一个类型为字符串值的value属性或者是空对象.
aCheckMsg
复选框的说明文字. 如果值设为Null,则复选框不会显示.
aCheckState
该变量是一个对象引用,当对话框打开时,变量的value属性控制了复选框的初始选择状态.当对话框关闭时,变量的value属性会存储下复选框的最后选择状态.该变量初始化时可以包含一个类型为布尔值的value属性或者是空对象.
返回值
点确定按钮返回 true , 点取消按钮返回 false

promptUsernameAndPassword()

显示一个对话框,内部包含一个文本输入框,一个密码输入框,和一个可选的复选框.

代码示例:promptUsernameAndPassword_example.

boolean promptUsernameAndPassword(
  in nsIDOMWindow aParent,
  in wstring aDialogTitle,
  in wstring aText,
  inout wstring aUsername,
  inout wstring aPassword,
  in wstring aCheckMsg,
  inout boolean aCheckState
);
参数
aParent
对话框的父窗口,如果该值设为 null,则父窗口为当前激活的窗口 nsIWindowWatcher.activeWindow.
aDialogTitle
对话框的标题文字.
aText
对话框的内容文字.
aUsername
该变量是一个对象引用,当对话框打开时,变量的value属性值就是用户名输入框的的初始值.当用户点击确认按钮关闭对话框时,变量的value属性会存储下用户名输入框的最后确定值.其他方法关闭对话框时,变量的value属性值不会改变.该变量初始化时可以包含一个类型为字符串值的value属性或者是空对象.
aPassword
该变量是一个对象引用,当对话框打开时,变量的value属性值就是密码输入框的的初始值.当用户点击确认按钮关闭对话框时,变量的value属性会存储下密码输入框的最后确定值.其他方法关闭对话框时,变量的value属性值不会改变.该变量初始化时可以包含一个类型为字符串值的value属性或者是空对象.
aCheckMsg
复选框的说明文字. 如果值设为Null,则复选框不会显示.
aCheckState
该变量是一个对象引用,当对话框打开时,变量的value属性控制了复选框的初始选择状态.当对话框关闭时,变量的value属性会存储下复选框的最后选择状态.该变量初始化时可以包含一个类型为布尔值的value属性或者是空对象.
返回值
点确定按钮返回 true , 点取消按钮返回 false

promptPassword()

显示一个对话框,包含一个密码框,一个可选的复选框.

代码示例:promptPassword_example.

boolean promptPassword(
  in nsIDOMWindow aParent,
  in wstring aDialogTitle,
  in wstring aText,
  inout wstring aPassword,
  in wstring aCheckMsg,
  inout boolean aCheckState
);
参数
aParent
对话框的父窗口,如果该值设为 null,则父窗口为当前激活的窗口 nsIWindowWatcher.activeWindow.
aDialogTitle
对话框的标题文字.
aText
对话框的内容文字.
aPassword
该变量是一个对象引用,当对话框打开时,变量的value属性值就是密码输入框的的初始值.当用户点击确认按钮关闭对话框时,变量的value属性会存储下密码输入框的最后确定值.其他方法关闭对话框时,变量的value属性值不会改变.该变量初始化时可以包含一个类型为字符串值的value属性或者是空对象.
aCheckMsg
复选框的说明文字. 如果值设为Null,则复选框不会显示.
aCheckState
    该变量是一个对象引用,当对话框打开时,变量的value属性控制了复选框的初始选择状态.当对话框关闭时,变量的value属性会存储下复选框的最后选择状态.该变量初始化时可以包含一个类型为布尔值的value属性或者是空对象.
返回值
点确定按钮返回 true , 点取消按钮返回 false

select()

显示一个对话框,包含一个单项选择的字符串列表.

代码示例:select_example.

boolean select(
  in  nsIDOMWindow aParent,
  in  wstring       aDialogTitle,
  in  wstring       aText,
  in  PRUint32     aCount,
  [array, size_is(aCount)] in wstring aSelectList,
  out long         aOutSelection
);
aParent
对话框的父窗口,如果该值设为 null,则父窗口为当前激活的窗口 nsIWindowWatcher.activeWindow.
aDialogTitle
对话框的标题文字.
aText
对话框的内容文字.
aCount
参数aSelectList的数组长度.
aSelectList
构成字符串列表的字符串数组.
aOutSelection
该变量是一个对象引用,当用户选择某个项目后,变量的value属性值存储了用户所选列表项目的索引值.
返回值
点确定按钮返回 true , 点取消按钮返回 false

代码示例

 

alert example

alert() 显示一个简单的对话框.

var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);

prompts.alert(null, "Title of this Dialog", "Hello! You have now been alerted.");

alertCheck example

alertCheck() 显示一个包含复选框的对话框

var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);

var check = {value: false};                      // default the checkbox to false

prompts.alertCheck(null, "Title of this Dialog", "Hello! You have now been alerted.",
                   "And this is a checkbox", check);

// check.value is now true if the box was checked and false if the box was cleared

confirm example

confirm() 显示一个提示框,内部包含一个确认按钮和一个取消按钮.

var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);

var result = prompts.confirm(null, "Title of this Dialog", "Are you sure?");

// result is now true if OK was clicked, and false if cancel was clicked

confirmCheck example

confirmCheck 显示一个提示框,内部包含一个确认按钮,一个取消按钮,一个复选框.

var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);

var check = {value: true};                   // default the checkbox to true

var result = prompts.confirmCheck(null, "Title of this Dialog", "Are you sure?",
                                  "Don't ask again", check);

// check.value is now true if the box was checked AND OK was pressed, false if
// the box was cleared AND OK was pressed, and is the default of true if Cancel was pressed.

confirmEx example

confirmEx()  显示一个对话框,内部包含三个或三个以下的按纽,和一个可选的复选框.

var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);

var check = {value: false};                  // default the checkbox to false

var flags = prompts.BUTTON_POS_0 * prompts.BUTTON_TITLE_SAVE +
            prompts.BUTTON_POS_1 * prompts.BUTTON_TITLE_IS_STRING  +
            prompts.BUTTON_POS_2 * prompts.BUTTON_TITLE_CANCEL;
// This value of flags will create 3 buttons. The first will be "Save", the
// second will be the value of aButtonTitle1, and the third will be "Cancel"

var button = prompts.confirmEx(null, "Title of this Dialog", "What do you want to do?",
                               flags, "", "Button 1", "", null, check);

// The checkbox will be hidden, and button will contain the index of the button pressed,
// 0, 1, or 2.

prompt example

prompt() 显示一个对话框,内部包含一个文本输入框.

var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);

var check = {value: false};                  // default the checkbox to false

var input = {value: "Bob"};                  // default the edit field to Bob

var result = prompts.prompt(null, "Title", "What is your name?", input, null, check);

// result is true if OK is pressed, false if Cancel. input.value holds the value of the edit field if "OK" was pressed.

promptUsernameAndPassword example

promptUsernameAndPassword() 显示一个对话框,内部包含一个文本输入框,一个密码输入框和一个可选的复选框.

var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);

var username = {value: "user"};              // default the username to user

var password = {value: "pass"};              // default the password to pass

var check = {value: true};                   // default the checkbox to true

var result = prompts.promptUsernameAndPassword(null, "Title", "Enter username and password:",
                                               username, password, "Save", check);

// result is true if OK was pressed, false if cancel was pressed. username.value,
// password.value, and check.value are set if OK was pressed.

promptPassword example

promptPassword() 显示一个对话框,内部包含一个密码输入框和一个可选的复选框.

var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);

var password = {value: "pass"};              // default the password to pass

var check = {value: true};                   // default the checkbox to true

var result = prompts.promptPassword(null, "Title", "Enter password:", password, null, check);

// result is true if OK was pressed, false if cancel was pressed. password.value is
// set if OK was pressed. The checkbox is not displayed.

select example

select() 显示一个对话框,内部是一个包含多个选项的列表框.

var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
                        .getService(Components.interfaces.nsIPromptService);

var items = ["Hello", "Welcome", "Howdy", "Hi", ":)"]; // list items

var selected = {};

var result = prompts.select(null, "Title", "What greeting do you want?", items.length,
                            items, selected);

// result is true if OK was pressed, false if cancel. selected is the index of the item array
// that was selected. Get the item using items[selected.value].

相关链接

文档标签和贡献者

向此页面作出贡献: teoli, ziyunfei
最后编辑者: teoli,