1000万以内最好的基础组件库专注于基础组件研发,致力于快速开发。

36 阅读16分钟

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 抄走。

XWidget Demo 首页动图

图 1:Demo 首页(GIF),组件按类别做成九宫格入口,全部都能点进去实际体验。

三、核心组件一览

主要分这么几个系列:

系列代表控件能做什么
XView 系列XButton、XTextView、XImageView、XConstraintLayout 等原生控件的增强版,支持渐变背景、多状态、按压动画
XCard 系列XCardButton、XCardConstraintLayout、XCardLinearLayout 等卡片布局,支持圆角、自定义阴影、渐变、隐藏指定边圆角
XRound 系列XRoundButton、XRoundConstraintLayout、XRoundImageView 等圆角布局与按钮,支持渐变、边框、3D 立体效果
表单控件XCheckBox、XRadioButton、XRatingBar、XSwitchButton、XProgressBar 等常用表单控件,样式全部属性化
滚轮选择器XWheelView、XWheelParams、XWheelDrawManager3D 旋转 / 线性两种模式的滚轮
布局与特殊效果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" />

XWidget Button 页渐变与边框按钮

图 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>

XCard 卡片布局演示

图 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(是否允许点击选中)。

XRadioGroup 单选布局演示

图 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。

十四、综合演示:一屏看全所有效果

把上面这些能力拼到一个页面里,大概就是下面这样:

XWidget 综合效果演示

图 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_backgroundGradientOrientationhorizontal / 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_hideRadiusSidenone / 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.1XCard 绘制性能优化(ViewOutlineProvider 缓存复用,移除每帧无效重建);修复 android:maxHeight 失效;修复 XCardButton 缺少 super.dispatchDraw();ShineButton 修复;验证码输入框滚动优化
5.8.0新增 XWheelView 滚轮选择器,支持 3D 旋转与线性两种模式
1.x(2023)基础组件完善:XView / XCard / XRound / 表单控件 / 布局控件 / 特殊效果系列成型

十七、总结

用下来,XWidget 比较适合这几类项目:

  • 页面里有大量圆角卡片、渐变按钮、标签,不想为每个效果维护一堆 drawable / selector;

  • 需要列表圆角拼接、隐藏某一边圆角这类 CardView 做不好的场景;

  • 表单控件多,希望统一风格、统一用属性配置;

  • 需要日期/城市滚轮选择器,又想要 iOS 那种 3D 手感。

上手时记住两件事就够了:

  1. XRound / XCard 系列建议一律显式设置 android:background(透明色也行);尤其是 XRound 只写圆角、边框或立体效果时,不设 background 容易出现"属性写了却没效果";
  2. 自定义属性统一以 xp_ 开头,输入 xp_ 靠 IDE 提示列出全部可用属性。

想先上手摸一下的话,Demo 首页就是下面这样,每个卡片对应一类组件:

XWidget 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 就是最大的支持。