史上最优美的Android原生UI框架XUI使用指南

古城微笑少年丶 2022-11-21 14:43 2357阅读 0赞

![0ef711fe573d553ee1d53289f87796b9.png][]

## 项目简介 ##

> [XUI][]是一个简洁而又优雅的Android原生UI框架，解放你的双手！

[XUI][]可以说是我花费心血最多的开源项目了，目前稍微大一点的项目我都会选择引入它。XUI几乎涵盖了目前Android开发所需要的所有组件，可以说有了XUI之后，可以大大提高我们的开发效率，让我们可以将精力很多地放在业务功能和数据处理上。可以说XUI是目前Github上组件最全、文档最详细、案例(200+)数量最多的Android原生UI库。

目前XUI在github上已经拥有2.6k的star量, 如果你喜欢的话,欢迎点击star收藏! 项目地址: [https://github.com/xuexiangjys/XUI][XUI]

### 设计原由 ###

相信做过Android的人都知道Android原生组件在国内很不受设计师的待见，至于Google推行的Material Design设计风格更是无人问津，这就导致了设计师给出的原型图几乎是清一色的IOS风格，更尴尬的是，网上Android相关的开源UI库是少之又少，这可就为难死我们了，几乎所有的基础组件都需要自己重写。之前也写过React和Vue，发现它们都有非常方便的UI库，而且使用起来也非常方便，直接在示例代码的基础上修修改改就能大致上实现自己想要的效果，极大地提高了开发的效率。

### 设计思路 ###

在开始着手做这样一个开源库之前，我是一点思路都没有的。好在在2017年的某一天，我接触到了[QMUI][],通过阅读它的源码，我发现它的设计思路非常好，可以通过设置不同的主题样式、组件属性等实现不同的组件效果，非常灵活；除此之外，它还对UI主题风格做了较为详细的制定和归类，可以说很有启发意义。于是我就遵循了QMUI的思路，开启了XUI的编写。

### 解决痛点 ###

*  简洁优雅，尽可能少得引用资源文件的数量，项目库整体大小不足1M。
 *  组件丰富，提供了绝大多数我们在开发者常用的功能组件。
 *  使用简单，为方便快速开发，提高开发效率，对api进行了优化，提供一键式接入。
 *  样式统一，框架提供了一系列统一的样式，使UI整体看上去美观和谐。
 *  兼容性高，框架还提供了3种不同尺寸设备的样式（4.5英寸、7英寸和10英寸），并且最低兼容到Android 17, 让UI兼容性更强。
 *  扩展性强，各组件提供了丰富的属性和样式API，可以通过设置不同的样式属性，构建不同风格的UI。

--------------------

## 演示项目 ##

> 通过查看演示Demo的实现，可以快速高效地掌握UI组件的使用。

### 项目架构 ###

> 项目页面主要使用[XPage][]页面框架自动搭建，结构非常清晰。项目主要分为"组件"、"工具"和"拓展"三个部分。

*  组件：组件页面主要包含了UI框架中所有组件的使用Demo样例，在`"com.xuexiang.xuidemo.fragment.components"`包下，[点击查看][Link 1]。
 *  工具：工具页面主要包含了UI框架中所有辅助工具的使用Demo样例，在`"com.xuexiang.xuidemo.fragment.utils"`包下，[点击查看][Link 2]。
 *  拓展：扩展页面主要包含了功能比较复杂的第三方UI组件集成Demo样例，在`"com.xuexiang.xuidemo.fragment.expands"`包下，[点击查看][Link 3]

项目结构如下图：

![项目结构][fe344579ea0f321bc583010bbba247b0.png]

Demo主页面如下图:

![Demo主页面][Demo]

### Demo体验 ###

![扫码体验][54ce2c3c71628d3cae78d9baef28dadc.png]

### 视频教程 ###

XUI系列

如何在项目中使用XUI: [https://www.bilibili.com/video/BV1w7411c7Hy/][https_www.bilibili.com_video_BV1w7411c7Hy]

### 快速集成 ###

*  Android空壳模板工程(自动集成了XUI、XUtil、XAOP、XPage、XUpdate、XHttp2等): [https://github.com/xuexiangjys/TemplateAppProject][https_github.com_xuexiangjys_TemplateAppProject]
 *  简化版的Android空壳模版工程(自动集成了XUI、XUtil、XAOP、XPage等): [https://github.com/xuexiangjys/TemplateSimpleProject][https_github.com_xuexiangjys_TemplateSimpleProject]

--------------------

## 集成指南 ##

### 添加Gradle依赖 ###

1.先在项目根目录的 build.gradle 的 repositories 添加:

allprojects {
         repositories {
            ...
            maven { url "https://jitpack.io" }
        }
    }

【注意】切记不要跳过这一步，因为XUI目前只发布在`jitpack`平台上，跳过这一步会导致`ERROR: Failed to resolve: com.github.xuexiangjys:XUI:x.x.x`错误！！！

2.然后在dependencies添加:

dependencies {
      ...
      //androidx项目
      implementation 'com.github.xuexiangjys:XUI:1.1.5'
    
      implementation 'androidx.appcompat:appcompat:1.1.0'
      implementation 'androidx.recyclerview:recyclerview:1.1.0'
      implementation 'com.google.android.material:material:1.1.0'
      implementation 'com.github.bumptech.glide:glide:4.11.0'
    }

【注意】如果你的项目目前还未使用androidx，请使用如下配置：

dependencies {
      ...
      //support项目
      implementation 'com.github.xuexiangjys:XUI:1.0.9-support'
    
      implementation 'com.android.support:appcompat-v7:28.0.0'
      implementation 'com.android.support:recyclerview-v7:28.0.0'
      implementation 'com.android.support:design:28.0.0'
      implementation 'com.github.bumptech.glide:glide:4.8.0'
    }

### 初始化XUI设置 ###

1.在Application最顶部初始化设置（必须）

XUI.init(this); //初始化UI框架
    XUI.debug(true);  //开启UI框架调试日志

2.调整应用的基础主题（必须）

> 必须设置应用的基础主题，否则组件将无法正常使用！必须保证所有用到XUI组件的窗口的主题都为XUITheme的子类，这非常重要！！！

基础主题类型：

*  大平板(10英寸, 240dpi, 1920\*1200）：XUITheme.Tablet.Big
 *  小平板(7英寸, 320dpi, 1920\*1200）：XUITheme.Tablet.Small
 *  手机（4.5英寸, 320dpi, 720\*1280）：XUITheme.Phone

当然也可以在Activity刚开始时调用如下代码动态设置主题

@Override
    protected void onCreate(Bundle savedInstanceState) {
        XUI.initTheme(this);
        super.onCreate(savedInstanceState);
        ...
    }

3.调整字体库（对字体无要求的可省略）

（1）设置你需要修改的字体库路径（assets下）

//设置默认字体为华文行楷，这里写你的字体库
    XUI.getInstance().initFontStyle("fonts/hwxk.ttf");

（2）在项目的基础Activity中加入如下代码注入字体.

注意：1.1.4版本之后使用如下设置注入

@Override
    protected void attachBaseContext(Context newBase) {
        //注入字体
        super.attachBaseContext(ViewPumpContextWrapper.wrap(newBase));
    }

注意：1.1.3版本及之前的版本使用如下设置注入

@Override
    protected void attachBaseContext(Context newBase) {
        //注入字体
        super.attachBaseContext(CalligraphyContextWrapper.wrap(newBase));
    }

### 混淆配置 ###

-keep class com.xuexiang.xui.widget.edittext.materialedittext.** { *; }

--------------------

## 常见问题 ##

### 接入的问题 ###

#### 1.如何快速上手XUI，提升UI开发的效率？ ####

*  首先，请先仔细按照[接入文档][Link 4]接入XUI框架，不要跳步骤或者漏步骤，一步一步按照说明来接入。除此之外，我也提供了[视频教程][Link 5]供大家学习。
 *  其次，按照[正确使用XUI的姿势][XUI 1]的说明，来使用XUI。
 *  最后，出现问题可以查阅[使用说明文档][Link 6]或者研究Demo的使用，确保自己的用法是正确合理的，不要想当然。源码阅读能力强的可直接翻看[XUI的项目源码][XUI 2], 如果发现框架确实存在问题也可以点击[提交Issue清单][Issue],将问题反馈给我解决。

#### 2.为什么我增加XUI依赖后会报错：`ERROR: Failed to resolve: com.github.xuexiangjys:XUI:x.x.x`？ ####

答：这句话的意思是：无法解析到XUI的依赖。出现这种情况的原因是你没有配置远程依赖仓库`jitpack`地址。这里建议你不要自以为是，老老实实按照[使用说明文档][Link 4]来引入依赖。

#### 3.为什么我在使用XUI中的组件时，会报错说R文件找不到`android.content.res.Resources$NotFoundException: File res/drawable/xxxxx.xml from drawable resource ID ...`、属性获取不到`Failed to resolve attribute at index ...`或者布局解析出错`android.view.InflateException:Binary XML file line #xx:Error inflating class <unknow>....`？ ####

*  首先，你需要确认的是你当前组件所在的窗口（Activity）所使用的主题是否继承了`XUITheme`主题，如果没有，请按照[接入文档][Link 7]正确接入。这里需要说明的是，XUI不同于其他开源组件库，他是一套统一的UI框架，有一套严格统一的属性样式标准，其中绝大多数组件和资源都使用了规范化的XUI样式主题属性，因此不使用`XUITheme`将无法正常使用XUI框架。
 *  其次，如果你也使用了XUI主题，那么请查看你使用的`context`是否是所在窗口的`context`，组件中传入的`context`一定不要使用`XUI.getContext()`之类的，不懂的自己去复习一下Android的基础吧，这里给个讲[Android中的Context][Android_Context]和[Android中Context的类型][Android_Context 1], 自己去看吧。
 *  然后，如果你`context`也没使用错的话，那么请查看一下当前报错设备的系统版本。因为在Android5.0（21）以下在drawable中使用`?attr`引用主题属性的话，也会导致R文件找不到的问题。而且同样是在Android5.0（21）以下，如果你使用vector加载SVG图片的话，同样也会导致R文件找不到，因为在Android5.0（21）以下系统是不支持加载SVG图片的。
 *  最后，如果以上都检查过但问题依然存在，你可以尝试升级XUI至最新版本（注意最新版本只支持AndroidX）。如果升级了问题依然存在，那么就要考虑是不是你的用法有问题了，建议多看看XUI项目中的演示Demo，点击查看[学习演示Demo的用法][XUI 1]。

#### 4.XUI有支持Support和AndroidX的版本吗？ ####

答：最新的版本是只支持AndroidX的。从XUI 1.0.5以后，是支持AndroidX的版本，1.0.5之前的版本是支持Support的版本。这里我建议使用最新版本（AndroidX版本），因为之前的版本可能存在一些兼容性的bug，并在后面的版本被逐一修复。如果你依然想使用Support版本的话，要么你就使用1.0.5之前的版本（存在一些低版本兼容性的bug），要么你就clone一下当前最新版本的源码，将其改为Support版本本地导入依赖使用。

【这里考虑到还有一大部分人在使用support，为了方便大家使用，我在当前较为稳定的1.0.9版本上修改了一个支持support的版本`1.0.9-support`供大家过渡使用。】

#### 5.Glide版本冲突问题怎么解决？ ####

答：XUI依赖的Glide版本在1.1.3之前必须是4.8.0, 1.1.3及之后使用的是4.11.0。

#### 6.XUI支持全局性的字体修改吗？ ####

答：XUI是支持全局性的字体修改的。详情参见[接入文档][Link 7]。

#### 7.XUI支持自定义属于自己的主题吗？如何自定义主题以符合设计师给出的UI风格。 ####

答：XUI是支持自定义主题的。详情参见[如何自定义自己的主题][Link 8]。

### 演示Demo相关的问题 ###

#### 1.为什么XUIDemo项目我运行不起来？ ####

答：演示Demo的程序跑通是肯定没有任何问题的。这里推荐使用Android Studio 3.4.1以上的版本打开运行。详情参见[如何运行Demo程序][Demo 1]。除此之外,请不要修改gradle的版本,因为升级gradle版本可能导致依赖加载失败的问题.

#### 2.演示Demo中的"组件"、"工具"和"拓展"都包含了什么内容？ ####

答："组件"中主要包含了XUI对外提供的绝大多数组件的使用案例，"工具"中主要包含XUI对外提供辅助工具的使用案例。  
而"拓展"中包含的则是一些第三方常用的UI组件库使用案例，非XUI中提供的内容。详情参见[演示Demo介绍][Demo 2]。

--------------------

## 资源链接 ##

*  XUI系列教学视频: [https://space.bilibili.com/483850585/channel/detail?cid=104998][https_space.bilibili.com_483850585_channel_detail_cid_104998]
 *  XUI使用文档: [https://github.com/xuexiangjys/XUI/wiki][Link 6]
 *  Android空壳模板工程(自动集成了XUI、XUtil、XAOP、XPage、XUpdate、XHttp2等): [https://github.com/xuexiangjys/TemplateAppProject][https_github.com_xuexiangjys_TemplateAppProject]
 *  简化版的Android空壳模版工程(自动集成了XUI、XUtil、XAOP、XPage等): [https://github.com/xuexiangjys/TemplateSimpleProject][https_github.com_xuexiangjys_TemplateSimpleProject]

## 技术交流 ##

*  XUI开源交流群(可能已满)：695048677，[点击一键加入][Link 9]
 *  XUI开源交流2号群(可能已满)：700246750，[点击一键加入][Link 10]
 *  XUI开源交流3号群：1090612354，[点击一键加入][Link 11]

## 微信公众号 ##

> 更多资讯内容，欢迎扫描关注我的个人微信公众号:【我的Android开源之旅】

![我的Android开源之旅][Android]

[0ef711fe573d553ee1d53289f87796b9.png]: /images/20221120/fe0e527eef114a82a09af3f70484c33b.png
[XUI]: https://github.com/xuexiangjys/XUI
[QMUI]: https://github.com/Tencent/QMUI_Android
[XPage]: https://github.com/xuexiangjys/XPage
[Link 1]: https://github.com/xuexiangjys/XUI/tree/master/app/src/main/java/com/xuexiang/xuidemo/fragment/components
[Link 2]: https://github.com/xuexiangjys/XUI/tree/master/app/src/main/java/com/xuexiang/xuidemo/fragment/utils
[Link 3]: https://github.com/xuexiangjys/XUI/tree/master/app/src/main/java/com/xuexiang/xuidemo/fragment/expands
[fe344579ea0f321bc583010bbba247b0.png]: /images/20221120/05a40a4138ae4d769fd919b779993bed.png
[Demo]: /images/20221120/96d952d79c3d4228962dcb3d35f2c2c2.png
[54ce2c3c71628d3cae78d9baef28dadc.png]: /images/20221120/1936da4de2004dad9dc545374feeefee.png
[https_www.bilibili.com_video_BV1w7411c7Hy]: https://www.bilibili.com/video/BV1w7411c7Hy/
[https_github.com_xuexiangjys_TemplateAppProject]: https://github.com/xuexiangjys/TemplateAppProject
[https_github.com_xuexiangjys_TemplateSimpleProject]: https://github.com/xuexiangjys/TemplateSimpleProject
[Link 4]: https://github.com/xuexiangjys/XUI/wiki/%E5%A6%82%E4%BD%95%E5%BC%95%E7%94%A8
[Link 5]: https://www.bilibili.com/video/av90832054
[XUI 1]: https://github.com/xuexiangjys/XUI/wiki/%E6%AD%A3%E7%A1%AE%E4%BD%BF%E7%94%A8XUI%E7%9A%84%E5%A7%BF%E5%8A%BF
[Link 6]: https://github.com/xuexiangjys/XUI/wiki
[XUI 2]: https://github.com/xuexiangjys/XUI/tree/master/xui_lib
[Issue]: https://github.com/xuexiangjys/XUI/issues/new?assignees=xuexiangjys&labels=bug&template=bug_report.md&title=
[Link 7]: https://github.com/xuexiangjys/XUI/wiki/%E5%A6%82%E4%BD%95%E5%BC%95%E7%94%A8#%E5%88%9D%E5%A7%8B%E5%8C%96xui%E8%AE%BE%E7%BD%AE
[Android_Context]: https://www.jianshu.com/p/f2a496cb9c7c
[Android_Context 1]: https://www.cnblogs.com/chenxibobo/p/6136693.html
[Link 8]: https://github.com/xuexiangjys/XUI/wiki/%E4%B8%BB%E9%A2%98#%E5%A6%82%E4%BD%95%E8%87%AA%E5%AE%9A%E4%B9%89%E8%87%AA%E5%B7%B1%E7%9A%84%E4%B8%BB%E9%A2%98
[Demo 1]: https://github.com/xuexiangjys/XUI/wiki/%E6%AD%A3%E7%A1%AE%E4%BD%BF%E7%94%A8XUI%E7%9A%84%E5%A7%BF%E5%8A%BF#%E8%BF%90%E8%A1%8Cdemo%E7%A8%8B%E5%BA%8F%E6%8E%A8%E8%8D%90
[Demo 2]: https://github.com/xuexiangjys/XUI/wiki/%E6%BC%94%E7%A4%BADemo%E4%BB%8B%E7%BB%8D
[https_space.bilibili.com_483850585_channel_detail_cid_104998]: https://space.bilibili.com/483850585/channel/detail?cid=104998
[Link 9]: http://shang.qq.com/wpa/qunwpa?idkey=a2ab505862c81f1528416b585832022e835ce0abe28eefa4b0d53f8094a5691d
[Link 10]: http://shang.qq.com/wpa/qunwpa?idkey=39497f13d5e456d219be785361a282d2d9c8cd9ba7745f6170def9d90643e164
[Link 11]: https://qm.qq.com/cgi-bin/qm/qr?k=nOY3GGJY-jiwzhQpR8E06G-yrOUsxCP1
[Android]: /images/20221120/1a31e811be8e45119ec79459f6dc11d3.png