Support Annotation Library 使用详解

Support Annotation Library 是提供了一系列元注解,用来帮助开发者在编译期间发现可能存在的BUG.

1. Nullness 注解

此类注解包含 :

• @Nullable 作用于函数参数和返回值,标记参数或者返回值可以为空.
• @NonNull 作用于函数参数和返回值,标记参数或者返回值不可以为空.

Android Studio 会自动提示注解错误.

2. 资源类型注解

在Android中资源通常用整形值表示,保存在R文件中. 这样存在的问题就是如果一个需要使用Layout资源的地方传入了一个String类型的资源编译期间也不会报错,只有在运行到相应代码时才会发现错误. 使用资源型注解就可以解决这个问题.

注解符号 标记类型 @AnimatorRes android.R.animator @AnimRes android.R.anim @AnyRes 标记整形值是任意一种资源 @ArrayRes android.R.array @AttrRes android.R.attr @BoolRes 整形值是布尔类型 @ColorRes android.R.color @Drawable android.R.drawable @IdRes android.R.id @FracriionRes fraction类型,这种比较少见,这种资源类型常见于Animation XML中. @IntegerRes android.R.layout @InterpolatorRes android.R.interpolator @LayoutRes android.R.layout @MenuRes android.R.menu @PluralsRes android.R.plurals 表示复数字符串. @RawRes android.R.raw @StringRes android.R.string @StyleableRes android.R.styleable @StyleRes android.R.style @TransitionRes 标记 transition类型 @XmlRes android.R.xml

3. 类型定义注解

在Android开发中,整数值不仅用来代表资源值,也经常用来代表枚举值. 使用@IntDef 注解可以定义一个新的整形类型的注解.

用法一 : 定义范围

// 定义可以接收的常量列表.@IntDef({X_1,X_2,X_3})// 定义注解.public @interface TestMode {}// 定义常量public final static int X_1 = 0x01;public final static int X_2 = 0x02;public final static int X_3 = 0x03;// 使用定义的注解, 如果mode不是三个常量之一Android Studio会给出警告.public void setTestMode(@TestMode int mode){}@TestModepublic int getTestMode(){    return X_1;}// 使用public void test(){    setTestMode(X_1);}

用法二 : 定义一个flag标志位,来识别函数参数或者返回值是否符合某一种模式.

// 定义范围@IntDef(flag = true, value = {        XX_1,XX_2,XX_3})// 定义注解public @interface TestMode2 {}// 定义常量public static final int XX_1 = 0x01;public static final int XX_2 = XX_1 << 1;public static final int XX_3 = XX_1 << 2;// 使用@TestMode2public int getMode2(){    return XX_1;}public void setMode2(@TestMode2 int mode2){}public void test2(){    // 这种模式下可以使用多个并在一起    setMode2(XX_1 | XX_3);}

4. 线程注解

• @UiThread : 标记运行在UI线程.
• @MainThread : 运行在主线程,一个应用只有一个主线程,主线程也是@UIThread线程,通常情况下我们可以使用@MainThread 来注解生命周期相关的函数,使用@UiThread 来注解视图相关的函数,一般情况下两者可以互换.
• @WorkerThread : 标记运行在后台线程.
• @BinderThread : 标记运行在Binder线程中.

@UiThreadpublic void testUiThread(){    Log.d(TAG,"运行在UI线程中");}@MainThreadpublic void testMainThread(){    Log.d(TAG, "运行在主线程");}@WorkerThreadpublic void testWorkerThread(){    Log.d(TAG, "运行在后台线程");}@BinderThreadpublic void testBinderThread(){    Log.d(TAG, "运行在Binder线程");}

5. 值范围注解

当函数取值是一定范围时,我们可以使用值范围注解来防止调用这传入错误参数.

• @Size : 对于集合、数组和字符串之类的参数,开使用@Size注解来表示这些参数的大小.

  • @Size(min=1) // 集合币可以为空
  • @Size(max=4) // 字符串最大字符个数是4.
  • @Size(2) // 数组元素两个.
  • @Size(multiple=2) //数组大小是2 的倍数.

// 数组不能为空public void testRange1(@Size(min = 1) final byte[] bbs){}// 数组长度大4public void testRange2(@Size(max = 4) final byte[] bbs){}// 两个字符public void testRange3(@Size(2) String string){}// 长度是 2 的倍数.public void testRange4(@Size(multiple = 2) String string){}

• @IntRange : 参数可以是 int 或者 long

// 0-255public void testRange5(@IntRange(from = 0,to = 255) int alpha){}

• @FloatRange : 参数是float或者double

// 0.0-255.0public void testRange6(@FloatRange(from = 0.0,to = 255.0) float alpha){}

6. 权限注解

Android 应用在使用某些系统功能时,需要在AndroidManifest.xml中声明权限,否则运行会报错. 使用权限注解@RequiresPermission 可以帮助我们在编译时找出错误.

• 需要声明一个权限

// 调用此方法需要声明权限.@RequiresPermission(Manifest.permission.SET_WALLPAPER)public void testPermissionAnnotation() {}

• 需要声明集合中的至少一个权限

// 调用此方法需要声明下面任何一个权限.@RequiresPermission(anyOf = {        Manifest.permission.ACCESS_COARSE_LOCATION,        Manifest.permission.ACCESS_FINE_LOCATION})public void testPermission2(){}

• 需要声明集合中的所有权限

// 调用此方法需要声明下面所有的权限.@RequiresPermission(allOf = {        Manifest.permission.ACCESS_COARSE_LOCATION,        Manifest.permission.ACCESS_FINE_LOCATION})public void testPermission3(){}

• Intent 调用所需权限,可以在Intent的ACTION字符串定义处添加注解

// Intent 的这个Action需要使用如下权限@RequiresPermission(Manifest.permission.EXPAND_STATUS_BAR)public static final String ACTION_MY = "custom_action";

• ContentProvider 同时需要读写

// 对于[e-mail](@RequiresPermission(Manifest.permission.READ_CALENDAR))@RequiresPermission.Write(@RequiresPermission(Manifest.permission.READ_CALENDAR))public static final Uri BOOKMARKS_URI = Uri.parse("content://browser/bookmarks");

7. 重写函数注解

如果API允许重写某个函数,但同时要求重写的函数调用被重写函数则可以使用@CallSuper注解.

@CallSuperpublic static int testCallSuper() {    return 0;}

8. 返回值注解

需要调用者对返回值进行某些处理,可以使用@CheckResult 回调. suggest 会是提示内容.

@CheckResult(suggest = "检查一下返回值呗")public static int testReturn(){    return 12;}public static void testCheck(){    int x = testReturn();}

9. @VisibaleForTesting

使某些变量在单元测试中可见.

10. @Keep

用来标记在混淆时不需要混淆的方法.

参考 : Android 高级进阶