nwjs-dialog
File dialog and message box for NW.js.
Install
npm install nwjs-dialog
Open Dialog
Shows an open dialog.
dialog.showOpenDialog([win, ]options)
-
win
(optional) -
options
(optional)-
title
/nwdirectorydesc
string (optional) - Dialog title. -
defaultPath
/nwworkingdir
string (optional) - Default path -
openDirectory
/nwdirectory
boolean (optional) - Select directory,false
by default -
multiple
boolean (optional) - Allow multiple files to be selected,false
by default -
accept
string (optional) - Defines the file types should accept -
returnFormat
string (optional) - Return format,"string"
or"file"
,"string"
by default
-
Returns Promise<string[] | File[]>
- Resolve with an array of files or file paths chosen by the user.
The win
argument allows the dialog to attach itself to a parent window, making it modal.
multiple
and accept
have no effect when openDirectory
(nwdirectory
) is true
.
title
(nwdirectorydesc
) valid only when openDirectory
(nwdirectory
) is true
.
const { showOpenDialog } = require("nwjs-dialog");
showOpenDialog().then(([filePath]) => {
console.log(filePath);
});
showOpenDialog({
title: "Dialog title",
defaultPath: process.cwd(),
openDirectory: false,
multiple: true,
accept: "audio/*,video/*,image/*,.txt",
returnFormat: "string",
}).then((filePaths) => {
console.log(filePaths);
});
Save Dialog
Shows a save dialog.
dialog.showSaveDialog([win, ]options)
-
win
(optional) -
options
(optional)-
defaultPath
/nwworkingdir
string (optional) - Default path -
filename
/nwsaveas
string (optional) - Default filename for saving -
accept
string (optional) - Defines the file types should accept -
returnFormat
string (optional) - Return format,"string"
or"file"
,"string"
by default
-
Returns Promise<string[] | File[]>
- Resolve with an array of files or file paths chosen by the user.
The win
argument allows the dialog to attach itself to a parent window, making it modal.
When filename
(nwsaveas
) is omitted, the filename defaults to empty.
const fs = require("fs");
const { showSaveDialog } = require("nwjs-dialog");
showSaveDialog().then(([filePath]) => {
fs.writeFileSync(filePath, "Hello");
});
showSaveDialog({
defaultPath: process.cwd(),
filename: "1.txt",
accept: "audio/*,video/*,image/*,.txt",
returnFormat: "string",
}).then(([filePath]) => {
fs.writeFileSync(filePath, "Hello");
});
Message Box
Shows a message box.
The first call will create a MessageBox directory in the working directory to store temporary html files and icon files.
const { showMessageBox } = require("nwjs-dialog");
showMessageBox({ message: "Message" });
showMessageBox({ message: "Something is wrong", type: "error" });
dialog.showMessageBox([win, ]options)
-
win
(optional) - Iftitle
option is omitted, it will be the win's title. -
options
-
message
string - Content of the message box -
type
string (optional) - Can be "none", "info", "error", "question", "warning" or "success" -
buttons
string[] (optional) - Array of texts for buttons -
title
string (optional) - Title of the message box -
detail
string (optional) - Extra information of the message -
checkboxLabel
string (optional) - If provided, the message box will include a checkbox with the given label -
checkboxChecked
boolean (optional) - Initial checked state of the checkbox.false
by default -
icon
string (optional) - Custom icon -
id
string (optional) - Message box window id -
platform
string (optional) - Message box style. "default", "win32" or "darwin". Follow the os bydefault
-
customStyle
string (optional) - Custom style for message box elements -
inputOptions
object (optional) - User input options -
onLoad
function(win) => void
(optional) - Called when the message box was loaded. -
onClose
function(returnValue, win) => Promise<boolean|void>
(optional) - Called before the message box closes, returnfalse
will prevents the window close. -
onValidate
function(errors, win) => void
(optional) - Called after input option validate, contains all input options errors, if everything is correct, it will be an empty array.
-
Returns Promise<MessageBoxReturnValue>
- Resolve with an object containing the following:
-
button
number - The index of the clicked button.-1
if close button clicked. -
checkboxChecked
boolean - The checked state of the checkbox ifcheckboxLabel
was set. -
inputData
object - Data of theinputOptions
-
radios
number - The index of the checked radio of theinputOptions.radios
-
checkboxes
boolean[] - The checked states of theinputOptions.checkboxes
-
inputs
string[] - The values of theinputOptions.inputs
-
const { showMessageBox } = require("nwjs-dialog");
showMessageBox({
message: "Message",
type: "info",
buttons: ["OK", "Cancel"],
title: "Title",
detail: "Detail",
checkboxLabel: "Checkbox",
checkboxChecked: true,
icon: "",
platform: "default",
customStyle: ".win32 .button:first-child { border-color: #0078d7; }",
}).then(({ button, checkboxChecked }) => {
console.log(button);
console.log(checkboxChecked);
});
Custom Style
Main elements's class names:
/* .header */
.header-icon {}
.title {}
/* .body */
.body-icon {}
.message {}
.detail {}
/* .input-options */
.checkbox-label {}
.checkbox-input {}
.radio-label {}
.radio-input {}
.input-label {}
.input-input {}
.description {}
/* .footer */
.button {}
/* platforms */
.win32 * {}
.darwin * {}
/* types */
.none {}
.info {}
.question {}
.warning {}
.error {}
.success {}
Input Options
You can add simple input options in message box.
inputOptions
object (optional) - User input options
-
radios
object[] (optional)-
label
string (optional) - Text for the item's label. -
value
boolean (optional) - Default value for the item. -
description
string (optional) - Description for the item.
-
-
checkboxes
object[] (optional)-
label
string (optional) - Text for the item's label. -
value
boolean (optional) - Default value for the item. -
description
string (optional) - Description for the item. -
required
boolean (optional) - Whether the checkbox must be checked.
-
-
inputs
object[] (optional)-
label
string (optional) - Text for the item's label. -
value
string (optional) - Default value for the item. -
description
string (optional) - Description for the item. -
placeholder
string (optional) - Placeholder for input. -
password
string (optional) - Set to password input. -
required
boolean (optional) - Whether the input is required. -
rule
RegExp |(value: string) => boolean
(optional) - Validation rule for the input. e.g./^\d+$/
-
const { showMessageBox } = require("nwjs-dialog");
showMessageBox({
title: "Input Options",
inputOptions: {
radios: [
{ label: "Radio 1" },
{ label: "Radio 2", value: true, description: "Description" },
],
checkboxes: [
{ label: "Checkbox 1", description: "Description" },
{ label: "Checkbox 2", value: true },
],
inputs: [
{
label: "Input 1",
placeholder: "Placeholder",
description: "Description",
},
{
label: "Input 2",
value: "123456",
password: true,
description: "Password Input",
},
],
},
}).then(({ button, inputData }) => {
if (button === 0) {
const { radios, checkboxes, inputs } = inputData;
console.log({ radios, checkboxes, inputs });
}
});
inputOptions
validators
const { showMessageBox } = require("nwjs-dialog");
showMessageBox({
title: "Simple Inputs Validators",
inputOptions: {
checkboxes: [
{ label: "Checkbox", required: true, description: "Required" },
],
inputs: [
{ label: "Input 1", value: "", required: true, description: "Required" },
{
label: "Input 2",
value: "abc",
rule: /^[0-9]+$/,
description: "A RegExp rule. This input can only have numbers.",
},
{
label: "Input 2",
value: "Value",
rule: (value) => value === "ssnangua",
description: "A function rule. This input must be `ssnangua`.",
},
],
},
// Called after input option validate, contains all input options errors, if everything is correct, it will be an empty array.
onValidate(errors, win) {
win.window.document
.querySelector(".button:first-child")
.classList[errors.length > 0 ? "add" : "remove"]("disabled");
},
});
Example: Login Window
Here is a simple login window example:
const { showMessageBox } = require("nwjs-dialog");
const customStyle = `.message {
margin: 0 auto;
}
.button {
border: 1px solid #dcdfe6;
border-radius: 4px;
padding: 2px 8px;
}
.darwin .button {
padding: 4px 8px;
}
.button:first-child {
background: #409eff;
color: #fff;
}
.button:first-child:hover {
background: #66b1ff;
}
.button:last-child {
background: #fff;
border-color: #dcdfe6;
}
.button:last-child:hover {
background: #ecf5ff;
border-color: #c6e2ff;
color: #409eff;
}`;
showMessageBox({
id: "loginWin",
message: "Awesome Web App",
type: "none",
buttons: ["Login", "Cancel"],
title: "Login",
checkboxLabel: 'Agree to the <a href="#" target="_blank">User Agreement</a>.',
checkboxChecked: true,
icon: "./images/user.png",
customStyle,
inputOptions: {
inputs: [
{ label: "User", placeholder: "Nickname / Email" },
{ label: "Password", value: "", password: true },
],
checkboxes: [{ label: "Remenber me" }],
},
onClose({ button, checkboxChecked, inputData }, win) {
if (button === 0) {
const [user, password] = inputData.inputs;
if (!user || !password) {
win.window.alert("User and password cannot be empty.");
// You can modify the elements of message box, too.
// win.window.document.querySelector(".message").style.color = "red";
return false;
} else if (!checkboxChecked) {
win.window.alert("You need to agree to the User Agreement.");
return false;
} else {
// Can return a promise and you can send network requests to validate the data
return new Promise((resolve) => {
setTimeout(() => {
if (user !== "ssnangua") {
win.window.alert("Incorrect user or password.");
resolve(false);
} else {
resolve(true);
}
}, 1000);
});
}
}
},
}).then(({ button, inputData }) => {
if (button === 0) {
const [user, password] = inputData.inputs;
const [remenberMe] = inputData.checkboxes;
console.log(user, password, remenberMe);
}
});
NOTE
If the message box was opened through another window, the resolve handler will be lost when the window is closed.
So if you need to do some important processing on user input, you should open the message box in bg-script.
Or you can make the window uncloseable until the message box is closed:
let msgbox = true;
showMessageBox({
message: "A modal message box",
}).then(() => (msgbox = false));
const curWin = nw.Window.get();
curWin.on("close", () => {
if (!msgbox) curWin.close(true);
});
Or use with nwjs-window-manager
:
npm install nwjs-window-manager
const { wm } = require("nwjs-window-manager");
showMessageBox({
message: "A modal message box",
onLoad(win) {
wm(win, {
parent: nw.Window.get(),
modal: true,
});
},
});
Change Log
1.0.5
- Fix: use
nw.require(...)
instead ofimport ... from ...
to importpath
andfs
.
1.0.6
- Feature:
showOpenDialog
andshowSaveDialog
addreturnFormat
option.
1.1.0
- Feature: add alias:
nwdirectorydesc
->title
,nwworkingdir
->defaultPath
,nwdirectory
->openDirectory
,nwsaveas
->filename
- Fix: header-icon use base64 image