欢迎使用SuperTextView
从 SuperTextView 诞生之初,便始终坚持一个愿景,即帮助 Android 开发者快速愉悦的去构建一个应用。
SuperTextView 是一个高效的、全能的 Android 控件。通过 SuperTextView ,你可以快速实现圆角背景,设置渐变色背景,给控件和文字描边,为控件增加状态图,添加按压时文字或背景变色效果,通过 Adjuster 模块快速插入操作到控件绘制过程中,展示图片,甚至可以直接从网络上下载图片展示…基本上涵盖了 Android 日常开发中会用到的绝大部分效果。而实现这一切的代价,仅仅是给 SuperTextView 设置一个属性。SuperTextView 可以帮助开发者高效、便捷、优雅的完成需求开发。
本篇文档将详细的讲解目前 SuperTextView 的每一个功能,以便开发者能够快速上手。
dependencies {
compile 'com.github.chenBingX:SuperTextView:v3.0.0'
}
https://github.com/chenBingX/SuperTextView
注:关注项目以优先获得最新版本。
SuperTextView 的绝大部分属性均支持在xml中配置,设置后即预览到效果。
<SuperTextView
//设置圆角。会同时作用于填充和边框(如果边框存在的话)。
//如果要设置为圆形,只需要把该值设置为宽或长的1/2即可。
app:corner="25dp"
//设置左上角圆角
app:left_top_corner="true"
//设置右上角圆角
app:right_top_corner="true"
//设置左下角圆角
app:left_bottom_corner="true"
//设置右下角圆角
app:right_bottom_corner="true"
//设置填充颜色
app:solid="@color/red"
//设置边框颜色
app:stroke_color="@color/black"
//设置边框的宽度。
app:stroke_width="2dp"
//放置一个drawable在背景层上。默认居中显示。
//并且默认大小为SuperTextView的一半。
app:state_drawable="@drawable/emoji"
//设置drawable的显示模式。可选值如下:
// left、top、right、bottom、center(默认值)、
//leftTop、rightTop、leftBottom、rightBottom、
//fill(充满整个SuperTextView,此时会使设置drawable的大小失效)
app:state_drawable_mode="center"
//设置drawable的height
app:state_drawable_height="30dp"
//设置drawable的width
app:state_drawable_width="30dp"
//设置drawble相对于基础位置左边的距离
app:state_drawable_padding_left="10dp"
//设置drawble相对于基础位置上边的距离
app:state_drawable_padding_top="10dp"
// boolean类型。是否显示drawable。
//如果你想要设置的drawable显示出来,必须设置为true。
//当不想让它显示时,再设置为false即可。
app:isShowState="true"
// 是否将state_drawable作为背景图
// 将state_drawable作为背景图可以让SuperTextView具备展示图片的能力
// 通过调节corner、stroke等属性,可以给图片设置圆角、边框等
app:drawableAsBackground="true"
//放置一个drawable在背景层上。默认居中显示。
//并且默认大小为SuperTextView的一半。
app:state_drawable2="@drawable/emoji"
//与state_drawable类似
app:state_drawable2_mode="center"
//与state_drawable_height类似
app:state_drawable2_height="30dp"
//与state_drawable_width类似
app:state_drawable2_width="30dp"
//与state_drawable_padding_left类似
app:state_drawable2_padding_left="10dp"
//与state_drawable_padding_top类似
app:state_drawable2_padding_top="10dp"
//与isShowState类似
app:isShow2State="true"
//是否开启文字描边功能。
//注意,启用这个模式之后通过setTextColor()设置的颜色将会被覆盖。
//你需要通过text_fill_color来设置文字的颜色。
app:text_stroke="true"
// 文字的描边颜色。默认为Color.BLACK。
app:text_stroke_color="@color/black"
// 文字描边的宽度。
app:text_stroke_width="1dp"
// 文字填充的颜色。默认为Color.BLACK。
app:text_fill_color="@color/blue"
// boolean类型。是否启用Adjuster功能。
//具体干什么,需要在Java中为SuperTextView实现一个Adjuster。
//当你启用这个功能而没有实现自己的Adjuster时,
//SuperTextView会启用默认的Adjuster。它会按照一定的规则调整文字大小。
app:autoAdjust="true"
// 必须设置为true才能启用渐变功能。这意味着你可以灵活的控制这一功能。
app:shaderEnable="true"
// 设置起始颜色。
app:shaderStartColor="@color/main_blue"
// 设置结尾颜色。
app:shaderEndColor="@color/pink"
// 设置渐变模式。如上图可见,一共支持4中模式:
// topTopBottom, bottomToTop, leftToRight, rightToLeft
app:shaderMode="rightToLeft"
// 设置按压时的背景色
app:pressBgColor="@color/red"
// 设置按压时的文字颜色
app:pressTextColor="@color/white"
/>
点击此处,查看详细的《SuperTextView Api文档》
在 SuperTextView 中,有层级划分的概念。
1.Background层:View的Background
背景层。
2.背景层:即通过app:solid
设置的纯色背景层。在 SuperTextView
中通常将该层视做背景层,而不是View的Background
。
3.Drawable层:SuperTextView
的Drawable所在的层级。如果你希望通过 SuperTextView
来展示图片,就是在该层展示。
4.文字层:即绘制文字的层级。
理解层级的概念对于后面将要讲述的 Adjuster 很有帮助。
圆角化功能是 SuperTextView 最基本的功能,你可以在xml文件或者Java中进行设置。
在xml中:
app:corner="25dp"
在Java中:
stv.setCorner(25);
圆角化的设置仅对 SuperTextView 的【背景层】,或者将Drawble
用于展示图片(即:配置了app:drawableAsBackground="true"
)时有效。
如果你需要一个圆形的效果,只需要将corner
值设置为控件最大边长度的一半即可。比如:
android:layout_width="80dp"
android:layout_height="80dp"
app:corner="40dp"
app:solid="#008673"
将一张普通的图片圆角化:
app:corner="15dp"
app:state_drawable="@drawable/avatar1"
app:drawableAsBackground="true"
如果你希望实现圆形头像,或者圆角背景图的效果,那最适合不过了。
默认情况下,对 SuperTextView 设置corner
会对控件的4个角都有效。当然也可以单独指定那些角需要圆角化。
在Xml
//设置左上角圆角
app:left_top_corner="true"
//设置右上角圆角
app:right_top_corner="true"
//设置左下角圆角
app:left_bottom_corner="true"
//设置右下角圆角
app:right_bottom_corner="true"
在Java中
//设置左上角圆角
stv.setLeftTopCornerEnable( boolean);
// 设置左下角圆角
stv.setLeftBottomCornerEnable() boolean);
//设置右上角圆角
stv.setRightTopCornerEnable() boolean);
//设置右下角圆角
stv.setRightBottomCornerEnable() boolean);
需要注意的时候,一旦指定了任何一个圆角,app:corner
将不再对4个角都有效了,你需要一个一个的去设置。
SuperTextView 可以通过简单的配置给控件加上边框,实际开发中十分的便捷。
app:solid="#78C3ED"
app:stroke_color="#5166ED"
app:stroke_width="5dp"
只需要设置app:stroke_width
大于0即开启了边框功能,如果没有设置app:stroke_color
,会有默认的黑色边框。边框的圆角化也会受到corner
属性的影响。
边框的效果同样能够在展示图片的时候有效。
使用 SuperTextView 能够很轻松的实现文字描边的功能。
# 开启文字描边功能
app:text_stroke="true"
# 设置文字填充颜色
app:text_fill_color="@color/white"
# 设置文字描边颜色
app:text_stroke_color="#461B50"
# 设置文字描边宽度
app:text_stroke_width="1dp"
开启文字描边的功能后,文字颜色只能够通过app:text_fill_color
来设置,不要使用android:textColor
!
如果想要实现空心文字的效果,只需要将app:text_fill_color
设置为透明色,或者与背景色相同即可。
SuperTextView 自带状态图功能,即Drawable、Drawable2,能够展示两个状态图。
与系统的原生TextView的Drawable不同,SuperTextView 的状态图能够准确的控制位置和大小。
# boolean类型。是否开启状态图1的功能。
app:isShowState="true"
# 设置状态图1的图片
app:state_drawable="@drawable/emoji"
# 设置状态图1的显示模式,决定了状态图1的基础位置
# 可选值如下:
# left、top、right、bottom、center(默认值)、
# leftTop、rightTop、leftBottom、rightBottom、
# fill(充满整个SuperTextView,此时会使设置drawable的大小失效)
app:state_drawable_mode="center"
# 设置状态图1的height
app:state_drawable_height="30dp"
# 设置状态图1的width
app:state_drawable_width="30dp"
# 设置状态图1相对于基础位置的左边的距离
app:state_drawable_padding_left="10dp"
# 设置状态图1相对于基础位置上边的距离
app:state_drawable_padding_top="10dp"
# boolean类型。是否开启状态图2的功能。
app:isShow2State="true"
# 设置状态图2的图片
app:state_drawable2="@drawable/emoji"
# 设置状态图2的显示模式,决定了状态图2的基础位置
# 可选值如下:
# left、top、right、bottom、center(默认值)、
# leftTop、rightTop、leftBottom、rightBottom、
# fill(充满整个SuperTextView,此时会使设置drawable的大小失效)
app:state_drawable2_mode="center"
# 设置状态图2的height
app:state_drawable2_height="30dp"
# 设置状态图2的width
app:state_drawable2_width="30dp"
# 设置状态图2相对于基础位置的左边的距离
app:state_drawable2_padding_left="10dp"
# 设置状态图2相对于基础位置上边的距离
app:state_drawable2_padding_top="10dp"
上图是一些使用一个状态图实现的功能,可以看到,你可以轻松准确的控制状态图的位置和大小。
现在,看看两个状态图能够干什么。
<com.coorchice.library.SuperTextView
android:layout_width="100dp"
android:layout_height="100dp"
...
app:corner="50dp"
app:state_drawable="@drawable/avatar1"
# 将状态图1作为控件背景,以展示图片
app:drawableAsBackground="true"
# state_drawable2的配置由此开始
app:isShowState2="true"
app:state_drawable2="@drawable/recousers"
app:state_drawable2_mode="rightTop"
app:state_drawable2_height="20dp"
app:state_drawable2_width="20dp"
...
/>
<com.coorchice.library.SuperTextView
android:layout_width="100dp"
android:layout_height="100dp"
...
# 背景图
android:background="@drawable/avatar7"
# drawable1的配置由此开始
app:isShowState="true"
app:state_drawable="@drawable/triangle"
app:state_drawable_mode="leftTop"
app:state_drawable_width="20dp"
app:state_drawable_height="20dp"
# state_drawable2的配置由此开始
app:isShowState2="true"
app:state_drawable2="@drawable/recousers"
app:state_drawable2_mode="rightTop"
app:state_drawable2_height="20dp"
app:state_drawable2_width="20dp"
...
/>
SuperTextView 支持通过配置简单的属性实现渐变色效果。
# 必须设置为true才能启用渐变功能。这意味着你可以灵活的控制这一功能。
app:shaderEnable="true"
# 设置起始颜色
app:shaderStartColor="@color/main_blue"
# 设置结尾颜色。
app:shaderEndColor="@color/pink"
# 设置渐变模式。如上图可见,一共支持4中模式:
# topTopBottom, bottomToTop, leftToRight, rightToLeft
app:shaderMode="rightToLeft"
这些属性也支持在Java中设置。
// 开启渐变色功能
stv.setShaderEnable(true);
// 设置起始颜色
stv.setShaderStartColor(Color.BLUE);
// 设置结束颜色
stv.setShaderEndColor(Color.RED);
// 设置模式
stv.setShaderMode(SuperTextView.ShaderMode.LEFT_TO_RIGHT);
渐变模式共有4种:
public static enum ShaderMode {
/**
* 从上到下
*/
TOP_TO_BOTTOM(0),
/**
* 从下到上
*/
BOTTOM_TO_TOP(1),
/**
* 从左到右
*/
LEFT_TO_RIGHT(2),
/**
* 从右到左
*/
RIGHT_TO_LEFT(3);
}
SuperTextView 能够快速的支持按压变色效果,就像下图一样,文字和背景色都支持。
只需配置简单的属性:
# 设置按压时的背景色
app:pressBgColor="@color/red"
# 设置按压时的文字颜色
app:pressTextColor="@color/white"
在Java中:
// 设置按压背景变色
stv.setPressBgColor(Color.RED);
// 取消按压文字变色
stv.setPressTextColor(-99);
PressBgColor
为透明色,Color.TRANSPARENT
。PressTextColor
为-99。前面有提到过,SuperTextView 可以通过状态图1变成一个ImageView
。在设置好状态图1后,只需开启图片展示功能即可。
<com.coorchice.library.SuperTextView
...
app:state_drawable="@drawable/avatar1"
# 开启图片展示功能
app:drawableAsBackground="true"
...
/>
需要注意的是,当将状态图1用于展示图片后,状态图1将不再具备状态图的功能,直到你关闭了图片展示功能,通过stv.setDrawableAsBackground(false)
。
stv.setUrlImage(url);
在 SuperTextView 中,通过上面简单的一句即可将 SuperTextView 作为一个可以展示网络图片的ImageView。
调用上面的方法会默认开启 SuperTextView 的图片展示功能,因此,此时状态图1的状态图功能会被停用。你也可以通过以下方法,使得能够从网络中下载状态图1:
stv.setUrlImage(url, false);
第二个参数表示关闭图片展示功能。
上图中,第一个例子是从网络中下载图片用作状态图,第二个例子是用作展示图片。
SuperTextView 为了保持依赖库的纯净和尽可能小的体积,并没有内置任何的图片加载框架。所以默认情况,将使用内置的一个简易图片引擎去下载图片,确保开发者能够正常使用展示网络图片的功能。
SuperTextView 具备兼容任意第三方图片下载框架的能力,建议开发者根据项目的具体情况,选择一个目前正在使用的图片加载框架,设置到 SuperTextView 中,以用来加载图片。 下面将通过几个的例子展示如何将现有的图片框架安装到 SuperTextView 中。
第一步:实现图片引擎Engine
在 SuperTextView 中,核心的图片加载引擎被抽象成接口 Engine ,开发者需要根据所用的图片框架,实现一个 Engine。
public class GlideEngine implements Engine {
private Context context;
public GlideEngine(Context context) {
this.context = context;
}
@Override
public void load(String url, final ImageEngine.Callback callback) {
Glide.with(context).load(url).into(new SimpleTarget<GlideDrawable>() {
@Override
public void onResourceReady(GlideDrawable resource, GlideAnimation<? super GlideDrawable> glideAnimation) {
// 主要是通过callback返回Drawable对象给SuperTextView
callback.onCompleted(resource);
}
});
}
}
public class PicassoEngine implements Engine {
private Context context;
public PicassoEngine(Context context) {
this.context = context;
}
@Override
public void load(String url, final ImageEngine.Callback callback) {
Picasso.with(context).load(url).into(new Target() {
@Override
public void onBitmapLoaded(Bitmap bitmap, Picasso.LoadedFrom from) {
// 主要是通过callback返回Drawable对象给SuperTextView
callback.onCompleted(new BitmapDrawable(Resources.getSystem(), bitmap));
}
@Override
public void onBitmapFailed(Drawable errorDrawable) {
}
@Override
public void onPrepareLoad(Drawable placeHolderDrawable) {
}
});
}
}
第二步:安装图片引擎Engine
实现好 Engine 后,下一步就是要将其安装到 SuperTextView 中。
建议可以在 Application的onCreate()
中进行安装,这样当需要使用 SuperTextView 加载显示网络图片的时候,就能够用到三方图片框架了。
public class STVApplication extends Application {
@Override
public void onCreate() {
super.onCreate();
// 安装图片引擎
ImageEngine.install(new GlideEngine(this));
// ImageEngine.install(new PicassoEngine(this));
}
}
一行代码,轻松安装。
需要注意的是,任何时候,后安装的 Engine 实例总是会替换掉先前安装的 Engine 实例,即 SuperTextView 只允许全局存在一个 Engine 实例。
只需简单两步,即可完成任意三方图片加载框架的适配。
Adjuster 被设计用来在 SuperTextView 的绘制过程中插入一些操作。这具有非常重要的意义。比如,实时的改变控件的状态,制作复杂的动画效果或者交互效果。
public class YourAdjuster extends SuperTextView.Adjuster {
@Override
protected void adjust(SuperTextView v, Canvas canvas) {
//do your business。
}
@Override
public boolean onTouch(SuperTextView v, MotionEvent event) {
//you can get the touch event.
//If want to get a series of touch event, you must return true here.
}
}
通过重写 Adjuster 的 adjust()
方法,可以获取每次绘制过程中控件的Canvas
对象,这意味着可以在绘制过程中从外部插入一些新的元素。当然,单单通过 SuperTextView 的实例修改其状态也是可以的。
通过重写 Adjuster 的 onTouch()
方法,可以获取每一次控件的触摸事件,如果在该方法中返回true,表明该 Adjuster 需要获取后续的触摸事件,同时也会使得 SuperTextView 在整个控件树中回去拦截触摸事件。配合 adjust()
可以实现一些复杂的交互效果。值得注意的是,如果在 SuperTextView 之前,已经有控件拦截的触摸事件,那么其中的 Adjuster 将无法获取到触摸事件。
当装载 Adjuster 到 SuperTextView 之后,需要调用以下方法来开启 Adjuster 的功能:
stv.setAutoAdjust(true);
当然,停止 Adjuster 只需要设置为false即可。
stv.addAdjuster(mAdjuster);
通过上面方法可以将一个 Adjuster 添加到 SuperTextView 中,最多支持添加3个 Adjuster 。超过3个的部分,将会始终覆盖最后一个 Adjuster。
如果你想要移除一个 Adjuster,通过下面方法来实现。
stv.removeAdjuster(index)
前面有描述过 SuperTextView 的层级划分,Adjuster 可以通过配置,将其插入到指定的层级。
mAdjuster.setOpportunity(opportunity);
层级定义了如下几个枚举变量:
public enum Opportunity {
// 背景层和Drawable层之间
BEFORE_DRAWABLE,
// Drawable层和文字层之间
BEFORE_TEXT,
// 最上层
AT_LAST
}
分别对应如下几种场景,其中Emoji图是StateDrawable状态图,蓝色圆形就是一个 Adjuster :
在 SuperTextView 中,可以通过以下方法触发 SuperTextView 的定时绘制:
stv.startAnim();
启动动画后, SuperTextView 将会以默认 60fps 的帧率进行刷新。配合 Adjuster 可以十分简单的实现动画效果。
当 SuperTextView 离开屏幕后,将会自动停止正在播放的动画,当在次进入屏幕时,又会自动启动。所以开发者可以无需担心动画在后台消耗资源。
当然,开发者也可以随时停止动画,通过调用以下方法:
stv.stopAnim();
通过以下方法,开发者可以随时修改 SuperTextView 的刷新频率:
// 每秒30帧
stv.setFrameRate(30);
- 如果你或你的团队正在使用 SuperTextView,可以通过邮箱
coorchice.cb@alibaba-inc.com
告知我。- 如果你喜欢 SuperTextView ,希望能顺手在 Github 点个star哦!
文档结束。更多例子可以Clone项目到本地学习,祝你使用愉快!