GuideDialog_tc

🚩引導對話框 GuideDialog

引導對話框 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)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly