自定义 View 实战

/**
 * 环形进度条 —— 典型的继承 View 绘制型自定义控件
 * 所有视觉元素完全由 Canvas + Paint 绘制，无任何子 View
 */
class RingProgressView @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,       // XML 属性集，用于从布局文件解析自定义属性
    defStyleAttr: Int = 0              // 默认样式属性，后续章节会详细讲解
) : View(context, attrs, defStyleAttr) {
 
    // ---------- 画笔对象在构造期创建，避免 onDraw 中重复分配 ----------
    // 背景环画笔：绘制灰色底环
    private val bgPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
        style = Paint.Style.STROKE     // 描边模式，不填充
        strokeWidth = 20f              // 环的粗细，单位为像素
        color = 0xFFE0E0E0.toInt()     // 浅灰色背景环
    }
 
    // 前景环画笔：绘制彩色进度弧
    private val fgPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
        style = Paint.Style.STROKE     // 同样是描边模式
        strokeWidth = 20f              // 与背景环等粗，保持视觉一致
        strokeCap = Paint.Cap.ROUND    // 线帽为圆形，弧线两端呈圆润效果
        color = 0xFF4CAF50.toInt()     // Material Green 500
    }
 
    // 绘制弧线需要的矩形边界，在 onSizeChanged 中计算一次即可
    private val arcRect = RectF()
 
    // 当前进度值：0 ~ 100
    var progress: Int = 0
        set(value) {
            field = value.coerceIn(0, 100) // 限制在合法范围内
            invalidate()                    // 通知系统重绘，触发 onDraw
        }
 
    /**
     * 尺寸变化回调 —— 在这里预计算绑定到尺寸的几何参数
     * 首次 layout 完成后、或 View 尺寸发生变化时调用
     */
    override fun onSizeChanged(w: Int, h: Int, oldw: Int, oldh: Int) {
        super.onSizeChanged(w, h, oldw, oldh)
        // 根据宽高和画笔粗细计算弧线的外接矩形
        // 需要向内收缩半个 strokeWidth，否则弧线会被裁剪
        val inset = fgPaint.strokeWidth / 2f
        arcRect.set(inset, inset, w - inset, h - inset)
    }
 
    /**
     * 测量回调 —— 支持 wrap_content 的关键
     * 如果不重写，wrap_content 会退化为 match_parent
     */
    override fun onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int) {
        // 默认期望尺寸为 200dp（转换为像素）
        val defaultSize = (200 * resources.displayMetrics.density).toInt()
        // resolveSize 会根据 MeasureSpec 的模式（EXACTLY/AT_MOST/UNSPECIFIED）
        // 智能地在"期望值"和"约束值"之间取合适的结果
        val width = resolveSize(defaultSize, widthMeasureSpec)
        val height = resolveSize(defaultSize, heightMeasureSpec)
        // 必须调用此方法存储测量结果，否则会抛出 IllegalStateException
        setMeasuredDimension(width, height)
    }
 
    /**
     * 绘制回调 —— 绘制型自定义 View 的核心
     * 注意：此方法内禁止创建任何对象（Paint/Rect/Path 等）
     */
    override fun onDraw(canvas: Canvas) {
        // 第一层：绘制 360° 的灰色背景完整圆环
        canvas.drawArc(arcRect, 0f, 360f, false, bgPaint)
        // 第二层：绘制从顶部（-90°）开始的绿色进度弧
        // sweepAngle = progress / 100 * 360，即进度百分比对应的角度
        val sweepAngle = progress / 100f * 360f
        canvas.drawArc(arcRect, -90f, sweepAngle, false, fgPaint)
    }
}

/**
 * 流式标签布局 —— 典型的继承 ViewGroup 布局型自定义控件
 * 子 View 从左到右排列，一行放不下时自动换行
 */
class FlowLayout @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,       // XML 属性集
    defStyleAttr: Int = 0
) : ViewGroup(context, attrs, defStyleAttr) {
 
    // 子 View 之间的水平间距（像素）
    private val horizontalSpacing = (8 * resources.displayMetrics.density).toInt()
    // 行与行之间的垂直间距（像素）
    private val verticalSpacing = (8 * resources.displayMetrics.density).toInt()
 
    /**
     * 测量阶段 —— 遍历所有子 View，模拟"排列"过程以计算自身所需的总宽高
     * 这是自定义 ViewGroup 中最复杂的方法
     */
    override fun onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int) {
        // 从 MeasureSpec 中解析出父容器给定的最大宽度约束
        val maxWidth = MeasureSpec.getSize(widthMeasureSpec)
        // paddingLeft + paddingRight 是 ViewGroup 自身的内边距，子 View 不能占据这部分空间
        val availableWidth = maxWidth - paddingLeft - paddingRight
 
        var currentLineWidth = 0   // 当前行已使用的宽度
        var currentLineHeight = 0  // 当前行的最大高度（取该行所有子 View 的最大值）
        var totalWidth = 0         // 所有行中最宽的那一行的宽度（用于 wrap_content 时报告自身宽度）
        var totalHeight = 0        // 所有行的高度累加（用于 wrap_content 时报告自身高度）
 
        // 遍历每一个子 View
        for (i in 0 until childCount) {
            val child = getChildAt(i)                // 获取第 i 个子 View
            if (child.visibility == GONE) continue   // 跳过 GONE 状态的子 View（不占空间）
 
            // 让子 View 自行测量：传入父容器的约束，子 View 会在内部执行自己的 onMeasure
            measureChild(child, widthMeasureSpec, heightMeasureSpec)
 
            val childWidth = child.measuredWidth     // 子 View 测量后的期望宽度
            val childHeight = child.measuredHeight   // 子 View 测量后的期望高度
 
            // 判断是否需要换行：当前行剩余空间放不下这个子 View
            if (currentLineWidth + childWidth > availableWidth) {
                // 换行前：将当前行的宽度与历史最大值比较，更新 totalWidth
                totalWidth = maxOf(totalWidth, currentLineWidth)
                // 将当前行高度累加到 totalHeight（如果不是第一行，还要加上行间距）
                totalHeight += currentLineHeight + verticalSpacing
                // 重置当前行的状态：新行从这个放不下的子 View 开始
                currentLineWidth = childWidth + horizontalSpacing
                currentLineHeight = childHeight
            } else {
                // 不换行：累加当前行宽度，更新当前行的最大高度
                currentLineWidth += childWidth + horizontalSpacing
                currentLineHeight = maxOf(currentLineHeight, childHeight)
            }
        }
 
        // 别忘了最后一行（循环结束时最后一行的数据还没有被累加）
        totalWidth = maxOf(totalWidth, currentLineWidth)
        totalHeight += currentLineHeight
 
        // 加上 ViewGroup 自身的 padding
        totalWidth += paddingLeft + paddingRight
        totalHeight += paddingTop + paddingBottom
 
        // resolveSize：根据 MeasureSpec 模式智能选择最终尺寸
        // EXACTLY 模式 → 使用 spec 给定的精确值
        // AT_MOST 模式 → 取 min(计算值, spec上限)
        // UNSPECIFIED 模式 → 直接使用计算值
        setMeasuredDimension(
            resolveSize(totalWidth, widthMeasureSpec),
            resolveSize(totalHeight, heightMeasureSpec)
        )
    }
 
    /**
     * 布局阶段 —— 将每个子 View "放置"到正确的 (left, top, right, bottom) 坐标
     * 逻辑与 onMeasure 中的"模拟排列"高度相似，但这次是真正地调用 child.layout()
     */
    override fun onLayout(changed: Boolean, l: Int, t: Int, r: Int, b: Int) {
        // 可用宽度 = ViewGroup 实际宽度 - 左右 padding
        val availableWidth = width - paddingLeft - paddingRight
 
        var xPos = paddingLeft     // 当前子 View 的 x 起始坐标（从左 padding 开始）
        var yPos = paddingTop      // 当前子 View 的 y 起始坐标（从顶 padding 开始）
        var currentLineHeight = 0  // 当前行最大高度，用于换行时计算下一行的 y 坐标
 
        for (i in 0 until childCount) {
            val child = getChildAt(i)
            if (child.visibility == GONE) continue   // GONE 的子 View 不参与布局
 
            val childWidth = child.measuredWidth      // 使用 measure 阶段确定的宽度
            val childHeight = child.measuredHeight    // 使用 measure 阶段确定的高度
 
            // 判断是否需要换行
            if (xPos + childWidth > paddingLeft + availableWidth) {
                // 换行：x 回到左边 padding 处，y 下移一行
                xPos = paddingLeft
                yPos += currentLineHeight + verticalSpacing
                currentLineHeight = 0                 // 新行高度重置
            }
 
            // 核心调用：将子 View 放置到 (xPos, yPos) 处
            // child.layout 的四个参数分别是 left, top, right, bottom
            child.layout(xPos, yPos, xPos + childWidth, yPos + childHeight)
 
            // 更新当前行状态
            xPos += childWidth + horizontalSpacing     // x 右移，为下一个子 View 留出位置
            currentLineHeight = maxOf(currentLineHeight, childHeight) // 更新行高
        }
    }
}

/**
 * 标题栏组合控件 —— 典型的组合型自定义 View
 * 继承 FrameLayout 作为根容器，内部 inflate 一个 XML 布局
 */
class TitleBarView @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,
    defStyleAttr: Int = 0
) : FrameLayout(context, attrs, defStyleAttr) {
 
    // 子 View 引用：通过 inflate 后的 findViewById 获取
    private val btnBack: ImageButton       // 左侧返回按钮
    private val tvTitle: TextView          // 中间标题文本
    private val btnMenu: ImageButton       // 右侧菜单按钮
 
    init {
        // 将 XML 布局加载到当前 FrameLayout 中
        // 第三个参数 true 表示将 inflate 出的根 View 直接 addView 到 this
        LayoutInflater.from(context).inflate(R.layout.view_title_bar, this, true)
 
        // 绑定子 View 引用
        btnBack = findViewById(R.id.btn_back)    // 查找返回按钮
        tvTitle = findViewById(R.id.tv_title)    // 查找标题 TextView
        btnMenu = findViewById(R.id.btn_menu)    // 查找菜单按钮
 
        // 解析 XML 中声明的自定义属性
        attrs?.let {
            // obtainStyledAttributes 返回 TypedArray，用完必须 recycle
            val ta = context.obtainStyledAttributes(it, R.styleable.TitleBarView)
            // 读取 app:title 属性，设置到标题 TextView
            tvTitle.text = ta.getString(R.styleable.TitleBarView_title) ?: ""
            // 读取 app:showBack 属性，控制返回按钮是否可见
            val showBack = ta.getBoolean(R.styleable.TitleBarView_showBack, true)
            btnBack.visibility = if (showBack) VISIBLE else GONE
            // 读取 app:menuIcon 属性，设置菜单按钮的图标
            val menuIcon = ta.getDrawable(R.styleable.TitleBarView_menuIcon)
            if (menuIcon != null) {
                btnMenu.setImageDrawable(menuIcon)   // 设置自定义图标
                btnMenu.visibility = VISIBLE          // 有图标才显示
            } else {
                btnMenu.visibility = GONE             // 无图标则隐藏
            }
            ta.recycle()   // 必须回收 TypedArray 以避免内存泄漏
        }
    }
 
    /**
     * 对外暴露的 API：设置返回按钮的点击回调
     * 使用 Kotlin 高阶函数简化回调写法
     */
    fun setOnBackClickListener(listener: () -> Unit) {
        btnBack.setOnClickListener { listener() }    // 将 View.OnClickListener 代理到 lambda
    }
 
    /**
     * 对外暴露的 API：动态修改标题文字
     */
    fun setTitle(title: String) {
        tvTitle.text = title    // 直接委托给内部 TextView
    }
 
    /**
     * 对外暴露的 API：设置菜单按钮的点击回调
     */
    fun setOnMenuClickListener(listener: () -> Unit) {
        btnMenu.setOnClickListener { listener() }
    }
}

<?xml version="1.0" encoding="utf-8"?>
<!-- 根元素使用 merge 标签，避免多一层无用的 ViewGroup 嵌套 -->
<!-- 因为 TitleBarView 本身已经是 FrameLayout，merge 的子 View 会直接成为其 children -->
<merge xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    tools:parentTag="android.widget.FrameLayout">
 
    <!-- 左侧返回按钮：固定在左边，垂直居中 -->
    <ImageButton
        android:id="@+id/btn_back"
        android:layout_width="48dp"
        android:layout_height="48dp"
        android:layout_gravity="start|center_vertical"
        android:background="?attr/selectableItemBackgroundBorderless"
        android:src="@drawable/ic_arrow_back"
        android:contentDescription="@string/back" />
 
    <!-- 中间标题文本：水平和垂直都居中 -->
    <TextView
        android:id="@+id/tv_title"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_gravity="center"
        android:textSize="18sp"
        android:textColor="#DE000000"
        android:textStyle="bold"
        tools:text="页面标题" />
 
    <!-- 右侧菜单按钮：固定在右边，垂直居中 -->
    <ImageButton
        android:id="@+id/btn_menu"
        android:layout_width="48dp"
        android:layout_height="48dp"
        android:layout_gravity="end|center_vertical"
        android:background="?attr/selectableItemBackgroundBorderless"
        android:src="@drawable/ic_more_vert"
        android:contentDescription="@string/menu" />
 
</merge>

/**
 * 可清除内容的输入框 —— 典型的继承现有控件扩展型
 * 继承 AppCompatEditText，在原有全部功能的基础上增加"清除按钮"
 */
class ClearableEditText @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,
    // 使用 AppCompatEditText 的默认样式，确保 Material Design 兼容
    defStyleAttr: Int = androidx.appcompat.R.attr.editTextStyle
) : AppCompatEditText(context, attrs, defStyleAttr) {
 
    // 清除按钮的 Drawable 图标，在构造期加载一次
    private val clearDrawable: Drawable? =
        ContextCompat.getDrawable(context, R.drawable.ic_clear)?.apply {
            // 设置 Drawable 的绘制边界（intrinsicWidth/Height 是图片的原始宽高）
            setBounds(0, 0, intrinsicWidth, intrinsicHeight)
        }
 
    init {
        // 监听文本变化：有内容时显示清除图标，无内容时隐藏
        addTextChangedListener(object : TextWatcher {
            override fun beforeTextChanged(s: CharSequence?, start: Int, count: Int, after: Int) {}
            override fun onTextChanged(s: CharSequence?, start: Int, before: Int, count: Int) {
                // 根据是否有文本内容来决定清除图标的显隐
                updateClearIconVisibility(s?.isNotEmpty() == true)
            }
            override fun afterTextChanged(s: Editable?) {}
        })
 
        // 监听焦点变化：失去焦点时隐藏清除图标
        setOnFocusChangeListener { _, hasFocus ->
            updateClearIconVisibility(hasFocus && text?.isNotEmpty() == true)
        }
    }
 
    /**
     * 控制右侧清除图标的显示/隐藏
     * setCompoundDrawables 的四个参数分别对应：左/上/右/下 方向的 Drawable
     * 只修改右侧图标，其余三个方向传 null 表示不改变
     */
    private fun updateClearIconVisibility(visible: Boolean) {
        // compoundDrawables[0] 是当前左侧图标，保持不变
        setCompoundDrawables(
            compoundDrawables[0],    // 左侧图标保持原样
            compoundDrawables[1],    // 上方图标保持原样
            if (visible) clearDrawable else null,  // 右侧：有内容则显示清除图标
            compoundDrawables[3]     // 下方图标保持原样
        )
    }
 
    /**
     * 拦截触摸事件 —— 检测用户是否点击了右侧的清除图标区域
     * 这是扩展型自定义 View 的典型手法：在原有触摸逻辑的基础上"插入"额外处理
     */
    override fun onTouchEvent(event: MotionEvent): Boolean {
        // 只在 ACTION_UP（手指抬起）时响应，避免误触
        if (event.action == MotionEvent.ACTION_UP) {
            // 获取当前右侧 Drawable（可能为 null，表示清除图标未显示）
            val drawable = compoundDrawables[2]
            if (drawable != null) {
                // 计算清除图标的"可点击区域"左边界
                // totalPaddingRight 包含了 compoundDrawablePadding + drawable 宽度 + paddingRight
                val touchAreaLeft = width - totalPaddingRight
                // 如果触摸点的 x 坐标在清除图标区域内，则执行清除操作
                if (event.x >= touchAreaLeft) {
                    setText("")    // 清空文本内容
                    return true    // 消费此事件，不再传递给父 View
                }
            }
        }
        // 其他情况交给 AppCompatEditText 的默认触摸处理
        return super.onTouchEvent(event)
    }
}

<!-- res/values/attrs.xml -->
<resources>
 
    <!-- 声明一个名为 circleColor 的属性，类型为 color -->
    <attr name="circleColor" format="color" />
 
    <!-- 声明一个名为 circleRadius 的属性，类型为 dimension -->
    <attr name="circleRadius" format="dimension" />
 
</resources>

<resources>
    <!-- 声明一个枚举属性 shape，只能取 circle/square/triangle 之一 -->
    <attr name="shape" format="enum">
        <!-- 每个 enum 项都有一个 name 和一个 int 映射值 -->
        <enum name="circle" value="0" />
        <enum name="square" value="1" />
        <enum name="triangle" value="2" />
    </attr>
</resources>

<resources>
    <!-- 声明一个 flags 属性 textStyle，可多值组合 -->
    <attr name="textStyle" format="flags">
        <!-- 值必须是 2 的幂，以便按位或组合 -->
        <flag name="normal" value="0" />
        <flag name="bold" value="1" />      <!-- 0b0001 -->
        <flag name="italic" value="2" />    <!-- 0b0010 -->
        <flag name="underline" value="4" /> <!-- 0b0100 -->
    </attr>
</resources>

<resources>
    <!-- 该属性既可以写颜色，也可以写资源引用 -->
    <attr name="overlayColor" format="color|reference" />
</resources>

// ① 代码中直接 new 时调用（如 val view = MyView(context)）
// 此构造函数无 AttributeSet，不涉及 XML 属性解析
constructor(context: Context)
 
// ② XML 布局加载时调用（LayoutInflater 反射创建 View 时使用）
// attrs 中包含了 XML 中声明的所有属性键值对
constructor(context: Context, attrs: AttributeSet?)
 
// ③ 带默认样式属性的构造函数
// defStyleAttr 是一个指向 Theme 中某属性的引用（如 R.attr.myViewStyle）
constructor(context: Context, attrs: AttributeSet?, defStyleAttr: Int)
 
// ④ 带默认样式资源的构造函数（API 21+ 正式公开）
// defStyleRes 是一个直接指向 Style 资源的引用（如 R.style.DefaultMyViewStyle）
constructor(context: Context, attrs: AttributeSet?, defStyleAttr: Int, defStyleRes: Int)

class CircleView : View {
 
    // 核心属性：圆的颜色与半径
    private var circleColor: Int = Color.RED
    private var circleRadius: Float = 50f
 
    // ① 代码创建 —— 委托给②
    constructor(context: Context) : this(context, null)
 
    // ② XML 加载 —— 委托给③
    constructor(context: Context, attrs: AttributeSet?) : this(context, attrs, 0)
 
    // ③ 带 defStyleAttr —— 委托给④
    constructor(context: Context, attrs: AttributeSet?, defStyleAttr: Int)
            : this(context, attrs, defStyleAttr, 0)
 
    // ④ 最终构造函数 —— 在此统一解析所有属性
    constructor(
        context: Context,
        attrs: AttributeSet?,
        defStyleAttr: Int,
        defStyleRes: Int
    ) : super(context, attrs, defStyleAttr, defStyleRes) {
        // 在此调用 obtainStyledAttributes 解析属性
        initAttributes(context, attrs, defStyleAttr, defStyleRes)
    }
}

private fun initAttributes(
    context: Context,
    attrs: AttributeSet?,   // XML 中的原始属性集
    defStyleAttr: Int,      // Theme 中指向默认 Style 的属性（如 R.attr.circleViewStyle）
    defStyleRes: Int         // 直接引用的默认 Style 资源（如 R.style.DefaultCircleViewStyle）
) {
    // obtainStyledAttributes 四参数版本：
    // 参数1: attrs —— 从 XML 中传入的属性集合
    // 参数2: R.styleable.CircleView —— 想要获取的属性 ID 数组（由 declare-styleable 生成）
    // 参数3: defStyleAttr —— 在 Theme 中查找默认 Style 的属性引用
    // 参数4: defStyleRes —— 当 defStyleAttr 为 0 或 Theme 中未定义时使用的兜底 Style
    val ta: TypedArray = context.obtainStyledAttributes(
        attrs,
        R.styleable.CircleView,
        defStyleAttr,
        defStyleRes
    )
 
    // 从 TypedArray 中按索引读取属性值
    // 索引常量由 declare-styleable 自动生成，格式为 R.styleable.{styleable名}_{属性名}
    // 第二个参数是默认值，当 XML/Style/Theme 都未定义时使用
    circleColor = ta.getColor(
        R.styleable.CircleView_circleColor,  // 属性索引
        Color.RED                             // 默认值：未配置时使用红色
    )
 
    circleRadius = ta.getDimension(
        R.styleable.CircleView_circleRadius,  // 属性索引
        50f                                    // 默认值：50px
    )
 
    // 【关键】用完后必须调用 recycle() 释放 TypedArray 对象
    // TypedArray 内部使用对象池（Pool）复用，不 recycle 会造成内存泄漏
    ta.recycle()
}

// ——— 基本类型 ———
// 读取 color 属性，返回 ARGB int 值
val color: Int = ta.getColor(index, defaultValue)
 
// 读取 dimension 属性，自动将 dp/sp 转为 px，返回 float
val size: Float = ta.getDimension(index, defaultValue)
 
// 读取 dimension 属性，但返回四舍五入后的 int 像素值
val sizeInt: Int = ta.getDimensionPixelSize(index, defaultValue)
 
// 读取 dimension 属性，返回截断后的 int 像素值（向下取整）
val sizeOffset: Int = ta.getDimensionPixelOffset(index, defaultValue)
 
// 读取 boolean 属性
val flag: Boolean = ta.getBoolean(index, defaultValue)
 
// 读取 integer 属性（enum/flags 也用此方法，返回底层 int 值）
val count: Int = ta.getInt(index, defaultValue)
 
// 读取 float 属性
val ratio: Float = ta.getFloat(index, defaultValue)
 
// 读取 string 属性，返回 String?（可能为 null）
val title: String? = ta.getString(index)
 
// ——— 资源引用类型 ———
// 读取 reference 类型，返回资源 ID（如 R.drawable.bg），未定义时返回 defaultValue
val resId: Int = ta.getResourceId(index, defaultValue)
 
// 读取 Drawable 引用，直接返回 Drawable 对象
val drawable: Drawable? = ta.getDrawable(index)
 
// ——— 存在性检查 ———
// 判断某个属性是否被用户显式设置过（XML / Style / Theme 中定义过即为 true）
val hasValue: Boolean = ta.hasValue(index)

<resources>
 
    <!-- 将 circleColor 和 circleRadius 归组到 CircleView 下 -->
    <declare-styleable name="CircleView">
        <!-- 引用已声明的全局属性 circleColor（注意这里不再写 format） -->
        <attr name="circleColor" />
        <!-- 也可以直接在 declare-styleable 内部声明新属性 -->
        <attr name="circleRadius" format="dimension" />
        <!-- 引用 Android 系统已定义的属性 -->
        <attr name="android:text" />
    </declare-styleable>
 
</resources>

// AAPT2 自动生成的内容（位于 R.java 中）
public static final class styleable {
 
    // ① 属性 ID 数组：包含了 CircleView 分组中所有属性的资源 ID
    // 数组的顺序由 AAPT2 按属性名字母序排列（不是你在 XML 中写的顺序！）
    // 这个数组会作为 obtainStyledAttributes() 的第二个参数传入
    public static final int[] CircleView = {
        0x0101014f,  // android:text 的资源 ID（系统属性 ID 通常以 0x01 开头）
        0x7f040001,  // circleColor 的资源 ID（应用属性 ID 通常以 0x7f 开头）
        0x7f040002   // circleRadius 的资源 ID
    };
 
    // ② 索引常量：每个属性在上面数组中的下标
    // 命名规则：{styleable名}_{属性名}
    // 这些索引用于从 TypedArray 中读取对应位置的属性值
    public static final int CircleView_android_text = 0;
    public static final int CircleView_circleColor = 1;
    public static final int CircleView_circleRadius = 2;
}

<!-- 布局文件 res/layout/activity_main.xml -->
<!-- xmlns:app 声明了自定义属性的命名空间 -->
<!-- http://schemas.android.com/apk/res-auto 是一个通配符，会自动匹配当前应用包名 -->
<FrameLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
 
    <!-- 使用 app: 前缀设置自定义属性 -->
    <!-- 使用 android: 前缀设置系统属性（包括被 declare-styleable 引用的系统属性） -->
    <com.example.widget.CircleView
        android:layout_width="200dp"
        android:layout_height="200dp"
        android:text="Circle"
        app:circleColor="@color/blue"
        app:circleRadius="48dp" />
 
</FrameLayout>

<!-- 定义一个 Style -->
<style name="GreenCircleStyle">
    <item name="circleColor">#00FF00</item>
    <item name="circleRadius">32dp</item>
</style>
 
<!-- 使用 Style：此处 circleColor 被 XML 直接值覆盖，circleRadius 从 Style 获取 -->
<com.example.widget.CircleView
    style="@style/GreenCircleStyle"
    app:circleColor="#FF0000"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content" />

<!-- res/values/attrs.xml -->
<resources>
    <!-- 这个属性将作为 Theme 中的"挂钩点"，值类型是 reference（指向一个 Style） -->
    <attr name="circleViewStyle" format="reference" />
 
    <declare-styleable name="CircleView">
        <attr name="circleColor" format="color" />
        <attr name="circleRadius" format="dimension" />
    </declare-styleable>
</resources>

<!-- res/values/styles.xml -->
<style name="Widget.App.CircleView">
    <item name="circleColor">#2196F3</item>   <!-- Material Blue -->
    <item name="circleRadius">40dp</item>
</style>

<!-- res/values/themes.xml -->
<style name="AppTheme" parent="Theme.MaterialComponents.Light">
    <!-- 将 circleViewStyle 属性指向 Widget.App.CircleView 这个 Style -->
    <item name="circleViewStyle">@style/Widget.App.CircleView</item>
</style>

class CircleView : View {
 
    // 构造函数②：XML 加载时调用
    // 将 R.attr.circleViewStyle 作为 defStyleAttr 传入
    // 这就告诉系统："当 XML 和 style 都没定义某属性时，去 Theme 中找 circleViewStyle 属性指向的 Style"
    constructor(context: Context, attrs: AttributeSet?)
            : this(context, attrs, R.attr.circleViewStyle)
 
    constructor(context: Context, attrs: AttributeSet?, defStyleAttr: Int)
            : this(context, attrs, defStyleAttr, 0)
 
    constructor(context: Context, attrs: AttributeSet?, defStyleAttr: Int, defStyleRes: Int)
            : super(context, attrs, defStyleAttr, defStyleRes) {
        // 解析属性
        val ta = context.obtainStyledAttributes(attrs, R.styleable.CircleView, defStyleAttr, defStyleRes)
        // ... 读取属性 ...
        ta.recycle()
    }
}

// defStyleAttr 传 0，defStyleRes 传一个具体的 Style 资源
// 此时属性值直接从 R.style.DefaultCircleViewStyle 中获取（如果 XML 和 style 都没设置的话）
constructor(context: Context, attrs: AttributeSet?)
        : this(context, attrs, 0, R.style.DefaultCircleViewStyle)

// 推荐写法：defStyleAttr 走 Theme 查找，defStyleRes 作为兜底
constructor(context: Context, attrs: AttributeSet?)
        : this(context, attrs, R.attr.circleViewStyle, R.style.Widget_App_CircleView_Default)

<style name="AppTheme" parent="Theme.MaterialComponents.Light">
    <!-- 直接在 Theme 中定义 circleColor，优先级最低 -->
    <item name="circleColor">#9E9E9E</item>
</style>

<!-- themes.xml -->
<style name="AppTheme" parent="Theme.MaterialComponents.Light">
    <!-- 优先级 5：Theme 全局直接定义 -->
    <item name="circleColor">#9E9E9E</item>
    <!-- 优先级 3 的桥梁：Theme 属性指向 Style -->
    <item name="circleViewStyle">@style/Widget.App.CircleView</item>
</style>
 
<!-- styles.xml -->
<!-- 优先级 3 的目标 Style -->
<style name="Widget.App.CircleView">
    <item name="circleColor">#2196F3</item>
    <item name="circleRadius">40dp</item>
</style>
 
<!-- 优先级 2 的 Style -->
<style name="RedCircleStyle">
    <item name="circleColor">#F44336</item>
    <item name="circleRadius">60dp</item>
</style>

<!-- layout.xml -->
<!-- 同时设置了 style（优先级 2）和直接属性（优先级 1） -->
<com.example.widget.CircleView
    style="@style/RedCircleStyle"
    app:circleColor="#4CAF50"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content" />

// obtainStyledAttributes 内部对优先级 3、4 的处理逻辑（伪代码）
fun resolveDefStyle(defStyleAttr: Int, defStyleRes: Int): Style? {
    // 如果 defStyleAttr 非零，先尝试从 Theme 中查找
    if (defStyleAttr != 0) {
        // 从当前 Theme 中取出 defStyleAttr 属性的值
        val themeStyle = theme.resolveAttribute(defStyleAttr)
        // 如果 Theme 中确实定义了这个属性，就用它指向的 Style
        if (themeStyle != null) {
            return themeStyle  // 优先级 3 命中
        }
    }
    // 如果 defStyleAttr 为 0，或者 Theme 中没定义，则使用 defStyleRes
    if (defStyleRes != 0) {
        return resources.getStyle(defStyleRes)  // 优先级 4 兜底
    }
    // 都没有，返回 null，继续查 Theme 全局属性（优先级 5）
    return null
}

<resources>
    <!--
        在 Theme 中设置此属性可全局修改 CircleView 的默认样式。
        示例：<item name="circleViewStyle">@style/MyCustomCircleStyle</item>
    -->
    <attr name="circleViewStyle" format="reference" />
</resources>

override fun onDraw(canvas: Canvas) {
    super.onDraw(canvas)
 
    // ---------- 1. 画一条从 (50,50) 到 (300,50) 的水平线 ----------
    // Paint 定义了颜色、线宽、抗锯齿等视觉属性
    canvas.drawLine(
        50f, 50f,   // 起点坐标 (startX, startY)
        300f, 50f,  // 终点坐标 (stopX, stopY)
        linePaint    // 使用预创建的 Paint 对象（避免在 onDraw 中 new）
    )
 
    // ---------- 2. 画一个填充矩形 ----------
    // RectF 使用 float 坐标，精度更高，适合绑制操作
    canvas.drawRect(
        50f,   // left：矩形左边界
        100f,  // top：矩形上边界
        300f,  // right：矩形右边界
        250f,  // bottom：矩形下边界
        fillPaint // style = FILL 的画笔
    )
 
    // ---------- 3. 画一个圆形 ----------
    canvas.drawCircle(
        175f,  // cx：圆心 X 坐标
        400f,  // cy：圆心 Y 坐标
        80f,   // radius：半径
        strokePaint // style = STROKE 的画笔，只画轮廓
    )
 
    // ---------- 4. 画一段弧线（扇形） ----------
    // 弧线基于一个椭圆的包围矩形来定义
    canvas.drawArc(
        ovalRect,   // RectF 椭圆包围盒
        0f,         // startAngle：起始角度（3点钟方向为0°）
        135f,       // sweepAngle：扫过角度（顺时针为正）
        true,       // useCenter：true=扇形(连接圆心), false=弧线
        arcPaint    // 画笔
    )
}

override fun onDraw(canvas: Canvas) {
    super.onDraw(canvas)
 
    // ---- 场景：在 View 中心画一个旋转45°的正方形 ----
 
    // 1. 保存当前坐标系状态（原点在左上角，无旋转）
    canvas.save()
 
    // 2. 将坐标原点平移到 View 的中心
    //    此后 (0, 0) 就是 View 的正中心
    canvas.translate(width / 2f, height / 2f)
 
    // 3. 以新原点为中心旋转 45°
    //    旋转影响后续所有 drawXxx 调用
    canvas.rotate(45f)
 
    // 4. 画一个中心在原点的正方形
    //    由于坐标系已经平移+旋转，实际效果是 View 中心的旋转方块
    val halfSize = 100f
    canvas.drawRect(
        -halfSize, // left：原点左侧 100px
        -halfSize, // top：原点上方 100px
        halfSize,  // right：原点右侧 100px
        halfSize,  // bottom：原点下方 100px
        rectPaint
    )
 
    // 5. 恢复到 save() 时保存的坐标系状态
    //    后续绘制不受上面的 translate/rotate 影响
    canvas.restore()
}

// save/restore 可以嵌套使用，形成多层状态栈
canvas.save()          // 状态栈: [S0]  — 保存初始状态
canvas.translate(100f, 0f)
canvas.save()          // 状态栈: [S0, S1] — 保存 translate 后的状态
canvas.rotate(30f)
canvas.drawRect(...)   // 此时坐标系 = translate(100,0) + rotate(30°)
canvas.restore()       // 弹出 S1，恢复到只有 translate(100,0) 的状态
canvas.drawCircle(...) // 此时坐标系 = translate(100,0)，无旋转
canvas.restore()       // 弹出 S0，恢复到初始坐标系

override fun onDraw(canvas: Canvas) {
    super.onDraw(canvas)
 
    // 保存状态，因为裁剪是破坏性操作
    canvas.save()
 
    // 设置一个圆角矩形裁剪区域
    // 此后所有绘制都只在这个圆角矩形内可见
    val clipPath = Path().apply {
        addRoundRect(
            RectF(0f, 0f, width.toFloat(), height.toFloat()), // 与 View 等大
            40f, 40f,   // 圆角半径 rx, ry
            Path.Direction.CW // 顺时针方向（影响填充规则）
        )
    }
    canvas.clipPath(clipPath) // 应用裁剪
 
    // 画一张全屏图片，但只有圆角矩形区域内可见
    canvas.drawBitmap(bitmap, 0f, 0f, null)
 
    // 恢复裁剪，后续绘制不受影响
    canvas.restore()
}

class MyCustomView(context: Context, attrs: AttributeSet?) : View(context, attrs) {
 
    // ===== 所有 Paint 在初始化阶段创建 =====
 
    // 填充画笔：用于绘制实心图形
    private val fillPaint = Paint().apply {
        color = Color.parseColor("#4CAF50") // Material Green 500
        style = Paint.Style.FILL            // 填充模式：只填充内部
        isAntiAlias = true                  // 开启抗锯齿，边缘更平滑
    }
 
    // 描边画笔：用于绘制轮廓线
    private val strokePaint = Paint().apply {
        color = Color.parseColor("#1565C0") // Material Blue 800
        style = Paint.Style.STROKE          // 描边模式：只画边线
        strokeWidth = 6f                    // 线宽 6px
        isAntiAlias = true                  // 开启抗锯齿
    }
 
    // 填充+描边画笔：同时填充内部并画边线
    private val fillAndStrokePaint = Paint().apply {
        color = Color.parseColor("#FF9800") // Material Orange 500
        style = Paint.Style.FILL_AND_STROKE // 两者兼具
        strokeWidth = 4f                    // 边线宽度
        isAntiAlias = true
    }
}

// 线帽与拐角的演示
private val capDemoPaint = Paint().apply {
    style = Paint.Style.STROKE
    strokeWidth = 20f
    color = Color.DKGRAY
    isAntiAlias = true
    strokeCap = Paint.Cap.ROUND   // 圆头线帽
    strokeJoin = Paint.Join.ROUND // 圆角拐角
}

// 推荐的 "万能" Paint 初始化模式
private val basePaint = Paint(Paint.ANTI_ALIAS_FLAG or Paint.DITHER_FLAG).apply {
    // 通过构造函数的 flags 参数同时开启抗锯齿和抖动
    // 比分别设置 isAntiAlias = true / isDither = true 更简洁
}

// 画一个等边三角形（手动计算三个顶点）
private val trianglePath = Path().apply {
    // 1. 移动到第一个顶点（底边左端）
    //    moveTo 不画线，只设定起始位置
    moveTo(100f, 300f)
 
    // 2. 从当前位置画直线到第二个顶点（底边右端）
    lineTo(300f, 300f)
 
    // 3. 画直线到第三个顶点（顶部中心）
    lineTo(200f, 127f) // 等边三角形高 = 边长 * √3/2 ≈ 200 * 0.866 ≈ 173
 
    // 4. 闭合路径：自动从当前位置画直线回到起点 (100, 300)
    //    如果不调用 close()，三角形的最后一条边会缺失（除非 style = FILL）
    close()
}

// 使用三阶贝塞尔画一条 S 形曲线
private val bezierPath = Path().apply {
    // 起点在左侧中央
    moveTo(50f, 400f)
 
    // cubicTo 的六个参数含义：
    //   (x1, y1) = 第一个控制点，将曲线"向上拉"
    //   (x2, y2) = 第二个控制点，将曲线"向下拉"
    //   (x3, y3) = 终点
    cubicTo(
        150f, 100f,  // 控制点1：大幅上移，曲线前半段向上弯曲
        250f, 700f,  // 控制点2：大幅下移，曲线后半段向下弯曲
        350f, 400f   // 终点：回到与起点相同的 Y 坐标
    )
    // 最终形成一条优雅的 S 形曲线
}

private val combinedPath = Path().apply {
    // 添加一个矩形到路径中
    // Direction.CW = 顺时针方向（clockwise），影响填充规则
    addRect(RectF(50f, 50f, 200f, 200f), Path.Direction.CW)
 
    // 添加一个圆形到路径中
    // 圆心 (300, 125)，半径 75
    addCircle(300f, 125f, 75f, Path.Direction.CW)
 
    // 添加一个圆角矩形
    addRoundRect(
        RectF(50f, 250f, 350f, 400f), // 矩形范围
        20f, 20f,                      // x方向和y方向圆角半径
        Path.Direction.CW
    )
 
    // 添加一段弧线（不连接到圆心，纯弧段）
    addArc(
        RectF(100f, 420f, 300f, 600f), // 椭圆包围盒
        0f,                             // 起始角度
        270f                            // 扫过角度
    )
}

// 两个重叠圆的填充效果演示
private val evenOddPath = Path().apply {
    fillType = Path.FillType.EVEN_ODD   // 使用奇偶规则
    addCircle(150f, 200f, 100f, Path.Direction.CW) // 圆1
    addCircle(250f, 200f, 100f, Path.Direction.CW) // 圆2
    // 结果：重叠区域被镂空，形成"排除"效果
}

// 布尔运算：矩形减去圆形 = 矩形带圆孔
val rectPath = Path().apply {
    addRect(RectF(50f, 50f, 350f, 350f), Path.Direction.CW) // 一个正方形
}
val circlePath = Path().apply {
    addCircle(200f, 200f, 80f, Path.Direction.CW) // 正方形中心的一个圆
}
 
// DIFFERENCE：从矩形中挖掉圆形区域
rectPath.op(circlePath, Path.Op.DIFFERENCE) // rectPath 现在是"带圆孔的矩形"

// Rect 与 RectF 互转
val intRect = Rect(10, 20, 300, 400)      // 整数矩形（用于布局计算）
val floatRect = RectF(intRect)             // 转为 float 矩形（用于绑制）
 
val backToInt = Rect()
floatRect.roundOut(backToInt)              // float → int，向外取整保证覆盖
// roundOut 向外扩展：left/top 向下取整，right/bottom 向上取整
// 确保 int 矩形完全包含原 float 矩形

override fun onTouchEvent(event: MotionEvent): Boolean {
    when (event.action) {
        MotionEvent.ACTION_DOWN -> {
            // 检查触摸点是否在按钮区域内
            // contains 对于 Rect 的判断规则是: left <= x < right 且 top <= y < bottom
            // 注意右边界和下边界是开区间（exclusive）
            if (buttonRect.contains(event.x.toInt(), event.y.toInt())) {
                // 处理点击
                isPressed = true
                invalidate() // 触发重绘以显示按下状态
                return true  // 消费事件
            }
        }
    }
    return super.onTouchEvent(event)
}

val rect1 = RectF(0f, 0f, 200f, 200f)
val rect2 = RectF(100f, 100f, 300f, 300f)
 
// 方法1：修改 rect1 为交集
val hasIntersection = rect1.intersect(rect2)
// hasIntersection = true, rect1 现在变成 (100, 100, 200, 200)
 
// 方法2：不修改原矩形，结果写入新矩形
val result = RectF()
result.setIntersect(rect1, rect2) // result = (100, 100, 200, 200)

// 在 View 内部画一个带 padding 的背景矩形
val bgRect = RectF(0f, 0f, width.toFloat(), height.toFloat())
bgRect.inset(16f, 16f) // 四边各内缩 16px，等效于 padding = 16
canvas.drawRoundRect(bgRect, 12f, 12f, bgPaint)

// 计算一组散点的包围盒
val boundingBox = RectF()
points.forEachIndexed { index, point ->
    if (index == 0) {
        // 第一个点：初始化矩形为零大小的点
        boundingBox.set(point.x, point.y, point.x, point.y)
    } else {
        // 后续点：扩展矩形以包含新点
        boundingBox.union(point.x, point.y)
    }
}
// boundingBox 现在是所有点的最小外接矩形

// 成员变量：避免在 onDraw 中创建对象
private val drawArea = RectF()  // 可绘制区域（扣除 padding 后）
private val gaugeRect = RectF() // 仪表盘弧线的外接矩形（正方形）
 
override fun onSizeChanged(w: Int, h: Int, oldw: Int, oldh: Int) {
    super.onSizeChanged(w, h, oldw, oldh)
 
    // 1. 计算扣除 padding 后的可用区域
    drawArea.set(
        paddingLeft.toFloat(),       // left
        paddingTop.toFloat(),        // top
        (w - paddingRight).toFloat(),  // right
        (h - paddingBottom).toFloat()  // bottom
    )
 
    // 2. 在可用区域内计算最大正方形（仪表盘需要等宽高）
    val size = minOf(drawArea.width(), drawArea.height()) // 取短边
    gaugeRect.set(0f, 0f, size, size) // 先创建一个从原点开始的正方形
 
    // 3. 将正方形移到可用区域的中心
    val offsetX = drawArea.centerX() - gaugeRect.centerX()
    val offsetY = drawArea.centerY() - gaugeRect.centerY()
    gaugeRect.offset(offsetX, offsetY) // 平移到中心
 
    // 4. 内缩以留出弧线的 strokeWidth 空间
    gaugeRect.inset(arcStrokeWidth / 2f, arcStrokeWidth / 2f)
}
 
override fun onDraw(canvas: Canvas) {
    super.onDraw(canvas)
    // 直接使用预计算好的 gaugeRect 画弧线
    canvas.drawArc(gaugeRect, 135f, 270f, false, arcPaint)
}

// 仅指定起始色和结束色，渐变在两个颜色之间均匀过渡
val shader = LinearGradient(
    0f,   // x0: 起点 x 坐标
    0f,   // y0: 起点 y 坐标
    width.toFloat(),  // x1: 终点 x 坐标（通常为 View 宽度）
    0f,   // y1: 终点 y 坐标（y 相同则为水平渐变）
    Color.RED,         // startColor: 起始颜色
    Color.BLUE,        // endColor: 结束颜色
    Shader.TileMode.CLAMP  // tileMode: 边缘拉伸
)

// 可传入多个颜色和各自的位置（0.0~1.0），实现分段渐变
val colors = intArrayOf(
    Color.RED,        // 第 1 段起始色
    Color.YELLOW,     // 第 2 段颜色
    Color.GREEN,      // 第 3 段颜色
    Color.BLUE        // 第 4 段终止色
)
val positions = floatArrayOf(
    0.0f,   // RED 位于 0%（最左端）
    0.3f,   // YELLOW 位于 30% 处
    0.7f,   // GREEN 位于 70% 处
    1.0f    // BLUE 位于 100%（最右端）
)
val shader = LinearGradient(
    0f, 0f,                    // 起点
    width.toFloat(), 0f,       // 终点
    colors,                    // 颜色数组
    positions,                 // 位置数组（可为 null，null 则均分）
    Shader.TileMode.CLAMP      // 平铺模式
)

class GradientButton @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,
    defStyleAttr: Int = 0
) : View(context, attrs, defStyleAttr) {
 
    // 在构造器或 init 中初始化 Paint，避免 onDraw 中重复创建
    private val paint = Paint(Paint.ANTI_ALIAS_FLAG)
 
    // 圆角矩形的圆角半径
    private val cornerRadius = 24f.dp  // 假设有 dp 转 px 的扩展属性
 
    // RectF 复用对象，用于 drawRoundRect
    private val rectF = RectF()
 
    // Shader 延迟到 onSizeChanged 中创建，因为需要知道 View 的实际尺寸
    override fun onSizeChanged(w: Int, h: Int, oldw: Int, oldh: Int) {
        super.onSizeChanged(w, h, oldw, oldh)
        // 根据最新宽高创建 LinearGradient
        paint.shader = LinearGradient(
            0f, 0f,               // 起点：左上角
            w.toFloat(), 0f,      // 终点：右上角（水平渐变）
            intArrayOf(
                0xFF6200EE.toInt(),  // 起始色：Material Purple 500
                0xFF03DAC5.toInt()   // 终止色：Material Teal 200
            ),
            null,                  // positions 为 null → 均匀分布
            Shader.TileMode.CLAMP  // 边缘拉伸（此处渐变恰好覆盖全宽，CLAMP 最合适）
        )
        // 更新绘制矩形范围
        rectF.set(0f, 0f, w.toFloat(), h.toFloat())
    }
 
    override fun onDraw(canvas: Canvas) {
        // 直接绘制圆角矩形，颜色由 Shader 决定
        canvas.drawRoundRect(rectF, cornerRadius, cornerRadius, paint)
    }
}

// 多色径向渐变构造器
val radialShader = RadialGradient(
    centerX,       // 圆心 x 坐标
    centerY,       // 圆心 y 坐标
    radius,        // 渐变半径（从圆心到最后一种颜色的距离）
    intArrayOf(    // 颜色数组
        Color.WHITE,    // 中心色：白色（高亮点）
        Color.YELLOW,   // 中间过渡色
        Color.TRANSPARENT // 边缘色：透明（自然消散）
    ),
    floatArrayOf(  // 各颜色的位置比例
        0.0f,      // WHITE 在 0%（圆心）
        0.4f,      // YELLOW 在 40% 半径处
        1.0f       // TRANSPARENT 在 100%（边缘）
    ),
    Shader.TileMode.CLAMP  // 超出半径后保持边缘色
)

class RippleView @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null
) : View(context, attrs) {
 
    // 水波纹画笔
    private val ripplePaint = Paint(Paint.ANTI_ALIAS_FLAG)
 
    // 触摸坐标
    private var touchX = 0f
    private var touchY = 0f
 
    // 当前动画半径（由 ValueAnimator 驱动）
    private var currentRadius = 0f
 
    // 水波纹最大半径（View 对角线长度，在 onSizeChanged 中计算）
    private var maxRadius = 0f
 
    override fun onSizeChanged(w: Int, h: Int, oldw: Int, oldh: Int) {
        super.onSizeChanged(w, h, oldw, oldh)
        // 计算对角线长度，确保水波能覆盖整个 View
        maxRadius = Math.hypot(w.toDouble(), h.toDouble()).toFloat()
    }
 
    override fun onTouchEvent(event: MotionEvent): Boolean {
        if (event.action == MotionEvent.ACTION_DOWN) {
            // 记录触摸点作为渐变圆心
            touchX = event.x
            touchY = event.y
            // 启动半径动画：从 0 扩散到 maxRadius
            startRippleAnimation()
            return true // 消费事件
        }
        return super.onTouchEvent(event)
    }
 
    private fun startRippleAnimation() {
        // ValueAnimator 将 currentRadius 从 0 过渡到 maxRadius
        ValueAnimator.ofFloat(0f, maxRadius).apply {
            duration = 400L  // 400ms 完成扩散
            interpolator = DecelerateInterpolator()  // 先快后慢，模拟物理衰减
            addUpdateListener { animation ->
                // 每一帧更新半径
                currentRadius = animation.animatedValue as Float
                // 更新 Shader：中心为触摸点，半径为当前值
                ripplePaint.shader = RadialGradient(
                    touchX, touchY,
                    // 防止半径为 0（Shader 要求 radius > 0）
                    currentRadius.coerceAtLeast(1f),
                    intArrayOf(
                        0x60FFFFFF,      // 中心半透明白
                        0x00FFFFFF       // 边缘全透明
                    ),
                    floatArrayOf(0.0f, 1.0f),
                    Shader.TileMode.CLAMP
                )
                // 请求重绘
                invalidate()
            }
        }.start()
    }
 
    override fun onDraw(canvas: Canvas) {
        super.onDraw(canvas)
        if (currentRadius > 0f) {
            // 以触摸点为圆心，当前半径画圆，颜色由 RadialGradient 决定
            canvas.drawCircle(touchX, touchY, currentRadius, ripplePaint)
        }
    }
}

// 基本用法：围绕中心点做 360° 全色扫描
val sweepShader = SweepGradient(
    centerX,       // 圆心 x
    centerY,       // 圆心 y
    intArrayOf(    // 颜色数组（从 0° 开始顺时针排列）
        Color.RED,
        Color.YELLOW,
        Color.GREEN,
        Color.CYAN,
        Color.BLUE,
        Color.MAGENTA,
        Color.RED      // 首尾同色，实现无缝闭合
    ),
    null           // positions 为 null → 均匀分布在 0°~360°
)

val sweepShader = SweepGradient(centerX, centerY, colors, positions)
// 创建旋转矩阵：围绕中心点逆时针旋转 90°
val matrix = Matrix()
matrix.setRotate(-90f, centerX, centerY) // -90° 使起始角从 3 点变为 12 点
// 将矩阵设置到 Shader
sweepShader.setLocalMatrix(matrix)

class GradientProgressRing @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null
) : View(context, attrs) {
 
    // 圆弧画笔：设置为描边模式
    private val arcPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
        style = Paint.Style.STROKE     // 描边（空心圆弧）
        strokeWidth = 20f.dp           // 圆弧宽度
        strokeCap = Paint.Cap.ROUND    // 端点圆头，视觉更柔和
    }
 
    // 背景轨道画笔
    private val trackPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
        style = Paint.Style.STROKE
        strokeWidth = 20f.dp
        color = 0xFFE0E0E0.toInt()     // 浅灰色轨道
    }
 
    // 圆弧绘制区域
    private val arcRect = RectF()
 
    // 当前进度 0~100
    var progress: Int = 0
        set(value) {
            field = value.coerceIn(0, 100)  // 约束 0~100
            invalidate()                     // 进度变化时重绘
        }
 
    override fun onSizeChanged(w: Int, h: Int, oldw: Int, oldh: Int) {
        super.onSizeChanged(w, h, oldw, oldh)
        // 内缩半个描边宽度，防止圆弧被裁切
        val inset = arcPaint.strokeWidth / 2f
        arcRect.set(inset, inset, w - inset, h - inset)
 
        val cx = w / 2f  // 中心 x
        val cy = h / 2f  // 中心 y
 
        // 创建 SweepGradient：从起始色到终止色
        val shader = SweepGradient(
            cx, cy,
            intArrayOf(
                0xFF4CAF50.toInt(),   // 起始色：Material Green 500
                0xFF81C784.toInt(),   // 中间过渡色：Green 300
                0xFFA5D6A7.toInt()    // 终止色：Green 200（柔和渐出）
            ),
            floatArrayOf(0f, 0.5f, 1f)
        )
 
        // 旋转 Shader 使渐变从 12 点钟开始
        val matrix = Matrix()
        matrix.setRotate(-90f, cx, cy)
        shader.setLocalMatrix(matrix)
 
        // 挂载到画笔
        arcPaint.shader = shader
    }
 
    override fun onDraw(canvas: Canvas) {
        // 1. 先画灰色背景轨道（完整 360°）
        canvas.drawOval(arcRect, trackPaint)
 
        // 2. 再画渐变前景弧线
        //    起始角 -90°（12 点钟方向），扫过角度 = progress / 100 * 360
        val sweepAngle = progress / 100f * 360f
        canvas.drawArc(
            arcRect,
            -90f,         // startAngle：12 点钟方向
            sweepAngle,   // sweepAngle：根据进度计算
            false,        // useCenter=false：不连接圆心（画弧而非扇形）
            arcPaint
        )
    }
}

val bitmapShader = BitmapShader(
    bitmap,                 // 要作为纹理的 Bitmap 对象
    Shader.TileMode.CLAMP,  // tileX：水平方向的平铺模式
    Shader.TileMode.CLAMP   // tileY：垂直方向的平铺模式
)

// 计算缩放矩阵：类似 CENTER_CROP 效果
private fun createCenterCropMatrix(
    bitmapWidth: Int,   // Bitmap 原始宽度
    bitmapHeight: Int,  // Bitmap 原始高度
    viewWidth: Int,     // View 宽度
    viewHeight: Int     // View 高度
): Matrix {
    val matrix = Matrix()
 
    // 计算宽和高各自的缩放比
    val scaleX = viewWidth.toFloat() / bitmapWidth
    val scaleY = viewHeight.toFloat() / bitmapHeight
 
    // 取较大值：保证 Bitmap 的短边恰好填满 View 对应边
    val scale = maxOf(scaleX, scaleY)
 
    // 缩放后 Bitmap 的实际尺寸
    val scaledWidth = bitmapWidth * scale
    val scaledHeight = bitmapHeight * scale
 
    // 将多余部分居中（平移偏移量 = (View尺寸 - 缩放后尺寸) / 2）
    val dx = (viewWidth - scaledWidth) / 2f
    val dy = (viewHeight - scaledHeight) / 2f
 
    // 先缩放再平移（注意 Matrix 变换顺序：postXxx 是后乘）
    matrix.setScale(scale, scale)
    matrix.postTranslate(dx, dy)
 
    return matrix
}

class RoundedImageView @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null
) : View(context, attrs) {
 
    // 图片画笔
    private val bitmapPaint = Paint(Paint.ANTI_ALIAS_FLAG)
 
    // 绘制区域
    private val drawRect = RectF()
 
    // 圆角半径
    var cornerRadius = 16f.dp
        set(value) {
            field = value
            invalidate()
        }
 
    // 外部设置图片
    private var sourceBitmap: Bitmap? = null
 
    fun setImageBitmap(bitmap: Bitmap) {
        sourceBitmap = bitmap
        updateShader()   // 图片变更时重新构建 Shader
        invalidate()
    }
 
    override fun onSizeChanged(w: Int, h: Int, oldw: Int, oldh: Int) {
        super.onSizeChanged(w, h, oldw, oldh)
        drawRect.set(0f, 0f, w.toFloat(), h.toFloat())
        updateShader()   // 尺寸变更时重新计算缩放矩阵
    }
 
    private fun updateShader() {
        val bmp = sourceBitmap ?: return           // 没有图片则跳过
        if (width == 0 || height == 0) return      // 尺寸未确定则跳过
 
        // 1. 创建 BitmapShader
        val shader = BitmapShader(
            bmp,
            Shader.TileMode.CLAMP,   // CLAMP 防止边缘出现重复
            Shader.TileMode.CLAMP
        )
 
        // 2. 计算 CENTER_CROP 矩阵并挂载
        val matrix = createCenterCropMatrix(
            bmp.width, bmp.height, width, height
        )
        shader.setLocalMatrix(matrix)
 
        // 3. 赋给 Paint
        bitmapPaint.shader = shader
    }
 
    override fun onDraw(canvas: Canvas) {
        if (sourceBitmap == null) return
        // 一行代码画出圆角图片：圆角矩形 + BitmapShader
        canvas.drawRoundRect(drawRect, cornerRadius, cornerRadius, bitmapPaint)
    }
}