Dialogs - 对话框
<p>[TOC]</p>
<h1>Dialogs</h1>
<blockquote>
<p>Stability: 2 - Stable</p>
</blockquote>
<p>dialogs 模块提供了简单的对话框支持，可以通过对话框和用户进行交互。最简单的例子如下：</p>
<pre><code>alert("您好");</code></pre>
<p>这段代码会弹出一个消息提示框显示"您好"，并在用户点击"确定"后继续运行。稍微复杂一点的例子如下：</p>
<pre><code>var clear = confirm("要清除所有缓存吗?");
if(clear){
alert("清除成功!");
}</code></pre>
<p><code>confirm()</code>会弹出一个对话框并让用户选择"是"或"否"，如果选择"是"则返回true。</p>
<p>需要特别注意的是，对话框在ui模式下不能像通常那样使用，应该使用回调函数或者<a href="https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>的形式。理解这一点可能稍有困难。举个例子:</p>
<pre><code>"ui";
//回调形式
confirm("要清除所有缓存吗?", function(clear){
if(clear){
alert("清除成功!");
}
});
//Promise形式
confirm("要清除所有缓存吗?")
.then(clear => {
if(clear){
alert("清除成功!");
}
});</code></pre>
<h2>dialogs.alert(title[, content, callback])</h2>
<ul>
<li><code>title</code> {string} 对话框的标题。</li>
<li><code>content</code> {string} 可选，对话框的内容。默认为空。</li>
<li><code>callback</code> {Function} 回调函数，可选。当用户点击确定时被调用,一般用于ui模式。</li>
</ul>
<p>显示一个只包含“确定”按钮的提示对话框。直至用户点击确定脚本才继续运行。</p>
<p>该函数也可以作为全局函数使用。</p>
<pre><code>alert("出现错误~", "出现未知错误，请联系脚本作者”);</code></pre>
<p>在ui模式下该函数返回一个<code>Promise</code>。例如:</p>
<pre><code>"ui";
alert("嘿嘿嘿").then(()=>{
//当点击确定后会执行这里
});</code></pre>
<h2>dialogs.confirm(title[, content, callback])</h2>
<ul>
<li><code>title</code> {string} 对话框的标题。</li>
<li><code>content</code> {string} 可选，对话框的内容。默认为空。</li>
<li><code>callback</code> {Function} 回调函数，可选。当用户点击确定时被调用,一般用于ui模式。</li>
</ul>
<p>显示一个包含“确定”和“取消”按钮的提示对话框。如果用户点击“确定”则返回 <code>true</code> ，否则返回 <code>false</code> 。</p>
<p>该函数也可以作为全局函数使用。</p>
<p>在ui模式下该函数返回一个<code>Promise</code>。例如:</p>
<pre><code>"ui";
confirm("确定吗").then(value=>{
//当点击确定后会执行这里, value为true或false, 表示点击"确定"或"取消"
});</code></pre>
<h2>dialogs.rawInput(title[, prefill, callback])</h2>
<ul>
<li><code>title</code> {string} 对话框的标题。</li>
<li><code>prefill</code> {string} 输入框的初始内容，可选，默认为空。</li>
<li><code>callback</code> {Function} 回调函数，可选。当用户点击确定时被调用,一般用于ui模式。</li>
</ul>
<p>显示一个包含输入框的对话框，等待用户输入内容，并在用户点击确定时将输入的字符串返回。如果用户取消了输入，返回null。</p>
<p>该函数也可以作为全局函数使用。</p>
<pre><code>var name = rawInput("请输入您的名字", "小明");
alert("您的名字是" + name);</code></pre>
<p>在ui模式下该函数返回一个<code>Promise</code>。例如:</p>
<pre><code>"ui";
rawInput("请输入您的名字", "小明").then(name => {
alert("您的名字是" + name);
});</code></pre>
<p>当然也可以使用回调函数，例如:</p>
<pre><code>rawInput("请输入您的名字", "小明", name => {
alert("您的名字是" + name);
});</code></pre>
<h2>dialogs.input(title[, prefill, callback])</h2>
<p>等效于 <code>eval(dialogs.rawInput(title, prefill, callback))</code>, 该函数和rawInput的区别在于，会把输入的字符串用eval计算一遍再返回，返回的可能不是字符串。</p>
<p>可以用该函数输入数字、数组等。例如：</p>
<pre><code>var age = dialogs.input("请输入您的年龄", "18");
// new Date().getYear() + 1900 可获取当前年份
var year = new Date().getYear() + 1900 - age;
alert("您的出生年份是" + year);</code></pre>
<p>在ui模式下该函数返回一个<code>Promise</code>。例如:</p>
<pre><code>"ui";
dialogs.input("请输入您的年龄", "18").then(age => {
var year = new Date().getYear() + 1900 - age;
alert("您的出生年份是" + year);
});</code></pre>
<h2>dialogs.prompt(title[, prefill, callback])</h2>
<p>相当于 <code>dialogs.rawInput()</code>;</p>
<h2>dialogs.select(title, items, callback)</h2>
<ul>
<li><code>title</code> {string} 对话框的标题。</li>
<li><code>items</code> {Array} 对话框的选项列表，是一个字符串数组。</li>
<li><code>callback</code> {Function} 回调函数，可选。当用户点击确定时被调用,一般用于ui模式。</li>
</ul>
<p>显示一个带有选项列表的对话框，等待用户选择，返回用户选择的选项索引(0 ~ item.length - 1)。如果用户取消了选择，返回-1。</p>
<pre><code>var options = ["选项A", "选项B", "选项C", "选项D"]
var i = dialogs.select("请选择一个选项", options);
if(i >= 0){
toast("您选择的是" + options[i]);
}else{
toast("您取消了选择");
}</code></pre>
<p>在ui模式下该函数返回一个<code>Promise</code>。例如:</p>
<pre><code>"ui";
dialogs.select("请选择一个选项", ["选项A", "选项B", "选项C", "选项D"])
.then(i => {
toast(i);
});</code></pre>
<h2>dialogs.singleChoice(title, items[, index, callback])</h2>
<ul>
<li><code>title</code> {string} 对话框的标题。</li>
<li><code>items</code> {Array} 对话框的选项列表，是一个字符串数组。</li>
<li><code>index</code> {number} 对话框的初始选项的位置，默认为0。</li>
<li><code>callback</code> {Function} 回调函数，可选。当用户点击确定时被调用,一般用于ui模式。</li>
</ul>
<p>显示一个单选列表对话框，等待用户选择，返回用户选择的选项索引(0 ~ item.length - 1)。如果用户取消了选择，返回-1。</p>
<p>在ui模式下该函数返回一个<code>Promise</code>。</p>
<h2>dialogs.multiChoice(title, items[, indices, callback])</h2>
<ul>
<li><code>title</code> {string} 对话框的标题。</li>
<li><code>items</code> {Array} 对话框的选项列表，是一个字符串数组。</li>
<li><code>indices</code> {Array} 选项列表中初始选中的项目索引的数组，默认为空数组。</li>
<li><code>callback</code> {Function} 回调函数，可选。当用户点击确定时被调用,一般用于ui模式。</li>
</ul>
<p>显示一个多选列表对话框，等待用户选择，返回用户选择的选项索引的数组。如果用户取消了选择，返回<code>[]</code>。</p>
<p>在ui模式下该函数返回一个<code>Promise</code>。</p>
<h2>dialogs.build(properties)</h2>
<ul>
<li><code>properties</code> {Object} 对话框属性，用于配置对话框。</li>
<li>返回 {Dialog}</li>
</ul>
<p>创建一个可自定义的对话框，例如：</p>
<pre><code>dialogs.build({
//对话框标题
title: "发现新版本",
//对话框内容
content: "更新日志: 新增了若干了BUG",
//确定键内容
positive: "下载",
//取消键内容
negative: "取消",
//中性键内容
neutral: "到浏览器下载",
//勾选框内容
checkBoxPrompt: "不再提示"
}).on("positive", ()=>{
//监听确定键
toast("开始下载....");
}).on("neutral", ()=>{
//监听中性键
app.openUrl("https://www.autojs.org");
}).on("check", (checked)=>{
//监听勾选框
log(checked);
}).show();</code></pre>
<p>选项properties可供配置的项目为:</p>
<ul>
<li><code>title</code> {string} 对话框标题</li>
<li><code>titleColor</code> {string} | {number} 对话框标题的颜色</li>
<li><code>buttonRippleColor</code> {string} | {number} 对话框按钮的波纹效果颜色</li>
<li><code>icon</code> {string} | {Image} 对话框的图标，是一个URL或者图片对象 </li>
<li><code>content</code> {string} 对话框文字内容 </li>
<li><code>contentColor</code>{string} | {number} 对话框文字内容的颜色</li>
<li><code>contentLineSpacing</code>{number} 对话框文字内容的行高倍数，1.0为一倍行高</li>
<li><code>items</code> {Array} 对话框列表的选项</li>
<li><code>itemsColor</code> {string} | {number} 对话框列表的选项的文字颜色</li>
<li><code>itemsSelectMode</code> {string} 对话框列表的选项选择模式，可以为:
<ul>
<li><code>select</code> 普通选择模式</li>
<li><code>single</code> 单选模式</li>
<li><code>multi</code> 多选模式</li>
</ul></li>
<li><code>itemsSelectedIndex</code> {number} | {Array} 对话框列表中预先选中的项目索引，如果是单选模式为一个索引；多选模式则为数组</li>
<li><code>positive</code> {string} 对话框确定按钮的文字内容(最右边按钮)</li>
<li><code>positiveColor</code> {string} | {number} 对话框确定按钮的文字颜色(最右边按钮)</li>
<li><code>neutral</code> {string} 对话框中立按钮的文字内容(最左边按钮)</li>
<li><code>neutralColor</code> {string} | {number} 对话框中立按钮的文字颜色(最左边按钮)</li>
<li><code>negative</code> {string} 对话框取消按钮的文字内容(确定按钮左边的按钮)</li>
<li><code>negativeColor</code> {string} | {number} 对话框取消按钮的文字颜色(确定按钮左边的按钮)</li>
<li><code>checkBoxPrompt</code> {string} 勾选框文字内容</li>
<li><code>checkBoxChecked</code> {boolean} 勾选框是否勾选 </li>
<li><code>progress</code> {Object} 配置对话框进度条的对象：
<ul>
<li><code>max</code> {number} 进度条的最大值，如果为-1则为无限循环的进度条</li>
<li><code>horizontal</code> {boolean} 如果为true, 则对话框无限循环的进度条为水平进度条</li>
<li><code>showMinMax</code> {boolean} 是否显示进度条的最大值和最小值</li>
</ul></li>
<li><code>cancelable</code> {boolean} 对话框是否可取消，如果为false，则对话框只能用代码手动取消</li>
<li><code>canceledOnTouchOutside</code> {boolean} 对话框是否在点击对话框以外区域时自动取消，默认为true</li>
<li><code>inputHint</code> {string} 对话框的输入框的输入提示</li>
<li><code>inputPrefill</code> {string} 对话框输入框的默认输入内容</li>
</ul>
<p>通过这些选项可以自定义一个对话框，并通过监听返回的Dialog对象的按键、输入事件来实现交互。下面是一些例子。</p>
<p>模拟alert对话框：</p>
<pre><code>dialogs.build({
title: "你好",
content: "今天也要元气满满哦",
positive: "好的"
}).show();</code></pre>
<p>模拟confirm对话框:</p>
<pre><code>dialogs.build({
title: "你好",
content: "请问你是笨蛋吗?",
positive: "是的",
negative: "我是大笨蛋"
}).on("positive", ()=>{
alert("哈哈哈笨蛋");
}).on("negative", ()=>{
alert("哈哈哈大笨蛋");
}).show();</code></pre>
<p>模拟单选框:</p>
<pre><code>dialogs.build({
title: "单选",
items: ["选项1", "选项2", "选项3", "选项4"],
itemsSelectMode: "single",
itemsSelectedIndex: 3
}).on("single_choice", (index, item)=>{
toast("您选择的是" + item);
}).show();</code></pre>
<p>"处理中"对话框:</p>
<pre><code>var d = dialogs.build({
title: "下载中...",
progress: {
max: -1
},
cancelable: false
}).show();
setTimeout(()=>{
d.dismiss();
}, 3000);</code></pre>
<p>输入对话框:</p>
<pre><code>dialogs.build({
title: "请输入您的年龄",
inputPrefill: "18"
}).on("input", (input)=>{
var age = parseInt(input);
toastLog(age);
}).show();</code></pre>
<p>使用这个函数来构造对话框，一个明显的不同是需要使用回调函数而不能像dialogs其他函数一样同步地返回结果；但也可以通过threads模块的方法来实现。例如显示一个输入框并获取输入结果为：</p>
<pre><code>var input = threads.disposable();
dialogas.build({
title: "请输入您的年龄",
inputPrefill: "18"
}).on("input", text => {
input.setAndNotify(text);
}).show();
var age = parseInt(input.blockedGet());
tosatLog(age);</code></pre>
<h1>Dialog</h1>
<p><code>dialogs.build()</code>返回的对话框对象，内置一些事件用于响应用户的交互，也可以获取对话框的状态和信息。</p>
<h2>事件: <code>show</code></h2>
<ul>
<li><code>dialog</code> {Dialog} 对话框</li>
</ul>
<p>对话框显示时会触发的事件。例如：</p>
<pre><code>dialogs.build({
title: "标题"
}).on("show", (dialog)=>{
toast("对话框显示了");
}).show();</code></pre>
<h2>事件: <code>cancel</code></h2>
<ul>
<li><code>dialog</code> {Dialog} 对话框</li>
</ul>
<p>对话框被取消时会触发的事件。一个对话框可能按取消按钮、返回键取消或者点击对话框以外区域取消。例如：</p>
<pre><code>dialogs.build({
title: "标题",
positive: "确定",
negative: "取消"
}).on("cancel", (dialog)=>{
toast("对话框取消了");
}).show();</code></pre>
<h2>事件: <code>dismiss</code></h2>
<ul>
<li><code>dialog</code> {Dialog} 对话框</li>
</ul>
<p>对话框消失时会触发的事件。对话框被取消或者手动调用<code>dialog.dismiss()</code>函数都会触发该事件。例如：</p>
<pre><code>var d = dialogs.build({
title: "标题",
positive: "确定",
negative: "取消"
}).on("dismiss", (dialog)=>{
toast("对话框消失了");
}).show();
setTimeout(()=>{
d.dismiss();
}, 5000);</code></pre>
<h2>事件: <code>positive</code></h2>
<ul>
<li><code>dialog</code> {Dialog} 对话框</li>
</ul>
<p>确定按钮按下时触发的事件。例如：</p>
<pre><code>var d = dialogs.build({
title: "标题",
positive: "确定",
negative: "取消"
}).on("positive", (dialog)=>{
toast("你点击了确定");
}).show();</code></pre>
<h2>事件: <code>negative</code></h2>
<ul>
<li><code>dialog</code> {Dialog} 对话框</li>
</ul>
<p>取消按钮按下时触发的事件。例如：</p>
<pre><code>var d = dialogs.build({
title: "标题",
positive: "确定",
negative: "取消"
}).on("negative", (dialog)=>{
toast("你点击了取消");
}).show();</code></pre>
<h2>事件: <code>neutral</code></h2>
<ul>
<li><code>dialog</code> {Dialog} 对话框</li>
</ul>
<p>中性按钮按下时触发的事件。例如：</p>
<pre><code>var d = dialogs.build({
title: "标题",
positive: "确定",
negative: "取消",
neutral: "稍后提示"
}).on("positive", (dialog)=>{
toast("你点击了稍后提示");
}).show();</code></pre>
<h2>事件: <code>any</code></h2>
<ul>
<li><code>dialog</code> {Dialog} 对话框</li>
<li><code>action</code> {string} 被点击的按钮，可能的值为:
<ul>
<li><code>positive</code> 确定按钮 </li>
<li><code>negative</code> 取消按钮</li>
<li><code>neutral</code> 中性按钮</li>
</ul></li>
</ul>
<p>任意按钮按下时触发的事件。例如:</p>
<pre><code>var d = dialogs.build({
title: "标题",
positive: "确定",
negative: "取消",
neutral: "稍后提示"
}).on("any", (action, dialog)=>{
if(action == "positive"){
toast("你点击了确定");
}else if(action == "negative"){
toast("你点击了取消");
}
}).show();</code></pre>
<h2>事件: <code>item_select</code></h2>
<ul>
<li><code>index</code> {number} 被选中的项目索引，从0开始</li>
<li><code>item</code> {Object} 被选中的项目</li>
<li><code>dialog</code> {Dialog} 对话框</li>
</ul>
<p>对话框列表(itemsSelectMode为"select")的项目被点击选中时触发的事件。例如：</p>
<pre><code>var d = dialogs.build({
title: "请选择",
positive: "确定",
negative: "取消",
items: ["A", "B", "C", "D"],
itemsSelectMode: "select"
}).on("item_select", (index, item, dialog)=>{
toast("您选择的是第" + (index + 1) + "项, 选项为" + item);
}).show();</code></pre>
<h2>事件: <code>single_choice</code></h2>
<ul>
<li><code>index</code> {number} 被选中的项目索引，从0开始</li>
<li><code>item</code> {Object} 被选中的项目</li>
<li><code>dialog</code> {Dialog} 对话框</li>
</ul>
<p>对话框单选列表(itemsSelectMode为"singleChoice")的项目被选中并点击确定时触发的事件。例如：</p>
<pre><code>var d = dialogs.build({
title: "请选择",
positive: "确定",
negative: "取消",
items: ["A", "B", "C", "D"],
itemsSelectMode: "singleChoice"
}).on("item_select", (index, item, dialog)=>{
toast("您选择的是第" + (index + 1) + "项, 选项为" + item);
}).show();</code></pre>
<h2>事件: <code>multi_choice</code></h2>
<ul>
<li><code>indices</code> {Array} 被选中的项目的索引的数组</li>
<li><code>items</code> {Array} 被选中的项目的数组</li>
<li><code>dialog</code> {Dialog} 对话框</li>
</ul>
<p>对话框多选列表(itemsSelectMode为"multiChoice")的项目被选中并点击确定时触发的事件。例如：</p>
<pre><code>var d = dialogs.build({
title: "请选择",
positive: "确定",
negative: "取消",
items: ["A", "B", "C", "D"],
itemsSelectMode: "multiChoice"
}).on("item_select", (indices, items, dialog)=>{
toast(util.format("您选择的项目为%o, 选项为%o", indices, items);
}).show();</code></pre>
<h2>事件: <code>input</code></h2>
<ul>
<li><code>text</code> {string} 输入框的内容</li>
<li><code>dialog</code> {Dialog} 对话框</li>
</ul>
<p>带有输入框的对话框当点击确定时会触发的事件。例如：</p>
<pre><code>dialogs.build({
title: "请输入",
positive: "确定",
negative: "取消",
inputPrefill: ""
}).on("input", (text, dialog)=>{
toast("你输入的是" + text);
}).show();</code></pre>
<h2>事件: <code>input_change</code></h2>
<ul>
<li><code>text</code> {string} 输入框的内容</li>
<li><code>dialog</code> {Dialog} 对话框</li>
</ul>
<p>对话框的输入框的文本发生变化时会触发的事件。例如：</p>
<pre><code>dialogs.build({
title: "请输入",
positive: "确定",
negative: "取消",
inputPrefill: ""
}).on("input_change", (text, dialog)=>{
toast("你输入的是" + text);
}).show();</code></pre>
<h2>dialog.getProgress()</h2>
<ul>
<li>返回 {number}</li>
</ul>
<p>获取当前进度条的进度值，是一个整数</p>
<h2>dialog.getMaxProgress()</h2>
<ul>
<li>返回 {number}</li>
</ul>
<p>获取当前进度条的最大进度值，是一个整数</p>
<h2>dialog.getActionButton(action)</h2>
<ul>
<li><code>action</code> {string} 动作，包括:
<ul>
<li><code>positive</code> </li>
<li><code>negative</code></li>
<li><code>neutral</code></li>
</ul></li>
</ul>