Android 开发小工具之:注解 Annotation

作者: rain 分类: 移动 发布时间: 2015-09-02 22:55 6 条评论

Android Support 包之一的 support-annotations 是通过静态编译检测来提高代码质量的一个注解工具。里面包含了 Android 开发中常用的代码检测注解,帮助开发者提高代码质量。通过 SDK Manager 下载 Android Support Repository 后,在 Gradle 中通过如下声明来使用该注解包:

dependencies {
compile ‘com.android.support:support-annotations:22.2.0’
}

该工具包含如下几种类型的代码检测:

检测参数或者返回值是否可以为 null

@Nullable 和 @NonNull 会分别检测一个变量、参数或者函数返回值是否为 null。如果一个函数的参数用 @NonNull 注解,当调用该函数指定该参数为 null 的时候,代码检测工具(Lint)会告诉你一个警告,该参数不能为 null。而 @Nullable 则表示可以为 null。例如 如下的代码表示 onCreateView 函数的返回值不为 null, 参数 context 和 attrs 也不能为 null:

import android.support.annotation.NonNull;

/** Add support for inflating the <fragment> tag. */
@NonNull
@Override
public View onCreateView(String name, @NonNull Context context,
@NonNull AttributeSet attrs) {

}

资源类型注解

Android 开发中经常使用各种资源常量 R.XXX 来引用各种资源。例如 图片资源和字符串资源。这些常量都是 int 类型的,在代码检测的时候没法判断引用的资源是否有错误,比如本来需要一个字符串资源,结果在代码写的时候用了一个颜色资源,这种情况只有通过测试才能发现,有些极端情况可能测试也不容易发现。资源类型注解就是为了解决该问题的,资源注解包含如下几种:

  • @AnimatorRes 表明该参数、变量或者函数返回值应该是一个 Animator 类型的资源
  • @AnimRes 表明该参数、变量或者函数返回值应该是一个 Anim 类型的资源
  • @AnyRes 表明该参数、变量或者函数返回值应该是一个任意类型的资源
  • @ArrayRes 表明该参数、变量或者函数返回值应该是一个 Array 类型的资源
  • @AttrRes 表明该参数、变量或者函数返回值应该是一个 attribute 类型的资源
  • @BoolRes 表明该参数、变量或者函数返回值应该是一个布尔类型的资源
  • @ColorInt 表明该参数、变量或者函数返回值应该是一个颜色值而不是颜色资源引用,例如应该是一个 AARRGGBB 的整数值。
  • @ColorRes 表明该参数、变量或者函数返回值应该是一个 color 类型的资源,而不是颜色值。注意和 ColorInt 区别
  • @DimenRes 表明该参数、变量或者函数返回值应该是一个 dimension 类型的资源
  • @DrawableRes 表明该参数、变量或者函数返回值应该是一个 drawable 类型的资源
  • @FractionRes 表明该参数、变量或者函数返回值应该是一个 fraction 类型的资源
  • @IdRes 表明该参数、变量或者函数返回值应该是一个资源的 ID 类型
  • @IntegerRes 表明该参数、变量或者函数返回值应该是一个整数类型的资源
  • @InterpolatorRes 表明该参数、变量或者函数返回值应该是一个 interpolator 类型的资源
  • @LayoutRes 表明该参数、变量或者函数返回值应该是一个 layout 布局文件类型的资源
  • @MenuRes 表明该参数、变量或者函数返回值应该是一个 menu 类型的资源
  • @PluralsRes 表明该参数、变量或者函数返回值应该是一个 plurals 类型的资源
  • @RawRes 表明该参数、变量或者函数返回值应该是一个 raw 类型的资源
  • @StringRes 表明该参数、变量或者函数返回值应该是一个字符串类型的资源
  • @StyleableRes 表明该参数、变量或者函数返回值应该是一个 styleable 类型的资源
  • @StyleRes 表明该参数、变量或者函数返回值应该是一个 style 类型的资源
  • @TransitionRes 表明该参数、变量或者函数返回值应该是一个 transition 类型的资源
  • @XmlRes 表明该参数、变量或者函数返回值应该是一个 XML 类型的资源

 

 

 

 

 

例如下面的函数在调用的时候,如果用非字符串类型的 R 常量则会给出警告:

import android.support.annotation.StringRes;

public abstract void setTitle(@StringRes int resId);

线程注解类型

线程注解用来检测一个函数是否在指定类型的线程中执行。 有四个:@UiThread @MainThread @WorkerThread @BinderThread

注意: 其中 @UiThread 和 @MainThread 是可替换用的, 大部分应用中,这两个是一样的。

如果一个类中的所有函数都在同一个线程内执行,可以在 类名称上面用这个注解即可。

权限注解类型

@RequiresPermission 用来表明该函数执行需要一个或者多个权限,如果你没有声明这些权限,则会给出警告。例如:

@RequiresPermission(Manifest.permission.SET_WALLPAPER)
public abstract void setWallpaper(Bitmap bitmap) throws IOException;

@RequiresPermission(allOf = {
Manifest.permission.READ_HISTORY_BOOKMARKS,
Manifest.permission.WRITE_HISTORY_BOOKMARKS})
public static final void updateVisitedHistory(ContentResolver cr, String url, boolean real) {

}

@RequiresPermission(anyOf = {
Manifest.permission.READ_HISTORY_BOOKMARKS,
Manifest.permission.WRITE_HISTORY_BOOKMARKS})
public static final void updateHistory(ContentResolver cr, String url, boolean real) {

}

如果只要满足多个权限中的一个,用 anyOf; 如果要满足多个权限,用 allOf.

返回值是否使用检测注解

@CheckResults 用来检测函数的返回值是否被使用了,如果没有使用则说明可能不应该调用这个函数,可以给出建议使用哪个函数。例如,新的 Android SDK 中就在 checkPermission 函数中使用如下注解:

@CheckResult(suggest=”#enforcePermission(String,int,int,String)”)
public abstract int checkPermission(@NonNull String permission, int pid, int uid);

如果你调用了 checkPermission 函数,但是并没有使用其返回值,则很有可能你是想申请一个权限而不是检查是否有这个权限,所以 suggest 参数建议你使用 enforcePermission 函数来申请权限。如果你确实想检查是否有这个权限,则通常你会判断 checkPermission 的返回值来确定是否有这个权限。

确保调用 super 函数的注解

@CallSuper 来表明重写这个函数需要调用 super 父函数。如果你忘记了调用,则会提醒你。比如 Activity 的onCreate 函数需要代用 super.onCreate().

数值常量注解

@IntRange 是用来表明整数型参数的取值范围的,比如 下面的 setAlpha 函数的参数 alpha 的取值范围应该为 0 到 255,其他值都是非法的;
public void setAlpha(@IntRange(from=0,to=255) int alpha) { … }

@FloatRange 同样是表明浮点数范围的,例如:
public void setAlpha(@FloatRange(from=0.0, to=1.0) float alpha) {…}

而 @Size 是用来表明数组类型参数的长度的,可以用 @Size(min=1) 来指定数组的最小长度,@Size(2) 则表明该数组参数必须是2. 例如:、

int[] location = new int[3];
button.getLocationOnScreen(@Size(min=1) location);

创建枚举类型注解

如果一个参数、变量的取值是几个常量中的一个,则可以用 @IntDef 和 @StringDef 注解来自定义一个常量枚举类型注解。使用方式如下所示:

import android.support.annotation.IntDef;

public abstract class ActionBar {

//定义所接受的常量值
@IntDef({NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS})

//告诉编译器该注解不会在 .class 文件中存在
@Retention(RetentionPolicy.SOURCE)

//定义 NavigationMode 注解
public @interface NavigationMode {}

//Declare the constants
public static final int NAVIGATION_MODE_STANDARD = 0;
public static final int NAVIGATION_MODE_LIST = 1;
public static final int NAVIGATION_MODE_TABS = 2;

//Decorate the target methods with the annotation
@NavigationMode
public abstract int getNavigationMode();

//Attach the annotation
public abstract void setNavigationMode(@NavigationMode int mode);

上面的 @NavigationMode 注解使用了 @IntDef 来定义该注解所限定了一些常量值。 当你用 @NavigationMode 注解时,则说明这个参数或者函数返回值需要是 @IntDef 中定义的常量值其一 (NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, 或者 NAVIGATION_MODE_TABS).

除了定义具体的常量值以外,还可以通过 flag 参数来指定一个模式,例如下面的 DisplayOptions 注解定义该类型必须满足依 DISPLAY_ 开头的一个模式。

import android.support.annotation.IntDef;

@IntDef(flag=true, value={
DISPLAY_USE_LOGO,
DISPLAY_SHOW_HOME,
DISPLAY_HOME_AS_UP,
DISPLAY_SHOW_TITLE,
DISPLAY_SHOW_CUSTOM
})
@Retention(RetentionPolicy.SOURCE)
public @interface DisplayOptions {}

本文出自 云在千峰,转载时请注明出处及相应链接。

本文永久链接: http://blog.chengyunfeng.com/?p=771

Ɣ回顶部