引导对话框 GuideDialog

🌐 View English Document | 繁體中文文檔

🚩引导对话框 GuideDialog

可以实现一个遮罩展示操作引导图，或者对按钮进行操作提示指引。

GuideDialog 可以围绕一个界面上的组件显示，并实现舞台光的效果，舞台光可选圆形（外围、内侧）、方形（外围、内侧）和矩形模式，方形和矩形可设置圆角。

显示一个简单引导对话框

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

自定义图片支持资源图（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();

使用 ViewBinding 的话也可以更换为 OnBindingView 来实现直接通过 binding 获取布局实例：

GuideDialog.show(new OnBindingView<CustomDialog, LayoutCustomViewBinding>() {
            @Override
            public void onBind(CustomDialog dialog, View view, LayoutCustomViewBinding binding) {
                //View childView = binding.childView
            }
        });

指定 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()方法构建对话框进行设置。

生命周期回调

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

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

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

你也可以通过使用 new 构建实例时，override 的生命周期事件的方式来处理生命周期事务，例如：

//复写事件演示
new GuideDialog() {
    @Override
    public void onShow(GuideDialog dialog) {
        //...
        tip("onShow");
    }
    @Override
    public void onDismiss(GuideDialog dialog) {
        //...
        tip("onDismiss");
    }
}

你也可以使用方法 .onShow(DialogXRunnable) 和 .onDismiss(DialogXRunnable)，来处理生命周期事务，例如：

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

其他额外方法

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

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

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

//获取自定义布局实例
.getCustomView()
    
//设置对话框宽度
.setWidth(px)
    
//设置对话框高度
.setHeight(px)

//隐藏对话框（无动画），恢复显示请执行非静态方法的 .show()
.hide();

//隐藏对话框（模拟关闭对话框的动画），恢复显示请执行非静态方法的 .show()
.hideWithExitAnim();

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

//置顶对话框
.bringToFront()

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