一行代码实现Android App指引

概述

前几周app改版，在修改老代码的过程中发现了一个指引，让我想起很久以前项目里指引实现是在布局文件中添加布局，并在代码中插入很多非业务的代码，这样写感觉不好。指引本只是一个不太重要，可能经常变动的功能，说不定下个版本又改了，当它和正常业务耦合在一起以后，就显得代码有点混乱了。有没有一种方法，可以无缝嵌入，将指引和正常业务彻底解耦？前几天早晨，几个公众号都发了同样一篇博客来抠个图吧~——更优雅的Android UI界面控件高亮的实现，看到这篇博客的时候有种醍醐灌顶的感觉，这不正是我想要的指引吗？看完博客中的实现原理后，决定动手重复造一个轮子，本文简单分析一下这个轮子是如何实现的，并分析了一下优缺点。下面先看个效果：

指引需求分析

不谈技术实现，首先分析一下指引这个需求本身。

入门级指引

入门级的指引，就是最简单的指引，在app安装新版本或者覆盖安装新版本后第一时间弹出来几张图片。为了突出某些功能，会高亮显示一些内容，同时还有一些指示性的箭头，或者在高亮旁边有文本描述。

升级版指引

升级版指引，在用户第一次进入到个页面的时候，告诉用户哪几个按钮有是做什么的。指引内容和入门级的差不多，高亮显示View，箭头、文本描述，点击高亮View后跑到下一步指引直到指引结束。

指引需求的抽象

简单指引一般由UI切图就好，这里以app内部的指引需求分析指引，如图（图片是随便找的），指引一般包括以下内容：

1. 满屏幕的半透明遮罩层；
2. 高亮显示突出显示底层app页面的某个或者某些View；
3. 在高亮显示的View旁边可能有一些带文本的图片，或者指示方向的图片+文本；
4. 高亮部分可以响应点击事件，并且很有可能点击后继续显示下一步指引，直到显示完。

指引的技术实现

分析了指引的需求后，得到指引的基本元素，决定用自定义View实现，命名这个自定义View为GuideView。实现整个指引流程如下：
1.定义指引绘制要素Shape，及其派生类：Rectangle、Oval、BitmapDecoration、TextDecoration；
2.定义每一步指引的信息GuideInfo，并获取高亮区域的坐标矩形；
3.定义GuideView继承View，绘制指引要素：Shape；
4.定义GuideManager，管理多步骤指引；
5.定义GuideDialog承载GuideView，覆盖在页面上，和GuideManager

指引的要素：Shape

指引的基本要素包括：高亮显示的View区域，图片，文本等饰品。定义个接口，命名为Shape，那么Shape有子类：高亮的矩形(Rectangle)，高亮的圆形(Oval)，图片(BitmapDecoration)，文本(TextDecoration)。指引要素实现代码如下：

interface Shape {
    fun draw(canvas: Canvas, paint: Paint)
}

class Oval(private val rect: RectF) : Shape {
    override fun draw(canvas: Canvas, paint: Paint) {
        canvas.drawOval(rect, paint)
    }
}

class Rectangle(
    private val rect: RectF,
    private val xRadius: Float = 0F,
    private val yRadius: Float = 0F
) : Shape {
    override fun draw(canvas: Canvas, paint: Paint) {
        canvas.drawRoundRect(rect, xRadius, yRadius, paint)
    }
}
class BitmapDecoration(
    private val bitmap: Bitmap,
    private val left: Float,
    private val top: Float
) : Shape {
    override fun draw(canvas: Canvas, paint: Paint) {
        canvas.drawBitmap(bitmap, left, top, paint)
    }
}
class TextDecoration(
    protected val text: String,         // 要绘制的文本
    protected val textSize: Float,      // 字体大小
    protected val textColor: Int,       // 字体颜色
    protected val startX: Float,        // x轴起点(left)
    protected val startY: Float,        // y轴七点(top)
    protected val bold: Boolean = false // 粗体
) : Shape {
    override fun draw(canvas: Canvas, paint: Paint) {
        paint.color = textColor
        paint.textSize = textSize
        paint.typeface = if (bold) {
            Typeface.create(Typeface.SANS_SERIF, Typeface.BOLD)
        } else {
            Typeface.DEFAULT_BOLD
        }
        canvas.drawText(text, startX, startY, paint)
    }
}

封装指引步骤：GuideInfo

上面介绍了指引要素Shape，接下来需要继续完成指引要素的封装，命名为GuideInfo。GuideInfo封装了一个指引页面(或者说一帧)包含的所有显示要素，也就是多个Shape，包括：高亮的View区域，图片，文本等。GuideView显示指引，也就是把一个GuideInfo对象的Shape绘制出来。

class GuideInfo(
    private val targetView: View,            // 高亮显示的，要指引的View
    val padding: Int = 0,                    // 高亮区域的padding(如果要显示大一些时可设置padding)
    val isOval: Boolean = false,             // 高亮区域是否时圆形
    val radius: Float = 0F,                  // 如果时矩形，那么可以设置圆角
    private val paddingLeft: Int = 0,        // 四个方向的padding
    private val paddingTop: Int = 0,
    private val paddingRight: Int = 0,
    private val paddingBottom: Int = 0,
    autoShape: Boolean = false // 是否使用自定义的高亮区域，true: 自动根据View的Background获取Shape
) {

    val mShapes = mutableListOf<Shape>()
    var mTargetHighlightShape: Shape? = null // 这就是高亮显示的地方
    val targetBound: RectF                   // 高亮View的矩形区域，可根据这个矩形设置其它Shape的位置
}

一个GuideInfo对象代表一个指引步骤（一帧），一个完整的指引，可能包含多个步指引

绘制指引要素：GuideView

绘制指引的大概流程如下：

1. 绘制一个半透明遮罩层；
2. 绘制高亮显示的View区域；
3. 绘制其它装饰，如图片，文本等。

代码如下：

class GuideView : View, View.OnTouchListener, GestureDetector.OnGestureListener {

    /**
     * 当点击了高亮区域时响应
     */
    interface OnClickListener {
        fun onClick()
    }

    private val location = IntArray(2)
    private var initLocation = false
    private val mPaint = Paint()
    private var mGuideInfo: GuideInfo? = null
    private var background: Int = 0
    private lateinit var mGestureDetector: GestureDetector
    var mOnClickListener: OnClickListener? = null

    private fun initView(attrs: AttributeSet) {
        background = getColor(context, R.color.translucent)
        val typedArray: TypedArray = context.obtainStyledAttributes(attrs, R.styleable.GuideView)
        background = typedArray.getColor(R.styleable.GuideView_background_translucent, background)
        typedArray.recycle()
        mPaint.isAntiAlias = true
        setOnTouchListener(this)
        mGestureDetector = GestureDetector(context, this)
    }

    constructor(context: Context) : super(context)

    constructor(context: Context, attrs: AttributeSet) : super(context, attrs) {
        initView(attrs)
    }

    constructor(context: Context, attrs: AttributeSet, defStyleAttr: Int) : super(context, attrs, defStyleAttr) {
        initView(attrs)
    }

    override fun onDraw(canvas: Canvas) {
        super.onDraw(canvas)
        if(!initLocation) {
            getLocationOnScreen(location)
            initLocation = true
        }
        drawBackGround(canvas)
        drawShapes(canvas)
    }

    override fun onTouch(v: View?, event: MotionEvent?): Boolean {
        if (v != this || event == null || mGuideInfo == null) {
            return false
        }
        return mGestureDetector.onTouchEvent(event)
    }

    override fun onShowPress(e: MotionEvent?) {

    }

    override fun onSingleTapUp(event: MotionEvent?): Boolean {
        if (event == null || mGuideInfo == null) {
            return false
        }
        if (mGuideInfo!!.targetBound.contains(location[0] + event.x,
                location[1] + event.y)) {
            mOnClickListener?.onClick()
            return true
        }
        return false
    }

    override fun onDown(e: MotionEvent?): Boolean {
        return true
    }

    override fun onFling(
        e1: MotionEvent?,
        e2: MotionEvent?,
        velocityX: Float,
        velocityY: Float
    ): Boolean {
        return false
    }

    override fun onScroll(
        e1: MotionEvent?,
        e2: MotionEvent?,
        distanceX: Float,
        distanceY: Float
    ): Boolean {
        return false
    }

    override fun onLongPress(e: MotionEvent?) {

    }

    fun showGuide(guideStep: GuideInfo) {
        this.mGuideInfo = guideStep
        postInvalidate()
    }

    private fun drawBackGround(canvas: Canvas) {
        mPaint.xfermode = null
        mPaint.color = background
        canvas.drawRect(0F, 0F, width.toFloat(), height.toFloat(), mPaint)
    }

    private fun drawShapes(canvas: Canvas) {
        if (mGuideInfo == null) {
            return
        }
        // 先转换一下坐标，这样绘制得到的和底层目标View区域重叠
        canvas.translate(-location[0].toFloat(), -location[1].toFloat())
        // 1.先绘制要抠图的部分，也就是高亮的区域
        mPaint.xfermode = PorterDuffXfermode(PorterDuff.Mode.DST_OUT)
        mGuideInfo?.mTargetHighlightShape?.draw(canvas, mPaint)
        // 2.再绘制其它的箭头，文本等指示性的Shape
        mPaint.xfermode = null
        mGuideInfo?.mShapes?.forEach {
            it.draw(canvas, mPaint)
        }
    }

}

管理指引：GuideManager

一个GuideInfo代表一帧指引，一个完整的指引可能会包含多帧，所以，指引流程需要定义一个管理类GuideManager，作为中间层，上对接用户，下对接GuideDialog，比较简单，就是定义了一个GuideInfo数组和一个指向当前步骤的指针，还定义了一些回调，直接贴代码吧：

interface GuideListener {
    fun onNextStep(step: Int)

    fun onCompleted()
}

class GuideManager(activity: Activity) :
    GuideDialog.OnNextStepListener {

    private val mGuideSteps = mutableListOf<GuideInfo>()
    private var currentStep = -1
    val mGuideDialog: GuideDialog =
        GuideDialog(activity)
    var mGuideListener: GuideListener? = null
    var showGuideButton = false

    init {
        mGuideDialog.mOnNextStepListener = this
        if (!showGuideButton) {
            mGuideDialog.btnPreStep.visibility = View.GONE
            mGuideDialog.btnNextStep.visibility = View.GONE
        }
    }

    fun addGuideStep(guideInfo: GuideInfo) {
        mGuideSteps.add(guideInfo)
    }

    fun guideStepCount(): Int {
        return mGuideSteps.size
    }

    fun show() {
        mGuideDialog.show()
        onNextStep()
    }

    override fun onNextStep() {
        if (currentStep >= mGuideSteps.size - 1) {
            mGuideDialog.dismiss()
            mGuideListener?.onCompleted()
            return
        }
        currentStep++
        val guideStep: GuideInfo = mGuideSteps[currentStep]
        mGuideDialog.guideView.showGuide(guideStep)
        if (currentStep > 0 && showGuideButton) {
            mGuideDialog.btnPreStep.visibility = View.VISIBLE
        }
        updateNextText()
    }

    override fun onPreStep() {
        if (currentStep == 0) {
            return
        }
        currentStep -= 1
        val guideStep: GuideInfo = mGuideSteps[currentStep]
        mGuideDialog.guideView.showGuide(guideStep)
        if (currentStep == 0 && showGuideButton) {
            mGuideDialog.btnPreStep.visibility = View.GONE
        }
        updateNextText()
    }

    private fun updateNextText() {
        if (currentStep == mGuideSteps.size - 1) {
            mGuideDialog.btnNextStep.setText(R.string.end)
        } else {
            mGuideDialog.btnNextStep.setText(R.string.next_step)
        }
        mGuideListener?.onNextStep(currentStep)
    }
}

承载GuideView的载体：GuideDialog

这个就更简单了，直接看代码：

class GuideDialog : BaseDialog, View.OnClickListener,
    GuideView.OnClickListener {

    var mOnNextStepListener: OnNextStepListener? = null

    constructor(context: Context): super(context, R.style.DialogFullScreenTranslucent){
        setContentView(R.layout.dialog_guide)
        btnNextStep.setOnClickListener(this)
        btnPreStep.setOnClickListener(this)
        guideView.mOnClickListener = this
    }

    override fun onClick(view: View) {
        if (view.id == R.id.btnNextStep) {
            mOnNextStepListener?.onNextStep()
        } else if (view.id == R.id.btnPreStep) {
            mOnNextStepListener?.onPreStep()
        }
    }

    interface OnNextStepListener {
        fun onNextStep()

        fun onPreStep()
    }

    override fun onClick() {
        mOnNextStepListener?.onNextStep()
    }
}

接入项目

这里举个栗子，自己再封装一下，就算是一行代码接入，代码中的imgLogo，imgLogo2，tvName分别是页面上的ImageView和TextView：

fun showGuide(context: Activity) {
    GuideManager(context).apply {
        addGuideStep(GuideInfo(imgLogo, isOval = true).apply {
            val textShape = TextDecoration(
                "这是圆形高亮区域，点击高亮进入下一步",
                sp2px(context, 12F).toFloat(),
                ContextCompat.getColor(context, R.color.white),
                targetBound.right + dip2px(context, 8F), targetBound.centerY()
            )
            addShape(textShape)
        })
        addGuideStep(GuideInfo(imgLogo2, radius = 16F).apply {
            val textShape = TextDecoration(
                "这是圆角矩形高亮区域，点击高亮继续进入下一步",
                sp2px(context, 12F).toFloat(),
                ContextCompat.getColor(context, R.color.white),
                targetBound.left, targetBound.bottom + dip2px(context, 24F)
            )
            addShape(textShape)
        })
        addGuideStep(GuideInfo(tvName, padding = 20).apply {
            val bitmap = BitmapFactory.decodeResource(resources, R.mipmap.ic_add_location_white_48dp)
            val bitmapShape =
                BitmapDecoration(
                    bitmap,
                    targetBound.left,
                    targetBound.top - dip2px(context, 45F)
                )
            addShape(bitmapShape)
            val textShape = TextDecoration(
                "点击高亮结束指引",
                sp2px(context, 14F).toFloat(),
                ContextCompat.getColor(context, R.color.white),
                targetBound.centerX(),
                targetBound.bottom + dip2px(context, 32F)
            )
            addShape(textShape)
        })
        mGuideListener = object: GuideListener {
            override fun onNextStep(step: Int) {
                Toast.makeText(context, "当前步骤：${step + 1}", Toast.LENGTH_SHORT).show()
            }

            override fun onCompleted() {
                tvShowGuide.visibility = View.VISIBLE
            }
        }
        // 如果要显示“上一步”，“下一步”，可以设置GuideManager中的mGuideDialog，
    }.show()
}

关键技术点

定位高亮区域

通过View#getLocationOnScreen()方法可以获得目标View左上角顶点的屏幕坐标，已知目标View的宽高，然后可以得到高亮View的矩形（划重点：是屏幕坐标，后面绘制需要根据GuideView左上角坐标做一次变换，这样绘制出来刚好和目标View重叠）：

    fun targetViewRectF(): RectF {
        val location = IntArray(2)
        targetView.getLocationOnScreen(location)
        val rectF = RectF(
            location[0].toFloat(),
            location[1].toFloat(),
            location[0].toFloat() + targetView.width,
            location[1].toFloat() + targetView.height
        )
        return rectF
    }

绘制高亮的View区域

如代码所示，绘制高亮View实际是从半透明背景中把目标View的区域抠出来，这样底层View就能正常显示，对比半透明层就是高亮效果了。关键点一，绘制完半透明背景后，需要转换一次坐标，xy就是GuideView左上角顶点坐标；关键点二，mPaint.xfermode = PorterDuffXfermode(PorterDuff.Mode.DST_OUT)，有兴趣可以深入学习一下，这里不解析(自己不懂，就不要忽悠别人)。

    private fun drawShapes(canvas: Canvas) {
        if (mGuideInfo == null) {
            return
        }
        // 转换一下坐标，这样绘制得到的和底层目标View区域重叠
        canvas.translate(-location[0].toFloat(), -location[1].toFloat())
        // 1.先绘制要抠图的部分，也就是高亮的区域
        mPaint.xfermode = PorterDuffXfermode(PorterDuff.Mode.DST_OUT)
        mGuideInfo?.mTargetHighlightShape?.draw(canvas, mPaint)
        // 2.再绘制其它的箭头，文本等指示性的Shape
        mPaint.xfermode = null
        mGuideInfo?.mShapes?.forEach {
            it.draw(canvas, mPaint)
        }
    }

高亮区域点击事件

上面已经得到了高亮View的矩形区域RectF，只要监听onTouch，判断事件是否落在这个矩形内即可。通过GestureDetector接管onTouch事件，可以轻松实现高亮View区域的点击事件。
至此，指引绘制部分，GuideView基本就这么点代码，就OK了。

    override fun onTouch(v: View?, event: MotionEvent?): Boolean {
        if (v != this || event == null || mGuideInfo == null) {
            return false
        }
        return mGestureDetector.onTouchEvent(event)
    }
    
    override fun onSingleTapUp(event: MotionEvent?): Boolean {
        if (event == null || mGuideInfo == null) {
            return false
        }
        if (mGuideInfo!!.targetBound.contains(event.rawX, event.rawY)) {
            mOnClickListener?.onClick()
            return true
        }
        return false
    }

优缺点

优点：

• 封装了指引的数据结构，支持扩展，清晰易懂；
• 流式构建流程，清晰优雅，简洁却不简单，可以实现复杂的指引；
• 对现有的代码无侵入性，封装后，可以做到一行代码接入指引；
• 无反射等影响性能的代码，对性能无任何影响，同一个页面的多个指引在一个Dialog中绘制，不会有切换感；
• 支持高亮View的点击事件

缺点：

• 每帧指引，只有一个高亮的View，目前还不能显示多个高亮的View；
• 给指引添加图片时，需要找准位置，文本目前还不支持换行，也不支持方向(如果确实需要，可继承TextDecoration，实现onDraw()，或者实现接口Shape重新定义一个新的TextDecoration)，再或者直接让UI设计师给tu，用BitmapDecoration代替；
• 高亮的View未能自动识别形状和属性，需要根据View来设置属性(虽然这些是已知的，没太大问题，但是如果能够自动识别确实可以再简化代码)

项目地址

代码不多，三五百行，核心的就那么几十行，下面附上项目githug地址：
GuideView

总结

• 一行代码接入指引，无代码侵入，无性能损耗；
• 借助kotlin的apply函数流式构建指引流程，简介明了；
• 以屏幕坐标为参考，准确定位高亮View的矩形区域；
• 在构建流程中动态添加Bitmap和文本，可以实现复杂指引；
• 实现了高亮区域点击事件，可以监听并完成额外的需求；
• 不足之处在于未能根据View自动识别高亮区域，随无大碍，但有待优化。

最后特别感谢来抠个图吧~——更优雅的Android UI界面控件高亮的实现的作者，如果没有他的思路我也难以实现这个指引小项目，也就没有本文。