等待框 WaitDialog 和提示框 TipDialog

🌐 View English Document | 繁體中文文檔

⌛等待框 WaitDialog 和提示框 TipDialog

阻断式等待提示框，会显示基础的环形等待动画以及进度展示动画，它是单例的，这就意味着从等待状态 WaitDialog 切换到提示状态 TipDialog 是无缝的，你可以自由的选择在等待结束后显示成功/警告/错误三种状态的消息提示，动画的切换也会无缝衔接。

使用前请注意，等待框 WaitDialog 和提示框 TipDialog的背景是与亮/暗色模式相反的，这是为了突出显示。

显示一个最简单的等待框

使用以下代码显示一个等待框：

WaitDialog.show("Please Wait!");

如果设置了全局的默认等待提示框文本，甚至可以直接启动：

WaitDialog.showWaitWithDefaultText();

WaitDialog 在显示后会持续运行，直到弹出一个提示框 TipDialog 或者使用.dismiss()方法关闭它。

以下是一个最简单的例子，程序会在运行 2 秒后自动关闭 WaitDialog：

WaitDialog.show("Please Wait!");
new Handler(Looper.getMainLooper()).postDelayed(new Runnable() {
    @Override
    public void run() {
        WaitDialog.dismiss();
    }
}, 2000);

若要修改已经显示的 WaitDialog 的文字，可以直接重新执行 WaitDialog.show("其他文字"); 即可。

显示一个最简单的提示框

提示框 TipDialog 分为三种样式，完成（SUCCESS）、警告（WARNING）和错误（ERROR）

TipDialog 实际上是 WaitDialog 的代理类，WaitDialog 在启动后至关闭前都只会有一个实例，因此在 WaitDialog 显示过程中执行 TipDialog 就会中断等待框的显示，转而衔接显示一个提示框，除此之外，TipDialog 也可以单独执行显示。

提示框的衔接是有线条动画效果的，若 WaitDialog 正在显示时，在执行 TipDialog 的显示指令后不一定会立即显示提示框，可能会等待动画可以衔接时才会转而显示 TipDialog。

使用以下代码显示一个完成等待框：

TipDialog.show("Success!", WaitDialog.TYPE.SUCCESS);

如果设置了全局的默认提示框文本，甚至可以直接启动：

TipDialog.showTipWithDefaultText(WaitDialog.TYPE.SUCCESS);

另有警告框和错误框状态可选：

//警告
TipDialog.show("Warning!", WaitDialog.TYPE.WARNING);
//错误
TipDialog.show("Error!", WaitDialog.TYPE.ERROR);

提示框默认在显示 1.5 秒后会自动消失，你可以通过以下方法来自定义显示时间（毫秒）：

TipDialog.show("Success!", WaitDialog.TYPE.SUCCESS, 3500);

显示一个进度提示框

进度提示可以以一个圆环为表现可视化展示当前的流程进度。

因为准确度要求，进度提示开始时不会有过渡动画。

使用以下代码显示一个进度框：

WaitDialog.show("正在加载...", 0.1f);

第二个浮点型的参数即进度，取值范围为0f ~ 1f，会由上一个进度平滑过渡到下一个设定的进度，也可以反向进行进行减少。

🚧 实现传统的进度条对话框

要显示一个传统的对话框进度条（例如下载更新的场景），请参阅 《常见问题：Q：如何实现传统的进度条对话框？》

生命周期回调

等待框 WaitDialog 和提示框 TipDialog 可以通过设置 .setDialogLifecycleCallback(...) 设置生命周期事件回调：

TipDialog.show("Success!", WaitDialog.TYPE.SUCCESS)
        .setDialogLifecycleCallback(new DialogLifecycleCallback<WaitDialog>() {
    @Override
    public void onShow(WaitDialog dialog) {
        //对话框启动时回调
    }
    @Override
    public void onDismiss(WaitDialog dialog) {
        //对话框关闭时回调
    }
});

WaitDialog/TipDialog 也支持 Lifecycle，你可以使用 .getLifecycle() 获取 Lifecycle 对象。

WaitDialog.show("please wait...")
        .onShow(new DialogXRunnable<WaitDialog>() {
            @Override
            public void run(WaitDialog dialog) {
                //WaitDialog show!
            }
        })
        .onDismiss(new DialogXRunnable<WaitDialog>() {
            @Override
            public void run(WaitDialog dialog) {
                //WaitDialog dismiss!
            }
        });

返回按键监听

等待框 WaitDialog 和提示框 TipDialog 可以通过设置 .setDialogLifecycleCallback(...) 设置当用户按下系统返回键时的事件处理：

WaitDialog.show("Please Wait!").setOnBackPressedListener(new OnBackPressedListener() {
    @Override
    public boolean onBackPressed() {
        toast("按下返回");
        return false;
    }
});

从上述代码可以看到onBackPressed()方法是有一个回调值，当return true时可以自动关闭等待/提示对话框。

自定义布局

WaitDialog 和 TipDialog 也支持自定义布局样式，使用方式与基本消息对话框相同：

WaitDialog.show("Please Wait!").setCustomView(new OnBindView<WaitDialog>(R.layout.layout_custom_view) {
            @Override
            public void onBind(WaitDialog dialog, View v) {
            
            }
        });

在启用自定义布局后，WaitDialog 和 TipDialog 自身的动画布局将会隐藏。

自定义进入和关闭动画

针对单次显示的对话框动画修改，可使用以下方法进行自定义：

WaitDialog.show("请稍后...")
        //设置入场动画资源和出场动画资源
        .setAnimResId(R.anim.anim_dialogx_bottom_enter, R.anim.anim_dialogx_bottom_exit);

要自定义动画文件，可以参考：默认对话框启动动画文件和默认对话框关闭动画文件

额外说明，除了 .setAnimResId(enterAnimResId, exitAnimResId) 外，还有 .setEnterAnimResId(enterAnimResId) 和 .setExitAnimResId(enterAnimResId) 单独方法可选，此方法仅针对单次显示的对话框有效。

另外你也可以通过 setEnterAnimDuration([long]) 设置入场动画时长以及通过 .setExitAnimDuration([long]) 设置关闭动画时长。

对 WaitDialog、TipDialog 全局生效的的动画修改：

你可以通过静态属性直接修改全局 WaitDialog 的动画：

//设置全局 PopTip入场动画
WaitDialog.overrideEnterAnimRes = R.anim.anim_dialogx_bottom_enter;
//设置全局 PopTip出场动画
WaitDialog.overrideExitAnimRes = R.anim.anim_dialogx_bottom_exit;
//设置全局 PopTip入场动画时间
WaitDialog.overrideEnterDuration = 1000;
//设置全局 PopTip出场动画时间
WaitDialog.overrideExitDuration = 1000;

通过自定义主题修改

您还可以通过参考自定义主题接口，完全定制全局的动画框默认动画效果，具体请查阅 《自定义 DialogX 主题》

请注意这三种设置是由优先级区别的，针对单次显示的对话框动画修改优先级 ＞ 对 WaitDialog、TipDialog 全局生效的的动画修改 ＞ 自定义主题修改。

其他额外方法

//强制重新刷新界面
.refreshUI();

//关闭对话框
.dismiss();

//获取对话框实例化对象，您可以通过此方法更深度的定制Dialog的功能
.getDialogImpl()

//获取自定义布局实例
.getCustomView()
    
//设置背景颜色，强行对对话框背景进行染色，请注意参数为int类型的颜色值而非R.color的索引
.setBackgroundColor(ColorInt);

//设置对话框圆角（会裁切内容显示）
.setRadius(float px)

//是否处于显示状态
.isShow()

//置顶对话框
.bringToFront()

//指定对话框显示层级
.setThisOrderIndex(int)

TipDialog 在展示提示时会有振动反馈，受以下属性控制影响：

//使用振动反馈
DialogX.useHaptic = true;

背景遮罩

WaitDialog 支持修改背景遮罩，这是为了丰富扩展性。如果需要背景遮罩，您可以自行使用如下代码设置：

WaitDialog.show(...).setMaskColor(colorInt);

请注意，传入参数为 ColorInt 值，您可以使用 Color.parseColor("#4D000000") 设置一个 HEX 色值，或使用 getResources().getColor(R.color.black30) 设置一个颜色的资源值。

动画衔接

默认情况下，使用 Material 动画的主题时，从 等待状态 到 提示状态（完成、警告、错误） 是需要等待一段时间以完成动画的衔接，最大时长取决于当前等待动画转到的进度，如果需要去掉动画衔接效果，以达到快速响应，您可以使用 NoArticulatedProgressView 来实现对默认等待提示动画的替换：

在您设置 DialogX 的主题时，请重写 overrideWaitTipRes 相关设置：

DialogX.globalStyle = new MaterialStyle(){
    @Override
    public WaitTipRes overrideWaitTipRes() {
        return new WaitTipRes() {
            @Override
            public ProgressViewInterface overrideWaitView(Context context, boolean light) {
                return new NoArticulatedProgressView(context);  //重要！
            }
        };
    }
};

NoArticulatedProgressView 是自带组件，只需要引入 import com.kongzue.dialogx.util.views.NoArticulatedProgressView; 即可