安卓自定义属性实战：从GradientButton设计到商用组件封装

1. 项目概述：为什么“自定义属性”是安卓开发绕不开的硬功夫

你有没有遇到过这样的场景：写了一个漂亮的圆形进度条控件，同事想在布局里直接用app:progress="75"设置初始值，结果报错说这个属性不存在？或者你封装了一个带标题栏的通用卡片容器，老板提需求要支持“标题文字粗细可配”“阴影强度分级控制”，你却只能改Java代码、重新编译、发版——而UI同学连XML里改个颜色都要等你半天？这些不是小问题，而是安卓视图层抽象能力的分水岭。自定义属性（Custom Attributes），就是让自定义控件真正“活”起来的关键开关。它不是炫技，而是把控件从“写死逻辑的黑盒”变成“可配置、可复用、可协作”的标准组件。我带过的几个团队里，新人常以为“能画出来就行”，但真正上线后维护成本飙升的，90%都卡在没设计好属性体系——比如一个按钮控件，只暴露了text和clickListener，却没预留iconPosition（图标在左/右/上/下）、rippleColor（水波纹颜色）、disabledAlpha（禁用态透明度）这些真实业务中高频调整的参数。结果每次改UI都要动代码，测试要全量回归，版本迭代像踩雷。这篇文章不讲XML语法基础，也不堆砌API文档，而是带你从一个真实项目出发：我们手写一个支持渐变色背景、圆角自适应、边框虚实切换、点击反馈可控的GradientButton，全程拆解属性怎么定义、怎么解析、怎么和Java/Kotlin逻辑联动、怎么避免常见坑。你会看到，属性不是“加个attr.xml就完事”，而是涉及资源解析时机、TypedArray生命周期、主题继承链、甚至Kotlin委托属性的底层协作。如果你正在封装SDK、做中台组件库，或者只是想让自己的简历多一行“具备高质量UI组件设计经验”，那这一关必须亲手过一遍。

2. 核心设计思路：属性不是越多越好，而是要“对得上业务节奏”

2.1 属性分类法：按修改频率和影响范围划出三道线

很多开发者一上来就列十几二十个属性，结果维护时自己都记不清哪个是干啥的。我用三年时间沉淀出一套属性分层法，核心就一句话：属性的价值 = （被修改次数 × 影响范围） / 定义复杂度。按这个公式，我把属性分成三类，每类对应不同的设计策略：

• 高频刚需型（红线级）：如app:backgroundGradient（渐变色）、app:cornerRadius（圆角）、app:strokeWidth（边框宽度）。这类属性必须支持XML直接设置、代码动态修改、主题全局覆盖，且要保证性能无损。比如cornerRadius，如果每次setRadius都触发invalidate()重绘，列表滚动时会掉帧，所以必须用LayerDrawable预生成圆角层，属性变更时只替换drawable而非重绘整个View。

• 中频配置型（黄线级）：如app:strokeDashGap（虚线间隔）、app:rippleEnabled（是否启用点击反馈）。这类属性允许轻微性能妥协，但必须提供默认值和清晰的文档说明。特别注意rippleEnabled这种布尔型属性，不能简单写android:attr="?android:attr/selectableItemBackground"，因为主题可能未定义该属性，需fallback到纯色背景，否则在某些定制ROM上直接崩溃。

• 低频调试型（蓝线级）：如app:debugOutlineColor（仅开发阶段显示轮廓线）、app:measureMode（测量模式枚举）。这类属性绝不进正式包，必须用BuildConfig.DEBUG包裹，且在attrs.xml中用format="enum"明确限定取值，避免UI同学误填"true"导致解析失败。

提示：我在某电商App的购物车按钮组件中，曾把app:cartBadgeCount（购物车角标数字）设为高频型，结果发现运营活动期间该值每小时变一次，后端通过下发JSON动态更新，根本不需要XML配置。于是果断降级为代码API，XML里只保留app:badgeVisible（是否显示角标）这个布尔开关。这说明：属性设计必须跟着实际交付流程走，而不是对着UI稿脑补。

2.2 命名规范：别让同事猜你的缩写是什么

属性命名不是小事。我见过最离谱的是app:btnBgGrd——三个缩写连在一起，新来的同学查了半小时源码才明白是“button background gradient”。安卓官方推荐用camelCase，但光这样不够。我的铁律是：属性名 = 业务语义 + 技术维度 + 单位（如适用）。例如：

• ✅app:cornerRadius（圆角半径，单位dp，符合Material Design规范）
• ✅app:strokeWidth（边框宽度，单位dp，和Android原生strokeWidth一致）
• ✅app:gradientAngle（渐变角度，单位degrees，明确区别于rotation）

而这些是反例：

• ❌app:bgGrad（bg=background？grad=gradient？还是gradient？）
• ❌app:corner（corner什么？半径？直径？弧度？）
• ❌app:angle（哪个角度？旋转角？渐变角？阴影角？）

更关键的是，所有属性必须在res/values/attrs.xml中用<attr>标签明确定义format。比如cornerRadius必须写format="dimension"，这样IDE才能在XML里自动提示单位（dp/sp），编译时也能校验非法值（如"red"）。我试过把format="integer"错写成format="string"，结果运行时TypedArray.getDimension()返回0，按钮圆角永远是0，排查了两天才发现是attr定义错了。

2.3 主题继承链：为什么你的属性在某些手机上不生效

很多人抱怨“在小米手机上属性失效，在华为上正常”，其实根源在主题继承链。安卓的TypedArray解析不是简单读XML，而是按优先级顺序合并：当前View的style → 父级Theme → Application Theme → System Theme。比如你定义了app:cornerRadius="8dp"，但父级Theme里有<item name="cornerRadius">16dp</item>，那么最终生效的是16dp。更隐蔽的是，某些厂商ROM会重写系统Theme，把?android:attr/colorAccent映射到自家主题色，如果你的属性依赖这个，行为就会不可控。

解决方案只有两个：

1. 显式声明依赖：在attrs.xml中为每个属性添加<attr name="cornerRadius" format="dimension" />，并确保所有使用该属性的控件都通过Context.obtainStyledAttributes()获取，而不是硬编码。
2. 强制隔离主题：在自定义控件构造函数中，用ContextThemeWrapper包装Context，指定一个纯净的Base.Theme，彻底切断厂商Theme干扰。代码如下：

class GradientButton @JvmOverloads constructor( context: Context, attrs: AttributeSet? = null, defStyleAttr: Int = 0 ) : AppCompatButton( ContextThemeWrapper(context, R.style.Base_Theme_AppCompat), // 强制使用AppCompat基础主题 attrs, defStyleAttr ) { // 后续逻辑... }

实测下来，这招在OPPO、vivo的深色模式适配中效果显著，避免了因厂商主题覆盖导致的渐变色异常。

3. 核心实现细节：从XML解析到属性联动的完整链路

3.1 attrs.xml定义：格式、命名空间与版本兼容性

attrs.xml是整个链条的起点，但90%的坑都埋在这里。先看一个典型错误写法：

<!-- 错误：缺少namespace声明，且format写错 --> <resources> <declare-styleable name="GradientButton"> <attr name="cornerRadius" format="integer" /> <attr name="gradientStartColor" format="color" /> </declare-styleable> </resources>

问题有三：

1. format="integer"应为format="dimension"：cornerRadius单位是dp，getDimension()方法需要dimension类型，否则返回0；
2. 缺少tools:ignore="PrivateResource"：Android Studio会警告私有资源，加这行可消除误报；
3. 未声明targetSdkVersion兼容性：Android 12+要求<attr>必须有format，否则编译失败。

正确写法如下（含注释说明）：

<?xml version="1.0" encoding="utf-8"?> <resources xmlns:tools="http://schemas.android.com/tools"> <!-- GradientButton控件专用属性集 --> <declare-styleable name="GradientButton"> <!-- 圆角半径，单位dp，支持主题继承 --> <attr name="cornerRadius" format="dimension" /> <!-- 渐变起始颜色，支持color资源引用（@color/red）和十六进制（#FF0000） --> <attr name="gradientStartColor" format="color" /> <!-- 渐变结束颜色，同上 --> <attr name="gradientEndColor" format="color" /> <!-- 边框宽度，单位dp --> <attr name="strokeWidth" format="dimension" /> <!-- 边框颜色，支持透明度 --> <attr name="strokeColor" format="color" /> <!-- 渐变角度，单位degrees，0=左到右，90=下到上 --> <attr name="gradientAngle" format="integer" /> <!-- 是否启用点击水波纹效果 --> <attr name="rippleEnabled" format="boolean" /> <!-- 水波纹颜色，仅当rippleEnabled=true时生效 --> <attr name="rippleColor" format="color" /> </declare-styleable> </resources>

注意：gradientAngle用format="integer"而非format="dimension"，因为角度是纯数值，不需要单位转换。getInteger()方法直接返回int值，比getDimension()少一次单位换算，性能更好。

3.2 构造函数解析：TypedArray的生命周期与内存陷阱

解析属性的核心是TypedArray，但它是个“一次性消耗品”。很多开发者在onDraw()里反复调用context.obtainStyledAttributes()，结果OOM。正确姿势是：在构造函数中一次性解析，存为成员变量，后续直接读取。以下是GradientButton的构造函数完整实现：

class GradientButton @JvmOverloads constructor( context: Context, attrs: AttributeSet? = null, defStyleAttr: Int = R.attr.gradientButtonStyle ) : AppCompatButton(context, attrs, defStyleAttr) { // 成员变量存储解析后的属性值 private var cornerRadius: Float = 0f private var gradientStartColor: Int = Color.TRANSPARENT private var gradientEndColor: Int = Color.TRANSPARENT private var strokeWidth: Float = 0f private var strokeColor: Int = Color.TRANSPARENT private var gradientAngle: Int = 0 private var rippleEnabled: Boolean = true private var rippleColor: Int = Color.parseColor("#40000000") init { // 1. 获取TypedArray，注意第三个参数是defStyleAttr，指向主题中的默认样式 val a = context.theme.obtainStyledAttributes( attrs, R.styleable.GradientButton, // 对应attrs.xml中的declare-styleable defStyleAttr, R.style.Widget_AppCompat_Button // 默认样式，兜底用 ) try { // 2. 逐个解析属性，务必用getXXX()方法，不要用getIndex() cornerRadius = a.getDimension(R.styleable.GradientButton_cornerRadius, 0f) gradientStartColor = a.getColor(R.styleable.GradientButton_gradientStartColor, Color.TRANSPARENT) gradientEndColor = a.getColor(R.styleable.GradientButton_gradientEndColor, Color.TRANSPARENT) strokeWidth = a.getDimension(R.styleable.GradientButton_strokeWidth, 0f) strokeColor = a.getColor(R.styleable.GradientButton_strokeColor, Color.TRANSPARENT) gradientAngle = a.getInteger(R.styleable.GradientButton_gradientAngle, 0) rippleEnabled = a.getBoolean(R.styleable.GradientButton_rippleEnabled, true) rippleColor = a.getColor(R.styleable.GradientButton_rippleColor, Color.parseColor("#40000000")) } finally { // 3. 关键！必须调用recycle()释放TypedArray，否则内存泄漏 a.recycle() } // 4. 初始化绘制相关对象（Paint、Shader等） initPaint() } private fun initPaint() { // 创建渐变Shader，角度需转为Canvas坐标系（Canvas角度=90-gradAngle） val angleInCanvas = 90 - gradientAngle val shader = LinearGradient( 0f, 0f, width.toFloat(), height.toFloat(), gradientStartColor, gradientEndColor, Shader.TileMode.CLAMP ) // ... 其他初始化逻辑 } }

实操心得：a.recycle()不是可选项，而是必选项。我曾在线上版本漏掉这行，用户滑动列表时TypedArray对象堆积，GC频繁，ANR率上升12%。另外，defStyleAttr参数很重要——它指向主题中定义的默认样式，比如你在themes.xml里写<item name="gradientButtonStyle">@style/Widget.MyApp.GradientButton</item>，那么所有未显式设置属性的GradientButton都会自动应用这个样式，实现“一处定义，全局生效”。

3.3 属性动态更新：如何让setCornerRadius()实时生效

静态解析只是第一步，真正的难点是动态更新。比如UI同学在代码里调用button.setCornerRadius(16f)，界面必须立刻刷新。这里有两个陷阱：

1. invalidate()vsrequestLayout()：cornerRadius只影响背景绘制，不改变View尺寸，所以只需invalidate()重绘，不用requestLayout()触发测量布局，否则列表滚动会卡顿；
2. 属性变更监听缺失：Kotlin的var属性没有setter拦截，必须手动重写setter。

正确实现如下：

// 在GradientButton类中添加 var cornerRadius: Float get() = _cornerRadius set(value) { if (_cornerRadius != value) { _cornerRadius = value // 重建圆角背景Drawable updateBackgroundDrawable() // 只重绘，不重布局 invalidate() } } private var _cornerRadius: Float = 0f private fun updateBackgroundDrawable() { // 1. 创建LayerDrawable，第一层是渐变背景，第二层是边框 val layers = mutableListOf<Drawable>() // 渐变背景层 val gradient = GradientDrawable().apply { colors = intArrayOf(gradientStartColor, gradientEndColor) orientation = when (gradientAngle) { 0 -> GradientDrawable.Orientation.LEFT_RIGHT 90 -> GradientDrawable.Orientation.TOP_BOTTOM else -> GradientDrawable.Orientation.BL_TR } cornerRadius = _cornerRadius } layers.add(gradient) // 边框层（如果strokeWidth > 0） if (strokeWidth > 0) { val stroke = GradientDrawable().apply { setColor(strokeColor) shape = GradientDrawable.RECTANGLE cornerRadius = _cornerRadius } // 用InsetDrawable给边框留出内边距 val inset = InsetDrawable(stroke, strokeWidth.toInt(), strokeWidth.toInt(), strokeWidth.toInt(), strokeWidth.toInt() ) layers.add(inset) } // 设置为背景 background = LayerDrawable(layers.toTypedArray()) }

注意：updateBackgroundDrawable()里用LayerDrawable组合渐变和边框，比用ShapeDrawable叠加更高效。实测在低端机上，LayerDrawable重绘耗时比setBackgroundColor()低40%，因为避免了多次onDraw()调用。

3.4 主题与样式集成：让设计师也能玩转你的控件

再好的属性，如果设计师不会用，等于白搭。我给团队定的规范是：每个自定义控件必须配套3个标准样式：

• Widget.MyApp.Button.Gradient（默认样式，含基础属性）
• Widget.MyApp.Button.Gradient.Primary（主按钮，高饱和度渐变）
• Widget.MyApp.Button.Gradient.Secondary（次按钮，低对比度）

styles.xml示例：

<style name="Widget.MyApp.Button.Gradient" parent="Widget.AppCompat.Button"> <item name="cornerRadius">8dp</item> <item name="gradientStartColor">@color/gradient_start_blue</item> <item name="gradientEndColor">@color/gradient_end_blue</item> <item name="strokeWidth">1dp</item> <item name="strokeColor">@color/stroke_gray</item> <item name="gradientAngle">0</item> <item name="rippleEnabled">true</item> </style> <style name="Widget.MyApp.Button.Gradient.Primary" parent="Widget.MyApp.Button.Gradient"> <item name="gradientStartColor">@color/primary_start</item> <item name="gradientEndColor">@color/primary_end</item> <item name="strokeColor">@color/primary_stroke</item> </style>

然后在布局XML中，设计师只需写：

<com.myapp.widget.GradientButton android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="立即购买" style="@style/Widget.MyApp.Button.Gradient.Primary" />

这样既保证了UI一致性，又避免了重复写属性。更重要的是，当设计规范升级（比如圆角从8dp改为12dp），只需改styles.xml，所有使用该样式的按钮自动更新，零代码修改。

4. 实操全流程：从零开始创建一个可商用的GradientButton

4.1 第一步：创建attrs.xml并定义属性集

新建res/values/attrs.xml，粘贴前面定义的<declare-styleable>代码。注意：name="GradientButton"必须和控件类名完全一致（大小写敏感），否则R.styleable.GradientButton_cornerRadius会编译报错。这是新手最常见的错误，IDE不会提示，只有编译时才报cannot find symbol。

4.2 第二步：编写GradientButton类（Kotlin版）

完整代码如下（已去除无关注释，保留核心逻辑）：

class GradientButton @JvmOverloads constructor( context: Context, attrs: AttributeSet? = null, defStyleAttr: Int = R.attr.gradientButtonStyle ) : AppCompatButton(context, attrs, defStyleAttr) { private var _cornerRadius: Float = 0f private var _gradientStartColor: Int = Color.TRANSPARENT private var _gradientEndColor: Int = Color.TRANSPARENT private var _strokeWidth: Float = 0f private var _strokeColor: Int = Color.TRANSPARENT private var _gradientAngle: Int = 0 private var _rippleEnabled: Boolean = true private var _rippleColor: Int = Color.parseColor("#40000000") // 属性getter/setter，支持Kotlin委托 var cornerRadius: Float get() = _cornerRadius set(value) { if (_cornerRadius != value) { _cornerRadius = value updateBackground() invalidate() } } var gradientStartColor: Int get() = _gradientStartColor set(value) { if (_gradientStartColor != value) { _gradientStartColor = value updateBackground() invalidate() } } // 其他属性类似，此处省略... init { val a = context.theme.obtainStyledAttributes( attrs, R.styleable.GradientButton, defStyleAttr, R.style.Widget_AppCompat_Button ) try { _cornerRadius = a.getDimension(R.styleable.GradientButton_cornerRadius, 0f) _gradientStartColor = a.getColor(R.styleable.GradientButton_gradientStartColor, Color.TRANSPARENT) _gradientEndColor = a.getColor(R.styleable.GradientButton_gradientEndColor, Color.TRANSPARENT) _strokeWidth = a.getDimension(R.styleable.GradientButton_strokeWidth, 0f) _strokeColor = a.getColor(R.styleable.GradientButton_strokeColor, Color.TRANSPARENT) _gradientAngle = a.getInteger(R.styleable.GradientButton_gradientAngle, 0) _rippleEnabled = a.getBoolean(R.styleable.GradientButton_rippleEnabled, true) _rippleColor = a.getColor(R.styleable.GradientButton_rippleColor, Color.parseColor("#40000000")) } finally { a.recycle() } // 初始化点击反馈 if (_rippleEnabled) { val ripple = RippleDrawable( ColorStateList.valueOf(_rippleColor), null, null ) foreground = ripple } } private fun updateBackground() { val layers = mutableListOf<Drawable>() // 渐变层 val gradient = GradientDrawable().apply { colors = intArrayOf(_gradientStartColor, _gradientEndColor) orientation = when (_gradientAngle) { 0 -> GradientDrawable.Orientation.LEFT_RIGHT 90 -> GradientDrawable.Orientation.TOP_BOTTOM else -> GradientDrawable.Orientation.BL_TR } cornerRadius = _cornerRadius } layers.add(gradient) // 边框层 if (_strokeWidth > 0) { val stroke = GradientDrawable().apply { setColor(_strokeColor) shape = GradientDrawable.RECTANGLE cornerRadius = _cornerRadius } val inset = InsetDrawable(stroke, _strokeWidth.toInt(), _strokeWidth.toInt(), _strokeWidth.toInt(), _strokeWidth.toInt() ) layers.add(inset) } background = LayerDrawable(layers.toTypedArray()) } // 重写onMeasure，支持wrap_content时根据文字内容计算最小尺寸 override fun onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int) { super.onMeasure(widthMeasureSpec, heightMeasureSpec) val width = measuredWidth val height = measuredHeight // 如果是wrap_content，确保最小尺寸不小于48dp（符合Material触控区规范） val minWidth = resources.getDimensionPixelSize(R.dimen.min_touch_target) val minHeight = resources.getDimensionPixelSize(R.dimen.min_touch_target) setMeasuredDimension( max(width, minWidth), max(height, minHeight) ) } }

关键点：onMeasure()里做了最小触控区保护，这是无障碍访问（Accessibility）的硬性要求。R.dimen.min_touch_target在dimens.xml中定义为48dp，确保按钮足够大，方便手指点击。

4.3 第三步：在布局中使用并验证

新建activity_main.xml，添加以下代码：

<LinearLayout 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" android:orientation="vertical" android:padding="16dp"> <!-- 使用自定义属性 --> <com.myapp.widget.GradientButton android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="主按钮" app:cornerRadius="12dp" app:gradientStartColor="#FF4081" app:gradientEndColor="#3F51B5" app:strokeWidth="2dp" app:strokeColor="#E0E0E0" app:gradientAngle="45" /> <!-- 使用主题样式 --> <com.myapp.widget.GradientButton android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="次按钮" style="@style/Widget.MyApp.Button.Gradient.Secondary" /> </LinearLayout>

运行后，你会看到两个按钮：第一个完全由XML属性控制，第二个由主题样式驱动。此时可以尝试：

• 修改app:cornerRadius="24dp"，观察圆角实时变大；
• 在代码中调用button.gradientStartColor = Color.RED，按钮渐变立即变化；
• 切换深色模式，检查@color/gradient_start_blue是否自动替换为深色版本（需在values-night/colors.xml中定义对应色值）。

4.4 第四步：发布为AAR并接入其他模块

当控件稳定后，可打包为AAR供其他模块复用。步骤如下：

1. 在build.gradle（Module级别）中添加：

android { // ... 其他配置 libraryVariants.all { variant -> variant.outputs.all { outputFileName = "gradient-button-${variant.versionName}.aar" } } }

2. 执行./gradlew assembleRelease，生成build/outputs/aar/gradient-button-1.0.0.aar；
3. 将AAR放入公司Maven仓库，或直接拷贝到其他模块的libs/目录；
4. 在其他模块的build.gradle中添加：

implementation(name: 'gradient-button-1.0.0', ext: 'aar')

注意：AAR中必须包含res/values/attrs.xml，否则引用方会报No resource found。我曾因忘记在AAR中打包attrs.xml，导致合作团队集成失败，排查了3小时才发现是资源缺失。

5. 常见问题与避坑指南：那些文档里不会写的血泪教训

5.1 典型问题速查表

5.2 高阶避坑技巧

技巧1：用format="reference|color"支持主题色引用
很多开发者只写format="color"，导致无法使用?attr/colorPrimary。正确写法：

<attr name="gradientStartColor" format="reference|color" />

这样XML中即可写：

app:gradientStartColor="?attr/colorPrimary"

解析时用a.getColor()仍可正常工作，getColor()会自动解析?attr引用。

技巧2：为布尔属性提供双向绑定支持
Kotlin中可结合PropertyDelegate实现bind：

class GradientButton(...) : AppCompatButton(...) { var isRippleEnabled: Boolean by Delegates.observable(true) { _, old, new -> if (old != new) { _rippleEnabled = new updateRipple() } } }

这样在DataBinding中可直接写：

<com.myapp.widget.GradientButton app:isRippleEnabled="@={viewModel.isRippleOn}" />

技巧3：用@IntDef约束枚举型属性
对于gradientAngle，可定义安全枚举：

@Retention(RetentionPolicy.SOURCE) @IntDef({GRADIENT_ANGLE_LEFT_RIGHT, GRADIENT_ANGLE_TOP_BOTTOM}) public @interface GradientAngle {} public static final int GRADIENT_ANGLE_LEFT_RIGHT = 0; public static final int GRADIENT_ANGLE_TOP_BOTTOM = 90;

然后在attrs.xml中：

<attr name="gradientAngle" format="integer"> <enum name="left_right" value="0" /> <enum name="top_bottom" value="90" /> </attr>

这样XML中输入app:gradientAngle="left_right"，IDE会自动提示，避免拼写错误。

5.3 性能监控实战：如何证明你的控件不拖慢APP

上线前必须做性能验证。我用的方案是：

1. Systrace抓帧：在列表中快速滑动，用adb shell systrace.py --time=10 -a com.myapp ui render抓10秒trace，重点看View#draw耗时是否<16ms；
2. Memory Profiler监控：打开Activity，反复创建/销毁GradientButton，观察GradientDrawable实例数是否稳定（不应持续增长）；
3. StrictMode检测：在Application中开启detectDiskReads()，确保attrs.xml解析不触发IO。

实测数据：在Redmi Note 9（入门级机型）上，单个GradientButton的onDraw()平均耗时3.2ms，列表滚动帧率稳定在58fps，符合性能基线。

6. 进阶扩展：从单控件到组件化体系的演进路径

6.1 属性复用：建立跨控件的属性标准

当你有多个自定义控件（如GradientTextView、GradientCardView）时，属性命名必须统一。我制定的《UI组件属性公约》规定：

• 所有圆角相关属性统一用cornerRadius，禁用roundCorner、radius等别名；
• 所有边框相关属性统一用strokeWidth/strokeColor，禁用borderWidth/borderColor；
• 所有渐变相关属性统一用gradientStartColor/gradientEndColor/gradientAngle。

这样做的好处是：设计师写Figma插件时，只需维护一套属性映射规则；前端同学对接Flutter时，属性名可1:1转换；自动化测试脚本也无需为每个控件单独写断言。

6.2 动态属性：用LiveData实现属性响应式更新

对于需要响应式更新的场景（如主题色随用户偏好实时变化），可将属性包装为LiveData：

class GradientButton(...) : AppCompatButton(...) { private val _cornerRadiusLiveData = MutableLiveData<Float>() val cornerRadiusLiveData: LiveData<Float> = _cornerRadiusLiveData fun setCornerRadiusLive(value: Float) { _cornerRadiusLiveData.value = value } // 在init中观察 _cornerRadiusLiveData.observeForever { radius -> this.cornerRadius = radius } }

这样在ViewModel中即可：

viewModel.themeRadius.observe(this) { radius -> button.setCornerRadiusLive(radius) }

6.3 跨平台延伸：属性体系如何平滑迁移到Flutter

Flutter的CustomPaint控件虽无XML，但属性设计思想相通。我团队的做法是：

• Android的app:cornerRadius→ Flutter的cornerRadius: 12.0（double类型）；
• Android的app:gradientStartColor→ Flutter的startColor: Colors.red（Color类型）；
• 所有属性名、单位、默认值保持一致，降低双端协同成本。

最后分享一个小技巧：我在attrs.xml中为每个属性添加<annotation name="flutter_equivalent">cornerRadius</annotation>，用脚本自动生成Flutter文档，效率提升70%。

我个人在实际封装中发现，属性设计最耗时的不是写代码，而是和UI、产品、测试三方对齐“这个属性到底要不要加”。建议每次新增属性前，先问三个问题：

1. 这个属性在最近3个需求中被修改过几次？
2. 如果不加，UI同学要改几行代码？测试要回归几个用例？
3. 加了之后，会不会让控件变得难以理解？

答案都是“是”，才动手。毕竟，好的自定义属性，不是功能越多越好，而是让复杂的事情变简单，让简单的事情变自然。