NativeScript Dialogs 模块完全指南：Alert、Confirm、Prompt、Login 与 Action 五种对话框实战

本指南以 NativeScript 官方自动化测试工程中的 dialogs.md 文档为主体，系统讲解@nativescript/core中ui/dialogs模块的五大对话框 API：action、confirm、alert、login与prompt。读完本文，你将掌握每种对话框的完整配置参数、Promise 返回值语义、平台差异（iOS/Android）以及底层实现原理，可直接在真实项目中复制使用。

模块引入与基本用法

显示对话框需要引入ui/dialogs模块。在 NativeScript 中，推荐通过核心包统一入口导入，自动化测试工程中的写法如下（见 dialog-tests.ts）：

import { Dialogs, PromptResult, LoginResult, inputType } from '@nativescript/core';

Dialogs是模块提供的一个聚合对象（rollup），内部将alert、confirm、prompt、login、action五个方法统一封装，便于以Dialogs.xxx(...)形式调用。其类型声明位于 index.d.ts，Android 端实现位于 index.android.ts。

所有对话框 API 均返回 Promise，你可以用.then()链式处理结果，也可以用async/await等待用户交互完成。官方文档（dialogs.md）将五种用法逐一列出，下文逐个展开。

Action：让用户在多个选项中做出选择

action用于向用户展示一个可选择的动作列表，返回用户选中的动作文本（Promise<string>）。测试工程中的标准示例（dialog-tests.ts）：

var options = { title: 'Race Selection', message: 'Choose your race', cancelButtonText: 'Cancel', actions: ['Human', 'Elf', 'Dwarf', 'Orc'], }; Dialogs.action(options).then((result) => { console.log(result); });

ActionOptions的完整字段（定义于 dialogs-common.ts）：

action也支持简化调用形式（见 index.d.ts）：action(message, cancelButtonText, actions)。

返回值语义：选中某个动作时 resolve 该动作的文本；点击取消按钮或通过返回键/点击外部关闭时，resolvecancelButtonText指定的文本。从 Android 源码看，用户点击动作项时会回调resolve(options.actions[which])，点击取消按钮时 resolveoptions.cancelButtonText，而对话框被 dismiss（例如点击外部区域）时也会 resolve 取消文案（index.android.ts），因此可以通过比较返回值是否等于取消文案来判断用户是否真正做出了选择。

Confirm：向用户确认一个决定

confirm展示确认对话框，返回Promise<boolean>。注意返回值存在三种状态：true（点击 OK）、false（点击 Cancel 或被取消）、undefined（点击中性按钮）。测试示例（dialog-tests.ts）：

var options = { title: 'Race Selection', message: 'Are you sure you want to be an Elf?', okButtonText: 'Yes', cancelButtonText: 'No', neutralButtonText: 'Cancel', }; Dialogs.confirm(options).then((result: boolean) => { // result can be true/false/undefined console.log(result); });

ConfirmOptions在AlertOptions基础上扩展（dialogs-common.ts）：

三态返回值的底层来源：Android 实现中，OK 按钮回调callback(true)，Cancel 按钮回调callback(false)，中性按钮回调callback(undefined)，而对话框被 dismiss 时默认回调callback(false)（index.android.ts）。所以在业务逻辑中，undefined通常代表用户点了"不确定/稍后再说"的中性按钮，需要单独分支处理。

Alert：最简单的消息提示

alert展示一个仅含 OK 按钮的消息框，返回Promise<void>。测试示例（dialog-tests.ts）：

var options = { title: 'Race Selection', message: 'Race Chosen: Elf', okButtonText: 'OK', }; Dialogs.alert(options).then(() => { console.log('Race Chosen!'); });

AlertOptions字段（dialogs-common.ts）为title、message、okButtonText。alert也接受字符串、数字或布尔值作为快捷参数（index.d.ts），例如Dialogs.alert('Some message')，此时底层会自动补全默认标题Alert与 OK 文案（index.android.ts）。

平台差异：Android 端alert在点击 OK 或对话框被 dismiss 时都会 resolve（index.android.ts），因此无需担心用户通过返回键关闭导致 Promise 永不完成。

Login：采集用户名与密码

login展示包含用户名、密码两个输入框的登录对话框，返回Promise<LoginResult>。测试示例（dialog-tests.ts）：

var options = { title: 'Login', message: 'Login', username: 'john_doe', password: '', }; Dialogs.login(options).then((loginResult: LoginResult) => { // true or false. console.log(loginResult.result); });

注意示例中选项字段为username/password（预填文本），而LoginOptions还支持userNameHint/passwordHint作为输入框的 placeholder 提示（dialogs-common.ts）：

LoginResult结构（dialogs-common.ts）：

interface LoginResult { result: boolean; // true=确认，false=取消，undefined=中性按钮 userName: string; // 用户输入的用户名 password: string; // 用户输入的密码 }

典型分支处理（源自官方模块文档 Readme.md 的示例）：result === true时执行登录逻辑；result === false时处理取消；result === undefined时可处理"注册新账号"之类的中性路径。密码输入框在 Android 端使用TYPE_TEXT_VARIATION_PASSWORD掩码显示（index.android.ts），保证输入内容不可见。

Prompt：带输入框的提问

prompt展示带文本输入框的对话框，返回Promise<PromptResult>，其中result为布尔结果、text为用户输入的内容。测试示例（dialog-tests.ts）：

var options = { title: 'Name', defaultText: 'Enter your name', inputType: inputType.text, }; Dialogs.prompt(options).then((result: PromptResult) => { console.log('Hello, ' + result.text); });

PromptOptions在ConfirmOptions基础上增加三个字段（dialogs-common.ts）：

inputType枚举（dialogs-common.ts）：text（纯文本）、password（密码）、email（邮箱）、number（数字）、decimal（小数）、phone（电话）。

capitalizationType枚举（dialogs-common.ts）：none（不自动大写）、all（全部大写）、sentences（句首大写）、words（每个单词首字母大写）。

Android 实现要点：底层会创建EditText并依据inputType映射到对应的android.text.InputType标志位——例如password映射为TYPE_CLASS_TEXT | TYPE_TEXT_VARIATION_PASSWORD，email映射为TYPE_CLASS_TEXT | TYPE_TEXT_VARIATION_EMAIL_ADDRESS，number映射为TYPE_CLASS_NUMBER，decimal追加TYPE_NUMBER_FLAG_DECIMAL，phone映射为TYPE_CLASS_PHONE；capitalizationType则通过追加TYPE_TEXT_FLAG_CAP_CHARACTERS、CAP_SENTENCES、CAP_WORDS标志实现（index.android.ts）。

源码级原理：跨平台对话框如何工作

ui/dialogs模块采用"公共定义 + 平台实现"的架构：

• 公共层dialogs-common.ts：定义全部选项/结果接口、inputType与capitalizationType枚举、字符串常量（DialogStrings），以及parseLoginOptions等参数归一化函数。
• Android 实现index.android.ts：基于android.app.AlertDialog.Builder构建原生对话框。
• iOS 实现index.ios.ts：基于UIAlertController实现，支持destructiveActionsIndexes等 iOS 专属能力。
• 类型声明index.d.ts：提供各方法的重载签名与完整类型信息。

几个值得注意的底层细节：

1. 参数归一化：Android 端通过isDialogOptions(arg)（判断参数是否含message或title）来区分"传字符串"与"传选项对象"两种调用方式，字符串会被自动包装为带默认标题/按钮文案的选项对象（dialogs-common.ts）。
2. 样式继承：对话框会读取当前页面的_styleScope，通过applySelectors将 CSS 类ns-dialog-item应用于内部的 Button、Label、TextField，从而让.ns-dialog-item的 CSS 规则作用于对话框内的控件（标题文字、消息文字、按钮文字与背景色），实现对话框外观随应用主题变化（dialogs-common.ts）。Android 端showDialog正是利用getLabelColor()与getButtonColors()的返回值去设置AlertDialog内部 TextView 与 Button 的颜色（index.android.ts）。
3. 按钮映射：Android 端将okButtonText映射为setPositiveButton、cancelButtonText映射为setNegativeButton、neutralButtonText映射为setNeutralButton（index.android.ts），这也是 confirm 返回值三态（true/false/undefined）的直接来源。

其他调用形式与进阶提示

除了选项对象，所有对话框 API 均保留简化的位置参数形式，官方模块文档 Readme.md 给出了历史用法示例：

// 字符串快捷调用 Dialogs.alert('Some message'); Dialogs.confirm('Some question?').then((r) => { /* r: boolean */ }); // prompt 的 message + defaultText 形式 Dialogs.prompt('Some message', 'Default text for the input', { title: 'My custom title', okButtonText: 'Yes', cancelButtonText: 'No', neutralButtonText: 'Not sure', inputType: 'password', }).then((r) => { console.log('Boolean result: ' + r.result + ', entered text: ' + r.text); }); // login 的位置参数形式：message, userNameHint, passwordHint, userName, password Dialogs.login('Enter your user name and password:', '', '', { title: 'Login', okButtonText: 'Sign In', cancelButtonText: 'Cancel', neutralButtonText: 'Sign Up', }).then((r) => { if (r.result) { // 执行登录 } else if (r.result === false) { // 用户取消 } else { // 用户点击了中性按钮 } });

parseLoginOptions正是为兼容这种多参数调用而存在：当只传一个对象参数时原样返回，否则按位置依次提取message、userNameHint、passwordHint、userName、password，并补全默认标题Login、OK/Cancel 文案（dialogs-common.ts）。

实战建议：

• 在页面事件（如按钮点击）中调用对话框 API，配合async/await让交互流程更易读；
• 对 confirm/login/prompt 的三态返回值（true/false/undefined）都要有明确分支，尤其是undefined（中性按钮）场景；
• 如需在 Android 上控制"点击外部关闭"，显式设置cancelable: false；
• 对话框文字样式可通过全局 CSS 类ns-dialog-item统一定制。

你可以在仓库的自动化测试文件 dialog-tests.ts 中看到上述五种对话框的完整可运行示例，在 dialogs-common.ts、index.android.ts 与 index.ios.ts 中深入阅读各平台的实现细节。