Android 注解指南

来源 https://juejin.im/entry/58fc7ca744d9040069e65197

日常开发中，注解能够帮助我们写出更好更优秀的代码，为了更好地支持 Android 开发，在已有的 android.annotation 基础上，Google 开发了 android.support.annotation 扩展包，共计50个注解，帮助开发者们写出更优秀的程序。

官网链接：developer.android.google.cn/reference/a…、developer.android.google.cn/reference/a…

一览

示例详解

AnimatorRes

1.在 res 文件夹下创建 animator 子文件夹

2.在 animator 文件夹下创建 scale.xml 文件

<set xmlns:android="http://schemas.android.com/apk/res/android"></set>

3.在需要的地方如下调用：

@AnimatorRes
public int returnAnimator() {
    return R.animator.scale;
}

如果将 return R.animator.scale; 改成 return 1; 或 return R.string.test; 等均会报错。

AnimRes

1.在 res 文件夹下创建 anim 子文件夹

2.在 anim 文件夹下创建 scale.xml 文件

<set xmlns:android="http://schemas.android.com/apk/res/android"></set>

3.在需要的地方如下调用：

@AnimRes
public int returnAnim() {
    return R.anim.scale;
}

如果将 return R.anim.scale; 改成 return 1; 或 return R.string.test; 等均会报错。

AnyRes

在需要的地方如下调用：

@AnyRes
public int returnAny() {
    return 1;
}

如果能提前知道返回值的具体资源类型，建议将 AnyRes 换成具体的资源类型，如 StringRes 或 DrawableRes 等。

AnyThread

在需要的地方如下调用：

@AnyThread
public void test() {
    //.....
}

ArrayRes

1.在 values 文件夹下创建 arrays.xml 文件

2.在 arrays.xml 文件中添加名为 names 的子项

<resources>
    <array name="names">1, 2, 3</array>
</resources>

3.在需要的地方如下调用：

@ArrayRes
public int returnArray() {
    return R.array.names;
}

如果将 return R.array.names; 改成 return 1; 或 return R.string.test; 等均会报错。

AttrRes

1.在 attrs.xml 文件中添加名为 CircleView 的子项

<resources>
    <declare-styleable name="CircleView">
        <attr name="circle_color" format="color"/>
    </declare-styleable>
</resources>

2.在需要的地方如下调用：

@AttrRes
public int returnAttr() {
    return R.attr.circle_color;
}

如果将 return R.attr.circle_color; 改成 return 1; 或 return R.string.test; 等均会报错。

BinderThread

1.表明指定的元素只能运行在 Binder 线程：

@BinderThread
public void test() {
    // ...
}

BoolRes

1.在 values 文件夹下创建 bools.xml 文件

2.在 bools.xml 文件中添加名为 isHide 的子项

<resources>
    <bool name="isHide">true</bool>
</resources>

3.在需要的地方如下调用：

@BoolRes
public int returnBool() {
    return R.bool.isHide;
}

如果将 return R.bool.isHide; 改成 return 1; 或 return R.string.test; 等均会报错。

CallSuper

1.在 BaseActivity 中创建一个 init() 方法，我们在其中初始化一些 Activity 共有的初始化操作：

public class BaseActivity extends AppCompatActivity {
    // ...

    @CallSuper
    public void init() {
        // Activity 共有的初始化操作...
    }
}

2.在具体 Activity 中继承 BaseActivity 并调用 init() 完成初始化操作：

public class MainActivity extends BaseActivity {
    // ...

    @Override
    public void init() {
        // super.init();
    }
}

如果在 init() 方法中不通过 super.init() 等方式调用父类方法，那么就会报一个 warning，编译器将会建议你调用 super.init()。

CheckResult

1.创建一个 add() 方法：

@CheckResult
public int add() {
    return 666;
}

2.调用该方法的地方不能忽略它的返回值：

add();  // error
int num = add();  // ok

ColorInt

ColorLong

ColorRes

1.在 colors.xml 下添加名为 colorAccent 的子项

<resources>
    <color name="colorAccent">#FF4081</color>
</resources>

2.在需要的地方如下调用：

@ColorRes
public int returnColorRes() {
    return R.color.colorAccent;
}

如果将 return R.color.colorAccent; 改成 return 1; 或 return R.string.test; 等均会报错。

DimenRes

1.在 dimens.xml 下添加名为 textview_height 的子项

<resources>
    <dimen name="textview_height">25dp</dimen>
</resources>

2.在需要的地方如下调用：

@DimenRes
public int returnDimenRes() {
    return R.dimen.textview_height;
}

如果将 return R.dimen.textview_height; 改成 return 1; 或 return R.string.test; 等均会报错。

Dimension

1.在需要的地方如下调用：

@Dimension(unit = Dimension.DP)
public int returnDimenRes() {
    return 666;
}

注：该注解仅表明希望该方法返回的是一个 DP 的值，而返回值本身和 DP 无关

DrawableRes

1..在 drawable.xml 文件中添加名为 btn_test 的子项

<selector xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:drawable="@drawable/btn_focused"
          android:state_window_focused="true"/>
    <item android:drawable="@drawable/btn_normal"/>
</selector>

3.在需要的地方如下调用：

@DrawableRes
public int returnDrawRes() {
    return R.drawable.btn_test;
}

如果将 return R.drawable.btn_test; 改成 return 1; 或 return R.string.test; 等均会报错。

FloatRange

1.用该注解所标记的元素只能返回指定范围内的浮点型数字，例如：

@FloatRange(from = -0.5F, to = 0.5F)
public float returnFloat() {
    // return 0.8F; // error
    return 0.2F;    // ok
}

FractionRes

同 ColorRes 等。

IdRes

同 ColorRes 等。

IntDef

1.用该注解修饰一个注解：

@IntDef({LAST, NOW, NEXT})
@Retention(RetentionPolicy.SOURCE)
public @interface Year {
    int LAST = 2016;
    int NOW = 2017;
    int NEXT = 2018;
}

2.再用被修饰的注解去注解指定元素：

@Year
public int returnYear() {
    // return 666; // warning
    return Year.LAST;   // ok
}

IntegerRes

同 BoolRes 等。

InterpolatorRes

同 ColorRes 等。

IntRange

同FloatRange

Keep

1.对于不希望被混淆的代码我们使用该注解：

@Keep
public void test() {
    // ...
}

LayoutRes

同 ColorRes 等。

MainThread

同 BinderThread，表指定元素只能运行在主线程。

MenuRes

同 ColorRes 等。

NonNull

1.如果被注解的元素不可以取空值的话，我们使用该注解：

public Intent start2Activity(@NonNull String data) {
    Intent intent = new Intent(MainActivity.this, SecondActivity.class);
    intent.putExtra("DATA", data);

    return intent;
}

2.在调用该方法处如果我们传入 null 作为参数编译器将会给出 warning：

public void test() {
    start2Activity(null);  //warning，passing ‘null‘ argument to paramter annotated as @NonNull
}

Nullable

同 NonNull，意义相反，表被注解的元素可为空。

PluralsRes

同 BoolRes 等。

Px

实际等同于 Dimension 中 unit 取 PX 时的意义。

RawRes

同 BoolRes 等。

RequiresApi

1.当你使用的代码（例：API 11）不支持你当前所支持的最低版本（例：API 10）时，使用该注解注明：

@Override
protected void onCreate(Bundle savedInstanceState) {
    getWindow().getDecorView().setSystemUiVisibility(View.SYSTEM_UI_FLAG_FULLSCREEN
            | View.SYSTEM_UI_FLAG_HIDE_NAVIGATION | View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY);
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
}

2.getWindow().getDecorView().setSystemUiVisibility(View.SYSTEM_UI_FLAG_FULLSCREEN| View.SYSTEM_UI_FLAG_HIDE_NAVIGATION | View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY); 所支持最低版本为 API 11，如果你的项目最低兼容到11以下的版本，那么编译器将会给出 warning，解决方法有三：

• 使用 RequiresApi 注解：

  @Override
  @RequiresApi(api = Build.VERSION_CODES.HONEYCOMB)
  protected void onCreate(Bundle savedInstanceState) {
          getWindow().getDecorView().setSystemUiVisibility(View.SYSTEM_UI_FLAG_FULLSCREEN
          | View.SYSTEM_UI_FLAG_HIDE_NAVIGATION | View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY);
          super.onCreate(savedInstanceState);
          setContentView(R.layout.activity_main);
  }
  

• 使用 Target 注解：

  @Override
  @TargetApi(Build.VERSION_CODES.HONEYCOMB)
  protected void onCreate(Bundle savedInstanceState) {
      getWindow().getDecorView().setSystemUiVisibility(View.SYSTEM_UI_FLAG_FULLSCREEN
          | View.SYSTEM_UI_FLAG_HIDE_NAVIGATION | View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY);
      super.onCreate(savedInstanceState);
      setContentView(R.layout.activity_main);
  }
  

• 使用 if 包裹相应代码块：

  @Override
  protected void onCreate(Bundle savedInstanceState) {
      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB) {
          getWindow().getDecorView().setSystemUiVisibility(View.SYSTEM_UI_FLAG_FULLSCREEN
                  | View.SYSTEM_UI_FLAG_HIDE_NAVIGATION | View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY);
      }
      super.onCreate(savedInstanceState);
      setContentView(R.layout.activity_main);
  }
  

注：网上大篇文章提到使用 RequiresApi 或 Target 注解能够解决低版本兼容问题，实际上它只是作为一个对程序员的提醒，告诉程序员这块代码只有在指定版本及以上才能使用，而并不是也不能用来解决兼容问题，指定代码块在低于指定版本上是不会运行的！

RequiresPermission

1.表注解的元素需要相应的权限：

@RequiresPermission(Manifest.permission.INTERNET)
private void netOperation() {
}

2.如果你的项目没有在 AndroidMenifest.xml 中声明相应的权限，那么调用该方法的地方将会抛出 Missing permissions required by MainActivity.netOperation:android.permission.INTERNET warning，所以同样的，这个注解只是告诉程序员指定的元素需要某个权限，而不代表使用了该注解后就不需要注册权限。

RequiresPermission.Read

同 RequiresPermission。

RequiresPermission.Write

同 RequiresPermission。

RestrictTo

1.该注解用于想要指定访问元素权限的范围，例如我们在 BaseActivity 中对 init() 方法使用该注解：

@RestrictTo(RestrictTo.Scope.SUBCLASSES)
public void init() {

}

2.这是限定了该方法只能由 BaseActivity 子类才能访问到，如果是非子类访问，则会被编译器抛出 BaseActivity.int() can only be called from subclass warning。

注：除 RestrictTo.Scope.SUBCLASSES 之外，还有其它几种枚举类型，详情可自行查看源码

Size

1.常用于限定数组大小的场合：

public @Size(2) int[] returnArr() {
    int[] arr = new int[3];
    int[] array = new int[2];
    // return arr; // Size must be exactly 2.
    return array； // ok
}

StringDef

同 IntDef。

StringRes

同 ColorRes 等。

StyleableRes

同 ColorRes 等。

StyleRes

同 ColorRes 等。

TransitionRes

同 ColorRes 等。

UiThread

同 BinderThread，表指定元素只能运行在 UI 线程。

WorkerThread

同 BinderThread，表指定元素只能运行在工作线程。

XmlRes

同 ColorRes 等。

SuppressLint

1.在想要屏蔽 Lint 静态检测工具的提示的地方添加该注解：

@SuppressLint("HandlerLeak")
private Handler mHandler = new Handler(){
    @Override
    public void handleMessage(Message msg) {
        // ...
    }
};

TargetApi

见 RequiresApi。

============= End

Android 注解指南