Android Support 注解概览

2016-07-06

Android Support Annotation（注解）概览。

@AnimatorRes

表示一个整形参数，变量或方法的返回值预期是一个animator资源，例如：android.R.animator.fade_in。

@AnimRes

表示一个整形参数，变量或方法的返回值预期是一个anim资源，例如：android.R.anim.fade_in。

@AnyRes

表示一个整形参数，变量或方法的返回值预期是一个任何类型的资源。

@AnyThread

表示方法可以在任何线程被调用。例如：

1 2	@AnyThread public void deliverResult(D data) { ... }

@ArrayRes

表示一个整形参数，变量或方法的返回值预期是一个array资源，例如：android.R.array.phoneTypes。

@AttrRes

表示一个整形参数，变量或方法的返回值预期是一个attribute资源，例如：android.R.attr.action。

@BinderThread

表示方法只能在binder线程中被调用。如果在类上注解，表示类中所有方法都应该在binder线程中被调用。例如：

1 2	@BinderThread public BeamShareData createBeamShareData() { ... }

@BoolRes

表示一个整形参数，变量或方法的返回值预期是一个boolean资源。

@CallSuper

表示所有重写的方法也应该调用这个方法。例如：

1 2	@CallSuper public abstract void onFocusLost();

@CheckResult

表示被注解的方法返回的结果通常是可忽略的错误。这通常用于方法没什么效果，因此调用它没有看到实际结果通常意味着开发者不理解方法做了什么。

@ColorInt

被注解的元素表示一个打包的int color,AARRGGBB。如果应用为一个int array，那么array中所有元素都可以表示一个color integer。例如：

1	public abstract void setTextColor(@ColorInt int color);

@ColorRes

表示一个整形参数，变量或方法的返回值预期是一个color资源，例如：android.R.color.black。

@DimenRes

表示一个整形参数，变量或方法的返回值预期是一个dimen资源，例如：android.R.dimen.app_icon_size。

@Dimension

表示一个整形参数，变量或方法的返回值预期是一个dimension。

@DrawableRes

表示一个整形参数，变量或方法的返回值预期是一个drawable资源，例如：android.R.attr.alertDialogIcon。

@FloatRange

被注解的元素应该是一个给定范围的float or double。

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

@FractionRes

表示一个整形参数，变量或方法的返回值预期是一个fraction资源。

@IdRes

表示一个整形参数，变量或方法的返回值预期是一个id资源，例如：android.R.id.copy。

@IntDef

表示integer类型的注解元素，代表一个逻辑类型并且它的值应该是指定常量中的一个。如果设置IntDef#flag()属性的值为true，可以结合多个常量。例如：

@Retention(SOURCE)
@IntDef({NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS})
public @interface NavigationMode {}
public static final int NAVIGATION_MODE_STANDARD = 0;
public static final int NAVIGATION_MODE_LIST = 1;
public static final int NAVIGATION_MODE_TABS = 2;
...
public abstract void setNavigationMode(@NavigationMode int mode);
@NavigationMode
public abstract int getNavigationMode();

设置flag属性：

1
2
3

@IntDef(
      flag = true
      value = {NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS})

@IntegerRes

表示一个整形参数，变量或方法的返回值预期是一个integer资源，例如：android.R.integer.config_shortAnimTime。

@InterpolatorRes

表示一个整形参数，变量或方法的返回值预期是一个interpolator资源，例如：android.R.interpolator.cycle。

@IntRange

被注解的元素应该是一个给定范围的int or long。
例如：

@IntRange(from=0,to=255)
public int getAlpha() {
    ...
}

@Keep

当代码被混淆后编译的时候被注解的元素不应该被移除。这通常用在方法和只通过反射访问的类上，编译器可能认为代码是无用的。

@Keep
public void foo() {
    ...
}

@LayoutRes

表示一个整形参数，变量或方法的返回值预期是一个layout资源，例如：android.R.layout.list_content。

@MainThread

表示方法只能在主线程中被调用。如果在类上注解，表示类中所有方法都应该在主线程中被调用。例如：

1 2	@MainThread public void deliverResult(D data) { ... }

@MenuRes

表示一个整形参数，变量或方法的返回值预期是一个menu资源。

@NonNull

表示一个参数，变量或方法的返回值不可以是null。这是一个标记注解并且它没有具体属性。

@Nullable

表示一个参数，变量或方法的返回值可以是null。当修饰在调用方法的参数上时，表示参数可以为null并且方法会很好地处理它。通常用在可选参数上。当修饰在一个方法上，表示方法可以合法地返回null。这是一个标记注解并且它没有具体属性。

@PluralsRes

表示一个整形参数，变量或方法的返回值预期是一个plurals资源。

@Px

表示一个整形参数，变量或方法的返回值预期是一个pixel dimension。

@RawRes

表示一个整形参数，变量或方法的返回值预期是一个raw资源。

@RequiresApi

被注解的元素表示只能在给定的API或之上被调用。这和之前的@TargetApi注解目的相似，但更清晰地表达了对调用者的要求，超过方法的minSdkVersion而不是使用”suppress”警告。

@RequiresPermission

表示被注解的元素需要或可能需要一个或多个权限。例如请求一个权限：

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

@RequiresPermission(ACCESS_COARSE_LOCATION)
public abstract Location getLastKnownLocation(String provider);

请求集合中至少一个权限：

1 2	@RequiresPermission(anyOf = {ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION}) public abstract Location getLastKnownLocation(String provider);

请求多个权限：

1 2	@RequiresPermission(allOf = {ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION}) public abstract Location getLastKnownLocation(String provider);

对于content provider分别请求读和写权限：

1
2
3

@RequiresPermission.Read(@RequiresPermission(READ_HISTORY_BOOKMARKS))
@RequiresPermission.Write(@RequiresPermission(WRITE_HISTORY_BOOKMARKS))
public static final Uri BOOKMARKS_URI = Uri.parse("content://browser/bookmarks");

当指定在一个参数上，注解表明方法需要一个依赖于参数值的权限。例如，android.app.Activity.startActivity(android.content.Intent)：

1	public void startActivity(@RequiresPermission Intent intent) { ... }

注意这没有在注解中列出真正的权限名称。实际需要的权限将依赖于具体的Intent。例如：

1 2	Intent intent = new Intent(Intent.ACTION_CALL); startActivity(intent);

对于这个Intent实际需要的权限描述在它自己的Intent名称上：

1 2	@RequiresPermission(Manifest.permission.CALL_PHONE) public static final String ACTION_CALL = "android.intent.action.CALL";

@RequiresPermission.Read

指定所给的权限需要读操作。

@RequiresPermission.Write

指定所给的权限需要写操作。

@Size

表示被注解的元素应该有给定的大小或长度。“-1”表示未设置。通常用在一个参数或数组或集合的返回值上。例如：

1
2
3

public void getLocationInWindow(@Size(2) int[] location) {
  ...
}

@StringDef

被注解的String元素，代表一个逻辑类型并且它的值应该是指定常量中的一个。例如：

@Retention(SOURCE)
@StringDef({
  POWER_SERVICE,
  WINDOW_SERVICE,
  LAYOUT_INFLATER_SERVICE
})
public @interface ServiceName {}
public static final String POWER_SERVICE = "power";
public static final String WINDOW_SERVICE = "window";
public static final String LAYOUT_INFLATER_SERVICE = "layout_inflater";
...
public abstract Object getSystemService(@ServiceName String name);

@StringRes

表示一个整形参数，变量或方法的返回值预期是一个String资源，例如：android.R.string.ok。

@StyleableRes

表示一个整形参数，变量或方法的返回值预期是一个styleable资源，例如：android.R.styleable.TextView_text。

@StyleRes

表示一个整形参数，变量或方法的返回值预期是一个style资源，例如：android.R.style.TextAppearance。

@TransitionRes

表示一个整形参数，变量或方法的返回值预期是一个transition资源。

@UiThread

表示被注解的方法或构造函数只能在UI线程被调用。如果被注解的是一个类，那么类中所有方法都应该在UI线程被调用。例如：

1 2	@UiThread public abstract void setText(@NonNull String text) { ... }

@VisibleForTesting

表示类、方法或变量的可见性可放松，因此为了让代码可测试它有更宽广的可见范围。

@WorkerThread

表示被注解的方法或构造函数只能在工作线程被调用。如果被注解的是一个类，那么类中所有方法都应该在工作线程被调用。例如：

1 2	@WorkerThread protected abstract FilterResults performFiltering(CharSequence constraint);

@XmlRes

表示一个整形参数，变量或方法的返回值预期是一个XML资源。