Android 组件库 XWidget 实战:圆角、渐变、阴影、多状态,少写 drawable 和 selector,还有 3D 滚轮
@toc
-
一句话:圆角、渐变、边框、阴影、多状态、3D 立体,全部写成 XML 属性,
res/drawable里能少几十个bg_xxx.xml。 -
适用:Android 原生 View 体系,示例以 XML + Kotlin 为主,Java 项目同样可用。
-
版本:XWidget 5.8.1,Maven Central 可直接依赖。
一、为什么会有 XWidget
做 Android UI 的同学大概都经历过这样的流程:一个"圆角 + 渐变 + 按下变色"的按钮,要先写一个圆角 shape drawable,再写一个按压态的 drawable,然后用 selector 把两个状态串起来;如果还想要阴影,就再套一层 CardView 或者 layer-list;想要渐变边框,又是另一个 layer-list。
一个页面下来,res/drawable 里全是 bg_xxx_normal、bg_xxx_pressed、bg_xxx_disabled。设计师一句"主色换了",就得全局搜索替换一下午;更难受的是 XML 预览里看不到最终效果,只能一遍遍装包看真机。
XWidget 想解决的就是这件事:把圆角、渐变、边框、阴影、按压/选中/禁用状态、3D 立体这些"效果",全部变成 XML 属性——不写 drawable、不写 selector,XML 预览里就能看到效果。
这个库从 2020 年底持续维护到现在(当前版本 5.8.1),已经发布在 Maven Central,组件覆盖按钮、卡片、图片、表单、滚轮选择器、嵌套滚动和一批工具类。项目地址:GitHub - pichsy/xwidget。
二、先看效果
下面这个 GIF 是 Demo 的首页:组件按类别做成九宫格入口,底部是自定义的导航栏。每个入口点进去都是可交互的 Demo,不少页面还能拖滑杆实时调圆角、阴影、颜色,调好之后直接把页面下方的 XML 抄走。
图 1:Demo 首页(GIF),组件按类别做成九宫格入口,全部都能点进去实际体验。
三、核心组件一览
主要分这么几个系列:
| 系列 | 代表控件 | 能做什么 |
|---|---|---|
| XView 系列 | XButton、XTextView、XImageView、XConstraintLayout 等 | 原生控件的增强版,支持渐变背景、多状态、按压动画 |
| XCard 系列 | XCardButton、XCardConstraintLayout、XCardLinearLayout 等 | 卡片布局,支持圆角、自定义阴影、渐变、隐藏指定边圆角 |
| XRound 系列 | XRoundButton、XRoundConstraintLayout、XRoundImageView 等 | 圆角布局与按钮,支持渐变、边框、3D 立体效果 |
| 表单控件 | XCheckBox、XRadioButton、XRatingBar、XSwitchButton、XProgressBar 等 | 常用表单控件,样式全部属性化 |
| 滚轮选择器 | XWheelView、XWheelParams、XWheelDrawManager | 3D 旋转 / 线性两种模式的滚轮 |
| 布局与特殊效果 | XFlowLayout、XNestedScrollLayout、ShineButton、XPressScaleLinearLayout 等 | 流式布局、嵌套滚动、闪光按钮、按压缩放 |
| 工具类 | XStatusBarHelper、XTypefaceHelper、XGradientHelper 等 | 状态栏、全局字体、渐变、颜色、屏幕、设备信息 |
四、快速接入
在模块的 build.gradle(或 build.gradle.kts)里加一行依赖:
dependencies {
implementation 'com.gitee.pichs:xwidget:5.8.1'
}
Kotlin DSL(build.gradle.kts):
dependencies {
implementation("com.gitee.pichs:xwidget:5.8.1")
}
如果项目还没配置 Maven Central 仓库:
repositories {
mavenCentral()
}
新版 Android Studio 创建的项目默认已经包含
mavenCentral(),可以先确认一下,没有再加。
混淆规则(proguard-rules.pro):
-keep class com.pichs.xwidget.** { *; }
依赖的 groupId 是
com.gitee.pichs,代码包名是com.pichs.xwidget,两者不一致是历史原因,不是引错了库。
库的最低支持版本是 Android 8.0(minSdk 26),compileSdk 35,基于原生 View 体系,Java 和 Kotlin 项目都能直接使用。
五、必读:background 到底要不要设?
README 和详细文档里都有一条提醒:XRound / XCard 系列想用渐变、边框,必须先设置 android:background。这条建议的出发点是"按最严格的情况写",但对着 5.8.1 的源码逐行看,实际行为要分情况——照抄可能让你多写没用的 background,也可能在真正需要它的地方漏掉。
| 场景 | 需要 background 吗 | 原因 |
|---|---|---|
| XRound 渐变背景 | 不需要 | 内部会根据 xp_backgroundGradient* 直接构建 GradientDrawable |
| XRound 单独边框(无渐变) | 需要 | 边框画在这张 GradientDrawable 上;没有 background 也没有渐变时 drawable 为 null,边框不显示 |
| XRound 单独立体(无渐变 / 背景) | 需要 | 立体侧面要叠在主面 drawable 上,主面为空就不会渲染 |
| XRound / XCard 纯色底 + 圆角 | 需要(background 写颜色) | 纯色由 background 承载,圆角才会跟着出现 |
| XCard 的渐变 / 边框 / 阴影 | 不需要 | 边框、阴影由 XLayoutHelper 直接绘制,渐变由父类 XBackgroundHelper 解析 |
| XCard / XRoundImageView:只想用圆角裁切内容 | 不需要 | XCard 走 outline,XRoundImageView 走 canvas.clipPath() |
XRoundButton / XRoundTextView / XRound*Layout:只配 xp_radius | 需要 | 圆角只作用在背景 drawable 上;没有 background、也没有渐变时 drawable 为 null,圆角不显示(布局也不会裁剪子 View) |
Demo 里就有现成的反例:Button 页第一排的渐变按钮(app/src/main/res/layout/fragment_button.xml)并没有设置 android:background,截图里的渐变是正常的(可以对照图 2)。真正会"静默失效"的,是只配 xp_radius、只设置边框、只设置立体效果这类没有 background / 渐变兜底的情况:
<!-- ❌ 只有边框、没有 background:边框不会显示 -->
<com.pichs.xwidget.roundview.XRoundButton
android:layout_width="120dp"
android:layout_height="48dp"
android:text="按钮"
app:xp_radius="8dp"
app:xp_borderColor="#E0E0E0"
app:xp_borderWidth="1dp" />
<!-- ✅ 加一个 background(透明色也算),边框正常 -->
<com.pichs.xwidget.roundview.XRoundButton
android:layout_width="120dp"
android:layout_height="48dp"
android:text="按钮"
android:background="@android:color/transparent"
app:xp_radius="8dp"
app:xp_borderColor="#E0E0E0"
app:xp_borderWidth="1dp" />
所以更准确的口诀是:有渐变就不必强行写 background;只写圆角(XRoundButton / 布局)、边框、立体或纯色底时,background 不能省。
当然,如果你不想记这些边界条件,最省心的办法仍然是显式设置 android:background(透明色或具体颜色都行)——本文后面的示例也统一这么写,图省事,而且不会错。
XView 系列(
XButton、XTextView、XImageView)是另一套背景实现,渐变和状态背景本来就不需要额外设置 background。
六、XRound 系列:圆角 + 渐变 + 立体效果
痛点:圆角按钮要建 drawable;四角不同圆角、渐变、立体效果,每个都要单独一套文件。
解决方案:改成几行属性。
<com.pichs.xwidget.roundview.XRoundButton
android:layout_width="wrap_content"
android:layout_height="48dp"
android:paddingStart="24dp"
android:paddingEnd="24dp"
android:text="圆角按钮"
android:textColor="#FFFFFF"
android:background="@android:color/transparent"
app:xp_radius="24dp"
app:xp_backgroundGradientColors="#667eea,#764ba2"
app:xp_backgroundGradientOrientation="TL_BR" />
四个角可以独立设置:
app:xp_radiusTopLeft="16dp"
app:xp_radiusTopRight="16dp"
app:xp_radiusBottomLeft="0dp"
app:xp_radiusBottomRight="0dp"
想做更有质感的 3D 立体按钮,XRound 系列还支持给"侧面"单独设颜色和高度:
<com.pichs.xwidget.roundview.XRoundButton
android:layout_width="150dp"
android:layout_height="60dp"
android:text="3D 效果"
android:textColor="#FFFFFF"
android:textSize="18sp"
android:background="@android:color/transparent"
app:xp_radius="30dp"
app:xp_backgroundGradientColors="#667eea,#764ba2"
app:xp_backgroundGradientOrientation="TL_BR"
app:xp_cubeSidesGradientColors="#5568d3,#6441a5"
app:xp_cubeFrontHeight="6dp"
app:xp_cubeBackHeight="4dp"
app:xp_cubeLeftHeight="5dp"
app:xp_cubeRightHeight="5dp"
app:xp_cubeSidesBorderColor="#4a5cc5"
app:xp_cubeSidesBorderWidth="2dp"
app:xp_pressedScale="0.92" />
图 2:Demo 的 Button 页,从上到下依次是渐变、阴影、边框、渐变边框等效果,截图下半部分就是生成这些按钮的 XML。
七、XCard 系列:卡片布局与自定义阴影
Material 的 CardView 阴影颜色只能靠 elevation 间接控制,想改颜色很麻烦;列表场景里想让中间项隐藏某一边的圆角,CardView 也做不到。XCard 系列继承自原生布局,原生属性全部保留,又补上了圆角、阴影、渐变和"隐藏指定边圆角"。
<com.pichs.xwidget.cardview.XCardConstraintLayout
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:background="#FFFFFF"
app:xp_radius="12dp"
app:xp_shadowElevation="4dp"
app:xp_shadowColor="#40000000"
app:xp_backgroundGradientStartColor="#FFFFFF"
app:xp_backgroundGradientEndColor="#F5F5F5"
app:xp_backgroundGradientOrientation="vertical">
<!-- 卡片内容 -->
</com.pichs.xwidget.cardview.XCardConstraintLayout>
这里 android:background="#FFFFFF" 是给卡片填底色;XCard 的渐变、边框、阴影并不依赖它(原因见第五节)。另外,xp_shadowColor 依赖系统的 setOutlineSpotShadowColor / setOutlineAmbientShadowColor,Android 9.0(API 28)及以上才生效;在 API 26/27 上阴影颜色会被静默忽略,xp_shadowElevation 不受影响。
边框也可以做渐变:
app:xp_borderWidth="1dp"
app:xp_borderGradientStartColor="#FF6B6B"
app:xp_borderGradientEndColor="#4ECDC4"
app:xp_borderGradientOrientation="TL_BR"
列表场景特别实用:xp_hideRadiusSide 支持 none / top / right / bottom / left,列表中间项把相邻边的圆角藏掉,视觉上就能拼成一整块:
<com.pichs.xwidget.cardview.XCardLinearLayout
android:layout_width="match_parent"
android:layout_height="60dp"
android:background="#FFFFFF"
app:xp_radius="12dp"
app:xp_hideRadiusSide="top"
app:xp_shadowElevation="2dp">
<!-- 列表项内容 -->
</com.pichs.xwidget.cardview.XCardLinearLayout>
图 3:Demo 的"卡片布局"页,滑杆分别控制圆角、阴影颜色、阴影高度和背景颜色,调完直接对照下方 XML。
八、多状态:一个控件顶一套 selector
痛点:按压、选中、禁用三套状态,就要写三个 drawable 加一个 selector,状态越多文件越多。
解决方案:状态直接写在属性上。以 XRoundButton 为例(它同时支持圆角与状态背景):
<com.pichs.xwidget.roundview.XRoundButton
android:layout_width="match_parent"
android:layout_height="48dp"
android:text="多状态按钮"
android:textColor="#FFFFFF"
android:background="@android:color/transparent"
app:xp_radius="8dp"
app:xp_backgroundGradientColors="#3498DB,#2980B9"
app:xp_pressedBackgroundGradientColors="#E74C3C,#C0392B"
app:xp_checkedBackgroundGradientColors="#27AE60,#229954"
app:xp_disabledBackgroundGradientColors="#95A5A6,#7F8C8D"
app:xp_pressedScale="0.95"
app:xp_pressedAlpha="0.8" />
支持的状态:
-
normal:
xp_background...系列 -
pressed:
xp_pressedBackground...,配合xp_pressedScale、xp_pressedAlpha -
checked:
xp_checkedBackground...,配合xp_checkedTextColor -
activated:
xp_activatedBackground... -
disabled:
xp_disabledBackground...,配合xp_disabledAlpha、xp_disabledScale
渐变色有两种写法:xp_backgroundGradientStartColor + xp_backgroundGradientEndColor 两色,或者 xp_backgroundGradientColors="#a,#b,#c" 多色。渐变方向支持 horizontal、vertical、TL_BR、BL_TR 四种。
补充一句:
XButton、XTextView这些 XView 系列控件同样支持状态背景和渐变,但它们本身不支持xp_radius圆角属性;需要圆角时用 XRound / XCard 系列。
九、XCircleImageView / XRoundImageView:圆形头像与圆角图片
以前做圆形头像要引 CircleImageView,圆角图要么挂 Glide 的 Transform,要么自己写 BitmapShader。XWidget 把这两件事拆成了两个控件:XCircleImageView 管圆形头像,XRoundImageView 管圆角图,边框也都能直接配属性。
圆形头像用 XCircleImageView,自带描边:
<com.pichs.xwidget.roundview.XCircleImageView
android:layout_width="80dp"
android:layout_height="80dp"
android:src="@drawable/avatar"
app:xp_borderWidth="2dp"
app:xp_borderColor="#FFFFFF" />
圆角图片用 XRoundImageView:
<com.pichs.xwidget.roundview.XRoundImageView
android:layout_width="160dp"
android:layout_height="100dp"
android:scaleType="centerCrop"
android:src="@drawable/image"
app:xp_radius="12dp" />
<!-- 四角分别设置 -->
<com.pichs.xwidget.roundview.XRoundImageView
android:layout_width="50dp"
android:layout_height="50dp"
android:background="#FFFFFF"
android:src="@drawable/avatar"
app:xp_radiusTopLeft="25dp"
app:xp_radiusTopRight="25dp"
app:xp_radiusBottomLeft="25dp"
app:xp_radiusBottomRight="25dp" />
一个小细节:XRoundImageView 的边框是画在背景上的,如果图片不透明且完全铺满,边框会被盖住。想要描边效果,可以给图片留一点 padding,或者直接用上面的 XCircleImageView。
十、XWheelView:iOS 风格的 3D 滚轮选择器
系统 NumberPicker 样式比较老,三方滚轮库要么只有 2D 效果,要么快速滑动时掉帧。XWheelView 基于 RecyclerView 实现,支持 3D 旋转和线性两种绘制模式,垂直、水平方向都可以。
先在布局里声明(@+id/wheel_view),再在代码里设置数据:
<com.pichs.xwidget.wheel.XWheelView
android:id="@+id/wheel_view"
android:layout_width="match_parent"
android:layout_height="200dp"
app:xp_wheelOrientation="vertical"
app:xp_wheelItemCount="5"
app:xp_wheelItemSize="50dp"
app:xp_wheelTextSize="20sp"
app:xp_wheelTextColor="#AAAAAA"
app:xp_wheelTextCenterColor="#FF6B6B"
app:xp_wheelDividerColor="#4ECDC4"
app:xp_wheelDividerSize="2dp"
app:xp_wheelGradient="true"
app:xp_wheelGravity="center"
app:xp_wheelTextSelectedBold="true"
app:xp_wheelTextNormalBold="false" />
// wheelView = findViewById<XWheelView>(R.id.wheel_view)
wheelView.setAdapter(object : XWheelView.Adapter() {
private val data = listOf("选项 1", "选项 2", "选项 3", "XWidget", "滚轮")
override fun getItemCount() = data.size
override fun getItem(position: Int) = data[position]
})
wheelView.addOnItemSelectedListener { _, index ->
Log.d("WheelView", "当前选中:$index")
}
不想要 3D 旋转效果,换成线性绘制器就行。方式二:纯代码创建(线性模式,不需要 XML):
val params = XWheelParams.Builder()
.setOrientation(XWheelParams.VERTICAL)
.setItemCount(3)
.setItemSize(XDisplayHelper.dp2px(context, 40f))
.setTextSize(XDisplayHelper.sp2px(context, 16f).toFloat())
.setTextColor(Color.parseColor("#666666"))
.setTextCenterColor(Color.parseColor("#000000"))
.setDividerColor(Color.parseColor("#E0E0E0"))
.setDividerSize(XDisplayHelper.dp2px(context, 1f))
.setGradient(true)
.build()
// 线性模式:只做透明度渐变,不做旋转
val wheelView = XWheelView(
context,
params,
XWheelLinearDrawManager(),
XWheelView.SimpleItemPainter()
)
// 运行时也能切换绘制管理器
wheelView.setDrawManager(XWheelDrawManager())
关键属性:xp_wheelItemCount 是中心项两侧各几个 item(默认 3),滚轮内部总 item 数为 2n+1;一屏实际能看到多少个,还取决于控件高度和 xp_wheelItemSize。xp_wheelTextCenterColor 是中心项的高亮色,xp_wheelGradient 控制是否开启两侧透明度渐变。
十一、表单控件全家桶
表单控件是业务里写得最多、也最容易写烦的一类。XWidget 里常用的都有,属性风格保持一致。
复选框
XCheckBox 用 android:src + xp_checked_src 切换选中/未选中两张图,圆角同样走 xp_radius:
<com.pichs.xwidget.checkbox.XCheckBox
android:layout_width="50dp"
android:layout_height="50dp"
android:src="@drawable/ic_unchecked"
app:xp_checked_src="@drawable/ic_checked"
app:xp_radius="8dp"
app:xp_clickable="true" />
想要动画就用 XSmoothCheckBox,对勾和填充都有过渡效果:
<com.pichs.xwidget.checkbox.XSmoothCheckBox
android:layout_width="wrap_content"
android:layout_height="wrap_content"
app:xp_cbox_duration="300"
app:xp_cbox_color_tick="@android:color/white"
app:xp_cbox_color_checked="@color/colorPrimary"
app:xp_cbox_color_unchecked_stroke="#DFDFDF"
app:xp_cbox_stroke_width="2dp" />
单选按钮与单选组
父容器用 XCardLinearRadioGroup,子项用 XRadioCardButton,选中状态由组统一管理:
<com.pichs.xwidget.radiogroup.XCardLinearRadioGroup
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:orientation="vertical"
android:background="#FFFFFF"
app:xp_radius="12dp">
<com.pichs.xwidget.radiobutton.XRadioCardButton
android:layout_width="match_parent"
android:layout_height="48dp"
android:text="选项一" />
<com.pichs.xwidget.radiobutton.XRadioCardButton
android:layout_width="match_parent"
android:layout_height="48dp"
android:text="选项二" />
</com.pichs.xwidget.radiogroup.XCardLinearRadioGroup>
单选控件还支持几个实用开关:xp_ignore_radio_group(忽略父单选组独立工作)、xp_check_state_follow_parent(选中状态跟随父控件)、xp_checked_by_click(是否允许点击选中)。
图 4:Demo 的"单选布局"页,包含约束布局单选组、忽略 RadioGroup 的独立按钮,以及父容器与子控件的联动。
图 5:单选控件的选中切换动画(GIF)。
Demo 的"单选布局"页用的是约束布局版本 XConstraintRadioGroup,需要约束布局时把上面的容器换掉即可,子项写法不变。
评分条
支持半星、可只读、可改星星圆角:
<com.pichs.xwidget.ratingbar.XRatingBar
android:layout_width="wrap_content"
android:layout_height="wrap_content"
app:xp_starCount="5"
app:xp_starSize="30dp"
app:xp_starProgress="3.5"
app:xp_starStep="0.5"
app:xp_starSelectedColor="#FFC619"
app:xp_starNormalColor="#DDDDDD"
app:xp_borderColor="#BF961A"
app:xp_borderWidth="1dp"
app:xp_starCornerRadius="12dp"
app:xp_isIndicator="false"
app:xp_ratingGravity="left" />
xp_starStep="0.5" 支持半星,xp_isIndicator="true" 可以变成纯展示的评分指示器。
开关
<com.pichs.xwidget.switcher.XSwitchButton
android:layout_width="60dp"
android:layout_height="30dp"
app:xp_swb_thumbColor="#FFFFFF"
app:xp_swb_backgroundColor_switchOn="#4CAF50"
app:xp_swb_backgroundColor_switchOff="#CCCCCC"
app:xp_swb_thumbRadius="14dp"
app:xp_swb_backgroundRadius="15dp"
app:xp_swb_animationDuration="250"
app:xp_swb_thumbRangeRatio="1.8"
app:xp_swb_text_switchOn="开"
app:xp_swb_text_switchOff="关" />
进度条
支持 rect / circle / roundRect 三种形态:
<com.pichs.xwidget.progressbar.XProgressBar
android:layout_width="200dp"
android:layout_height="20dp"
app:xp_progressType="roundRect"
app:xp_progressColor="#4CAF50"
app:xp_backgroundColor="#E0E0E0"
app:xp_maxValue="100"
app:xp_value="60" />
xp_strokeWidth和xp_strokeRoundCap只在circle类型下生效(rect/roundRect是填充绘制,没有描边概念);进度文字需要配合setXProgressBarTextGenerator才会绘制:
progressBar.setXProgressBarTextGenerator { _, value, max -> "$value / $max" }
除此之外,还有 XInputLayout(带清除按钮的输入布局)、XVerificationCodeEditText(验证码输入框,5.8.1 版本专门优化了滚动顺滑度)、XEditText 等。
十二、布局控件与特殊效果
除了常规控件,还有几类"用了就回不去"的辅助控件:
-
XFlowLayout:流式布局,做标签云、搜索历史很方便;
-
XNestedScrollLayout:嵌套滚动(顶部固定 + 中间滚动 + 底部固定),内置可拖拽滚动条
XDraggableScrollBar; -
ShineButton:闪光按钮,收藏、点赞场景直接用;
-
XPressScale 系列(
XPressScaleLinearLayout/XPressScaleFrameLayout/XPressScaleConstraintLayout):按压缩放容器,一整个布局都能跟着缩放; -
XSpace / XStatusBarSpace / XStatusBarView:占位控件,沉浸式状态栏必备;
-
XWebView:增强 WebView。
流式布局示例(标签用 XRoundButton,background 提供填充色,圆角走 xp_radius):
<com.pichs.xwidget.flowlayout.XFlowLayout
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:padding="16dp"
app:xp_childHorizontalSpacing="8dp"
app:xp_childVerticalSpacing="8dp"
app:xp_maxNumber="10"
android:maxLines="3">
<com.pichs.xwidget.roundview.XRoundButton
android:layout_width="wrap_content"
android:layout_height="32dp"
android:background="#F5F5F5"
android:text="标签一"
android:textColor="#333333"
app:xp_radius="16dp" />
<com.pichs.xwidget.roundview.XRoundButton
android:layout_width="wrap_content"
android:layout_height="32dp"
android:background="#F5F5F5"
android:text="标签二"
android:textColor="#333333"
app:xp_radius="16dp" />
</com.pichs.xwidget.flowlayout.XFlowLayout>
占位控件大概是沉浸式页面里最常用的小工具之一:顶部需要一块和状态栏等高的区域,XStatusBarSpace 自动计算高度,XStatusBarView 还能顺便把背景色铺上,普通留白用 XSpace 即可。
<!-- 状态栏占位:高度自动等于状态栏高度 -->
<com.pichs.xwidget.space.XStatusBarSpace
android:layout_width="match_parent"
android:layout_height="wrap_content" />
<!-- 带背景的状态栏占位 -->
<com.pichs.xwidget.view.XStatusBarView
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:background="#FF0000" />
<!-- 普通占位:自定义高度 -->
<com.pichs.xwidget.space.XSpace
android:layout_width="match_parent"
android:layout_height="80dp" />
图 6:Demo 的"占空布局"页,XStatusBarSpace 自动取状态栏高度、XStatusBarView 额外铺背景色、XSpace 自定义高度,三块效果对比,下半部分是 XML 示例。
十三、全局字体切换:一行代码换掉整个 App 的字体
如果产品要做"大字模式"或者"品牌字体",一个个控件设字体显然不现实。XTypefaceHelper 的思路是:在 Application 里开启全局字体监听,之后所有支持该能力的 XWidget 控件都会自动跟着变。
class App : Application() {
override fun onCreate() {
super.onCreate()
XTypefaceHelper.init(this, true)
}
}
切换字体:
// assets 目录下的字体
XTypefaceHelper.setGlobalTypefaceFromAssets(context, "custom_font.ttf")
// res/font 下的字体资源(换成你自己工程里的字体)
XTypefaceHelper.setGlobalTypefaceFromFontRes(context, R.font.your_font)
// 只改字体样式:NONE / NORMAL / BOLD / ITALIC / BOLD_ITALIC
XTypefaceHelper.setGlobalTypefaceStyle(context, XTypefaceHelper.NONE)
// 恢复默认字体
XTypefaceHelper.resetTypeface(context)
// 关闭 / 开启全局字体
XTypefaceHelper.closeTypeface(context)
XTypefaceHelper.openTypeface(context)
如果某个控件不想跟着全局字体变,加一个属性即可:
<com.pichs.xwidget.view.XTextView
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="忽略字体文件变化"
app:xp_ignoreGlobalTypeface="true" />
图 7:Demo 的字体页:一键切换得意黑 / 雷鸿字体、恢复默认,以及不跟随全局字体变化的 XTextView。
十四、综合演示:一屏看全所有效果
把上面这些能力拼到一个页面里,大概就是下面这样:
图 8:综合演示页。顶部红色是 XStatusBarView 自动计算的状态栏占位,其余按钮分别标注了按压透明度、放大/缩小、变矮、凹陷、立体等效果,还有多色渐变、Card 圆角剪裁、带清除按钮的输入框和 XWebView。
这张图其实可以当"目录"来用,和图里的元素对应一下:
-
顶部红色状态栏 → 第十二节的
XStatusBarView; -
字体按钮、忽略字体变化 → 第十三节的
XTypefaceHelper与xp_ignoreGlobalTypeface; -
多色渐变、立体效果、按压变矮/凹陷 → 第六节的 XRound 系列与第八节的多状态;
-
Card 圆角剪裁 → 第七节的 XCard;
-
带清除按钮的输入框 → 第十一节提到的
XInputLayout。
这些效果基本都是属性直接生成的,没有为它们单独写 drawable。
十五、常用属性速查
写布局时对着查就行。先看圆角、边框和渐变:
| 属性 | 说明 |
|---|---|
xp_radius | 统一圆角半径 |
xp_radiusTopLeft / xp_radiusTopRight / xp_radiusBottomLeft / xp_radiusBottomRight | 四角独立圆角(XRound 系列) |
xp_borderColor / xp_borderWidth | 边框颜色与宽度(XRound / XCard 系列) |
xp_borderGradientStartColor / xp_borderGradientEndColor / xp_borderGradientOrientation | 渐变边框,配合 xp_borderWidth(XCard 系列) |
xp_backgroundGradientStartColor / xp_backgroundGradientEndColor | 两色渐变背景 |
xp_backgroundGradientColors | 多色渐变,如 #FF6B6B,#4ECDC4,#45B7D1 |
xp_backgroundGradientOrientation | horizontal / vertical / TL_BR / BL_TR |
状态与动画:
| 属性 | 说明 |
|---|---|
xp_pressedBackgroundGradientColors | 按压态渐变 |
xp_checkedBackgroundGradientColors | 选中态渐变 |
xp_activatedBackgroundGradientColors | 激活态渐变 |
xp_disabledBackgroundGradientColors | 禁用态渐变 |
xp_pressedScale / xp_pressedAlpha | 按压缩放比例 / 透明度 |
xp_disabledScale / xp_disabledAlpha | 禁用态缩放比例 / 透明度 |
xp_checkedTextColor / xp_pressedTextColor | 选中 / 按压时文字颜色 |
阴影、立体与其他:
| 属性 | 说明 |
|---|---|
xp_shadowElevation / xp_shadowColor / xp_shadowAlpha | 阴影高度 / 颜色 / 透明度(XCard 系列) |
xp_hideRadiusSide | none / top / right / bottom / left(XCard 系列) |
xp_cubeFrontHeight / xp_cubeBackHeight / xp_cubeLeftHeight / xp_cubeRightHeight | 四个方向的立体面高度(XRound 系列) |
xp_cubeSidesGradientColors / xp_cubeSidesBorderColor / xp_cubeSidesBorderWidth | 立体侧面渐变与描边 |
xp_topDividerHeight / xp_bottomDividerHeight | 顶部 / 底部分割线高度(XCard 系列) |
xp_isRadiusAdjustBounds | 按最小边自动取半圆(XCard 系列,如 XCardImageView) |
xp_ignoreGlobalTypeface | 忽略全局字体变化(文本类控件) |
这只是最常用的一批属性,状态类还有
xp_pressedTextColor、xp_disabledAlpha等等,滚轮、表单控件也各有独立前缀(xp_wheel驼峰、xp_star、xp_swb_、xp_cbox_,如xp_wheelItemCount),完整列表见仓库里的详细文档.md。
十六、版本与更新
当前版本是 5.8.1(2026-07-29),最近的更新主要集中在性能和几个历史遗留 bug 上:
| 版本 | 主要内容 |
|---|---|
| 5.8.1 | XCard 绘制性能优化(ViewOutlineProvider 缓存复用,移除每帧无效重建);修复 android:maxHeight 失效;修复 XCardButton 缺少 super.dispatchDraw();ShineButton 修复;验证码输入框滚动优化 |
| 5.8.0 | 新增 XWheelView 滚轮选择器,支持 3D 旋转与线性两种模式 |
| 1.x(2023) | 基础组件完善:XView / XCard / XRound / 表单控件 / 布局控件 / 特殊效果系列成型 |
十七、总结
用下来,XWidget 比较适合这几类项目:
-
页面里有大量圆角卡片、渐变按钮、标签,不想为每个效果维护一堆 drawable / selector;
-
需要列表圆角拼接、隐藏某一边圆角这类 CardView 做不好的场景;
-
表单控件多,希望统一风格、统一用属性配置;
-
需要日期/城市滚轮选择器,又想要 iOS 那种 3D 手感。
上手时记住两件事就够了:
- XRound / XCard 系列建议一律显式设置
android:background(透明色也行);尤其是 XRound 只写圆角、边框或立体效果时,不设 background 容易出现"属性写了却没效果"; - 自定义属性统一以
xp_开头,输入xp_靠 IDE 提示列出全部可用属性。
想先上手摸一下的话,Demo 首页就是下面这样,每个卡片对应一类组件:
图 9:Demo 首页把组件按类别做成入口,点击任意卡片即可进入对应组件的演示页面。
最后放几个链接:
-
GitHub:pichsy/xwidget
-
依赖:
com.gitee.pichs:xwidget:5.8.1 -
Demo:
app模块可直接运行;仓库里自带的app/release/app-release.apk是较早的 5.6.3 版本,想体验 5.8.1 的新组件建议直接跑源码 -
详细文档与更新日志都在仓库里,Issue / PR 都欢迎
如果这个库帮你少写了几个 drawable,去 GitHub 点个 ⭐️ Star 就是最大的支持。