使用 DialogX 轻松实现应用操作引导

在功能复杂时时长需要制作引导提示来指引用户进行操作，引导提示一般又分为非关联引导（提示图）以及关联到界面上固定布局的引导提示，此时要实现在各分辨率下都能精准指引的提示效果就是件麻烦事了，DialogX 新增的 GuideDialog 可以轻松完成这个操作。

如何使用

1. 在 project 的 build.gradle 文件中找到 allprojects{} 代码块添加以下代码：

allprojects {
    repositories {
        google()
        jcenter()
        maven { url 'https://jitpack.io' }      //增加 jitPack Maven 仓库
    }
}

⚠️请注意，使用 Android Studio 北极狐版本（Arctic Fox）创建的项目，需要您前往 settings.gradle 添加上述 jitpack 仓库配置。

1. 在 app 的 build.gradle 文件中找到 dependencies{} 代码块，并在其中加入以下语句：

def dialogx_version = "0.0.46.beta8"
implementation "com.github.kongzue.DialogX:DialogX:${dialogx_version}"

显示一个简单引导对话框

首先准备一个自定义引导图或自定义布局，然后使用以下代码显示一个引导对话框：

自定义图片支持资源图（redId）、Drawable 或位图（Bitmap）。

//使用自定义图片
GuideDialog.show(R.mipmap.img_guide_tip);
​
//使用自定义布局
GuideDialog.show(new OnBindView<CustomDialog>(R.layout.layout_custom_dialog) {
    @Override
    public void onBind(final CustomDialog dialog, View v) {
        ImageView btnOk;
        btnOk = v.findViewById(R.id.btn_ok);
        btnOk.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View v) {
                dialog.dismiss();
            }
        });
    }
});

你也可以使用 build() 方法构建 CustomDialog：

GuideDialog.build()
        .setTipImage(R.mipmap.img_guide_tip)
        .show();

指定 GuideDialog 基于一个布局显示

要基于界面上已经存在的布局对用户进行引导，请在显示 GuideDialog 时绑定布局：

//view 即需要 GuideDialog 绑定的布局
GuideDialog.show(view, R.mipmap.img_tip_login);

绑定布局后，默认会使用“舞台光”效果照亮绑定的布局位置，舞台光效果支持以下模式：

STAGE_LIGHT_TYPE 类型	介绍	图例
RECTANGLE	基于绑定布局外围显示矩形舞台光
SQUARE_OUTSIDE	基于绑定布局外围显示正方形舞台光
SQUARE_INSIDE	基于绑定布局内围显示正方形舞台光
CIRCLE_OUTSIDE	基于绑定布局外围显示圆形舞台光
CIRCLE_INSIDE	基于绑定布局内围显示圆形舞台光

然后使用代码设置：

//在启动方法指定
GuideDialog.show(btnFullScreenDialogLogin, GuideDialog.STAGE_LIGHT_TYPE.CIRCLE_OUTSIDE, R.mipmap.img_tip_login);
​
//使用 set 方法指定
GuideDialog.show(btnFullScreenDialogLogin, R.mipmap.img_tip_login)
        .setStageLightType(GuideDialog.STAGE_LIGHT_TYPE.CIRCLE_OUTSIDE);

当使用矩形 RECTANGLE 和方形 SQUARE_* 时可以指定圆角，方法为：

.setStageLightFilletRadius(15)  //设置圆角，单位像素

引导图、引导布局选项

GuideDialog 的引导图/布局是指提供引导提示的部分，可以单独显示，也可以围绕绑定的布局上下左右显示。

使用引导图时，可以指定资源图（redId）、Drawable 或位图（Bitmap），除了静态方法启动对话框外也可以单独指定：

GuideDialog.build()
        .setCustomView(new OnBindView(...))     //指定引导布局
        .setTipImage(...)   //指定引导图

请注意，引导图和引导布局只能选其一，使用引导布局时引导图将不生效。

绑定引导布局时

可以使 GuideDialog 围绕绑定布局的周围显示：

//在启动方法指定
GuideDialog.show(btnFullScreenDialogLogin, R.mipmap.img_tip_login, Gravity.BOTTOM|Gravity.CENTER_HORIZONTAL);
​
//使用 set 方法指定
GuideDialog.build()
        .setAlignBaseViewGravity(Gravity.BOTTOM | Gravity.CENTER_HORIZONTAL);

还可以设置引导图/布局距离绑定布局的间距：

//指定引导图/布局和绑定布局之间的左上右下的间距（单位：像素）
.setBaseViewMargin(left, top, right, bottom)
.setBaseViewMargin(new int[]{left, top, right, bottom})
    
//仅单独指定上间距
.setBaseViewMarginTop(-dip2px(30))

不绑定引导布局时

但单独使用引导图/布局且不绑定引导布局时，GuideDialog 和自定义对话框 CustomDialog 功能基本一致，可以设置 Align 来修改 GuideDialog 的启动方式：

GuideDialog.show(...)
    .setAlign(ALIGN.TOP);

ALIGN 是一个枚举，其值定义如下：

CENTER          中央显示（默认）
TOP         顶部显示（等同于顶部中央）
TOP_CENTER      顶部中央显示
TOP_LEFT        顶部左侧显示
TOP_RIGHT       顶部右侧显示
BOTTOM          底部显示（等同于底部中央）
BOTTOM_CENTER       底部中央显示
BOTTOM_LEFT     底部左侧显示
BOTTOM_RIGHT        底部右侧显示
LEFT            左侧显示（等同于左侧中央）
LEFT_CENTER     左侧中央显示
LEFT_TOP        左侧上方显示
LEFT_BOTTOM     左侧下方显示
RIGHT           右侧显示（等同于右侧中央）
RIGHT_CENTER        右侧中央显示
RIGHT_TOP       右侧上方显示
RIGHT_BOTTOM        右侧下方显示

请注意： 其中，例如顶部左侧显示 TOP_LEFT 和左侧上方显示 LEFT_TOP 的区别在于入场出场动画方向不一样，顶部左侧显示的动画是从屏幕顶部进入，布局居于屏幕左侧，而左侧上方显示则是动画从屏幕左侧进入，居于上方显示。

您也可以自定义启动/关闭动画，支持使用自定义的 anim 资源文件进行设置：

GuideDialog.build()
    .setCustomView(...)
    .setEnterAnimResId(R.anim.enter_anim)
    .setExitAnimResId(R.anim.exit_anim)
    .show();

或：

GuideDialog.build()
    .setCustomView(...)
    .setAnimResId(R.anim.enter_anim, R.anim.exit_anim)
    .show();

请注意，启动动画必须在对话框启动前设置，即使用build()方法构建对话框进行设置。

引导点击

设置引导绑定布局的位置点击：

.setOnStageLightPathClickListener(new OnDialogButtonClickListener<GuideDialog>() {
    @Override
    public boolean onClick(GuideDialog dialog, View v) {
        toast("点击了原按钮");
        btnCustomDialogAlign.callOnClick();     //调用原按钮点击事件
        return false;
    }
});

设置点击了外围遮罩：

.setOnBackgroundMaskClickListener(new OnBackgroundMaskClickListener<CustomDialog>() {
    @Override
    public boolean onClick(CustomDialog dialog, View v) {
        toast("点击了外围遮罩");
        return false;       //return true可以使对话框无法点击遮罩关闭
    }
})

沉浸式

GuideDialog 默认会开启沉浸式非安全区隔离模式，也就是说，会在根布局设置一个 padding，将顶部状态栏和底部导航栏的无法触控的非安全区位置分离开，保证自定义布局位置一定处于安全区内，但这可能与您使用的沉浸式框架，或者未配置任何沉浸式（即顶部导航栏和底部状态栏都不沉浸式）时产生冲突，导致 GuideDialog 在使用顶部显示/底部显示时额外空出一部分区域，此时您可以使用以下设置关闭沉浸式 padding：

GuideDialog.build()
    .setCustomView(...)
    .setAutoUnsafePlacePadding(false)
    .show();

请注意，setAutoUnsafePlacePadding(Boolean) 必须在对话框启动前设置，即使用build()方法构建对话框进行设置。

生命周期回调

想要监控对话框的生命周期，可以实现其 接口，建议使用build()方法构建对话框：

GuideDialog.build()
        .setDialogLifecycleCallback(new DialogLifecycleCallback<CustomDialog>() {
            @Override
            public void onShow(CustomDialog dialog) {
                //CustomDialog 启动时回调
            }
            @Override
            public void onDismiss(CustomDialog dialog) {
                //CustomDialog 关闭时回调
            }
        })
        .show();

其他额外方法

//强制重新刷新界面
.refreshUI();
​
//关闭对话框
.dismiss();
​
//获取对话框实例化对象，您可以通过此方法更深度的定制Dialog的功能
.getDialogImpl()
​
//获取自定义布局实例
.getCustomView()
    
//设置对话框宽度
.setWidth(px)
    
//设置对话框高度
.setHeight(px)

下载 Demo App 试用

最新的 DialogX Demo App 已经更新并添加 GuideDialog 的范例，也可以优先下载尝试 beta.kongzue.com/DialogXDemo