Android Support库——support annotations

　　Android Support库是官方出的支持扩展库，包含了丰富的组件、工具类等，通过在Android SDK Manager中勾选以下两项来获取到。



　　其中，

Android Support Library

下载的是对应的源码或jar包，在使用Eclipse时会从这里拷贝出需要的文件到项目中。而

Android Support Repository

下载的是这个support库所对应的本地Maven库。如果你是使用Gradle进行构建（如Android Studio），并通过远程依赖的方式来使用support库的话，则需要下载它，才能获取到对应的依赖。

　　如上面所说，Android support库包含了众多有用的类库，包括目前基本在项目中都会用到的support-v4包。而本序列第一篇要讲的是，除此support-v4库之外，我们用得特别多的一个库：android-support-annotations。

　　由于我所使用的是Android Studio，所以对于Eclipse相关的知识在本篇及后续博客中都会略过不谈。

　　android-support-annotations是Android官方提供的一个注解库，它提供了许多有用的注解，这些注解的生命周期为源码时期，也就是在编译之后则不再保留，通常用于辅助代码上的静态检查。

　　在Gradle中引入这个库的方式通常如下：

　　compile 'com.android.support:support-annotations:23.1.1'

1
　　但是如果你已经通过这种方式依赖了support-v4库的话，则不必再显式声明依赖它，因为support-v4也依赖于这个库，由于Gradle的传递依赖的特性，你的项目如果依赖了support-v4库的话，也会依赖到这个注解库。

　　通过使用support-annotations的注解，我们可以限定一些变量、方法参数或者是方法返回值的范围，这些注解涵盖的使用范围如下：

　　

22个资源类注解：

AnimatorRes

：指出一个

integer

的参数，成员变量，或方法返回值是一个

animator

资源的引用。

AnimRes

：指出一个

integer

的参数，成员变量，或方法返回值是一个

anim

资源的引用。

AnyRes

：指出一个

integer

的参数，成员变量，或方法返回值是一个任意资源类型的引用。

ArrayRes

：指出一个

integer

的参数，成员变量，或方法返回值是一个

array

资源类型的引用。

AttrRes

：指出一个

integer

的参数，成员变量，或方法返回值是一个

attr

资源的引用。

BoolRes

：指出一个

integer

的参数，成员变量，或方法返回值是一个

boolean

资源的引用。

ColorRes

：指出一个

integer

的参数，成员变量，或方法返回值是一个

color

资源的引用。

DimenRes

：指出一个

integer

的参数，成员变量，或方法返回值是一个

dimen

资源的引用。

DrawableRes

：指出一个

integer

的参数，成员变量，或方法返回值是一个

drawable

资源的引用（包括

@mipmap

）。

FractionRes

：指出一个

integer

的参数，成员变量，或方法返回值是一个

fraction

资源的引用。

IdRes

：指出一个

integer

的参数，成员变量，或方法返回值是一个

id

资源的引用。

IntegerRes

：指出一个

integer

的参数，成员变量，或方法返回值是一个

integer

资源的引用。

InterpolatorRes

：指出一个

integer

的参数，成员变量，或方法返回值是一个

interpolator

资源的引用。

LayoutRes

：指出一个

integer

的参数，成员变量，或方法返回值是一个

layout

资源的引用。

MenuRes

：指出一个

integer

的参数，成员变量，或方法返回值是一个

menu

资源的引用。

PluralsRes

：指出一个

integer

的参数，成员变量，或方法返回值是一个

plurals

资源的引用。

RawRes

：指出一个

integer

的参数，成员变量，或方法返回值是一个

raw

资源的引用。

StringRes

：指出一个

integer

的参数，成员变量，或方法返回值是一个

string

资源的引用。

StyleableRes

：指出一个

integer

的参数，成员变量，或方法返回值是一个

styleable

资源的引用。

StyleRes

：指出一个

integer

的参数，成员变量，或方法返回值是一个

style

资源的引用。

TransitionRes

：指出一个

integer

的参数，成员变量，或方法返回值是一个

transition

资源的引用。

XmlRes

：指出一个

integer

的参数，成员变量，或方法返回值是一个

xml

资源的引用。

颜色注解：

　　假如我们定义了一个方法用来设置颜色，但是因为表示颜色用的是int类型，这样就会导致使用的人无法区分是要传一个表示颜色的资源还是颜色值，对于这种情况，support-annotations给我们提供了以下这个注解：

ColorInt

：指出一个被注解的元素，是一个int颜色值，表示的是

AARRGGBB

。

4个线程相关的注解：

BinderThread

：指出被注解的方法应该只在binder线程中被调用。

MainThread

：指出被注解的方法应该只在主线程中被调用。

WorkerThread

：指出被注解的方法应该只在工作线程中被调用。

UiThread

：指出被注解的方法应该只在UI线程中被调用。
关于这四个注解的差异，可参见stackoverflow的回答：Difference between MainThread, UiThread, WorkerThread, BinderThread
in Android Annotation

其他方法相关的注解：

CallSuper

：指出一个方法如果被重写了，它必须也被调用。比如Activity的生命周期方法

onCreate

方法等。

CheckResult

：指出一个方法返回的结果通常是否为一个忽略的错误。比如删除文件：

new File("xx").delete();

Keep

：指出一个方法在被混淆的时候应该被保留。

取值范围的注解：

FloatRange

：指出一个被注解的元素应该是一个给定范围内的float值或double值。比如：

@FloatRange(from=0.0,to=1.0)
public float getAlpha() {
...
}

1
2
3
4

IntRange

：指出一个被注解的元素应该是一个给定范围内的int值或long值。

IntDef

：指出一个int类型的元素，它表示的是一个逻辑上的类型，并且它的值必须是被明确声明的常量之一。官方常使用这种方式使int类型代替enum类型。

StringDef

：指出一个String类型的元素，它表示的是一个逻辑上的类型，并且它的值必须是被明确声明的常量之一。

空指针检查

　　通常我们如果对一个变量进行主动的赋值为null，编译器可能会进行可能引发空指针异常的警告，我们可以使用以下注解对这种行为进行控制。

-

NonNull

：指出一个参数，变量，或方法返回值永远不可为null。

-

Nullable

：指出一个参数，变量，或方法返回值可能为null。

其他注解：

Size

：表示一个被注解的元素应该有一个给定的大小或长度。

VisibleForTesting

：可注解一个类，方法，或变量，表示有更宽松的可见性，这样它能够有更宽泛的可见性，使代码可以被测试。

在Android Support Library19.1版本中，Android工具小组引入了几个很酷的注解类型，供开发者在工程中使用。Support Library自身也使用这些注解，这是一个好兆头。就让我们好好研究下。

通过gradle可以很容易的把这些注解添加到我们的工程中：

compile 'com.android.support:support-annotations:20.0.0'

有三种类型的注解可供我们使用：

Nullness注解；
资源类型注解；
IntDef和StringDef注解；
我们将通过代码例子来讲解每一种类型的作用以及在工程中如何使用它们。

Nullness注解

使用@NonNull注解修饰的参数不能为null。在下面的代码例子中，我们有一个取值为null的name变量，它被作为参数传递给sayHello函数，而该函数要求这个参数是非null的String类型：

public class MainActivity extends ActionBarActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        String name = null;
        sayHello(name);
    }

    void sayHello(@NonNull String s) {
        Toast.makeText(this, "Hello " + s, Toast.LENGTH_LONG).show();
    }
}

由于代码中参数String s使用@NonNull注解修饰，因此IDE将会以警告的形式提醒我们这个地方有问题：



如果我们给name赋值，例如String name = “Our Lord Duarte”，那么警告将消失。使用@Nullable注解修饰的函数参数或者返回值可以为null。假设User类有一个名为name的变量，使用 User.getName()访问，那么我们可以编写如下代码：

public class MainActivity extends ActionBarActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        User user = new User("Our Lord Duarte");
        Toast.makeText(this, "Hello " + getName(user), Toast.LENGTH_LONG).show();
    }
    @Nullable
    String getName(@NonNull User user) {
        return user.getName();
    }
}

因为getName函数的返回值使用@Nullable修饰，所以调用：

Toast.makeText(this, "Hello " + getName(user), Toast.LENGTH_LONG).show();

没有检查getName的返回值是否为空，将可能导致crash。

资源类型注解

是否曾经传递了错误的资源整型值给函数，还能够愉快的得到本来想要的整型值吗？资源类型注解可以帮助我们准确实现这一点。在下面的代码中，我们的sayHello函数预期接受一个字符串类型的id，并使用@StringRes注解修饰：

public class MainActivity extends ActionBarActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        sayHello(R.style.AppTheme);
    }

    void sayHello(@StringRes int id) {
        Toast.makeText(this, "Hello " + getString(id), Toast.LENGTH_LONG).show();
    }
}

而我们传递了一个样式资源id给它，这时IDE将提示警告如下：



类似的，我们把警告的地方使用一个字符串资源id代替警告就消失了：

sayHello(R.string.name);

IntDef和StringDef注解

我们要介绍的最后一种类型的注解是基于Intellij的“魔术常量”检查机制（http://blog.jetbrains.com/idea/2012/02/new-magic-constant-inspection/）

（我们不需要详细了解这个机制具体是如何实现的，想了解的话可以点击链接）。

很多时候，我们使用整型常量代替枚举类型（性能考虑），例如我们有一个IceCreamFlavourManager类，它具有三种模式的操 作：VANILLA，CHOCOLATE和STRAWBERRY。我们可以定义一个名为@Flavour的新注解，并使用@IntDef指定它可以接受的 值类型。

public class IceCreamFlavourManager {
    private int flavour;
    public static final int VANILLA = 0;
    public static final int CHOCOLATE = 1;
    public static final int STRAWBERRY = 2;
    @IntDef({VANILLA, CHOCOLATE, STRAWBERRY})
    public @interface Flavour {
    }
    @Flavour
    public int getFlavour() {
        return flavour;
    }
    public void setFlavour(@Flavour int flavour) {
        this.flavour = flavour;
    }
}

这时如果我们使用错误的整型值调用IceCreamFlavourManager.setFlavour时，IDE将报错如下：



IDE甚至会提示我们可以使用的有效的取值：



我们也可以指定整型值作为标志位，也就是说这些整型值可以使用’｜’或者’&’进行与或等操作。如果我们把@Flavour定义为如下标志位：

@IntDef(flag = true, value = {VANILLA, CHOCOLATE, STRAWBERRY})

    public @interface Flavour {

}

那么可以如下调用：

iceCreamFlavourManager.setFlavour(IceCreamFlavourManager.VANILLA & IceCreamFlavourManager

                .CHOCOLATE);

@StringDef用法和@IntDef基本差不多，只不过是针对String类型而已。

关于将来计划增加哪些新的注解类型或者这些注解的依赖以及和Intellij自身的注解如何交互等等问题，可以查看网址：http://tools.android.com/tech-docs/support-annotations。