Android Saripaar 註解詳解

寫這篇文章的緣由

在移動端通常不多使用複雜的表單，通常針對於屬性的更改都會打開一個新的頁面進行更改。雖然很少，可是也會有。若是一個頁面要輸入的內容包括姓名、地址、郵箱、手機號等，對各個屬性的驗證會很是麻煩，而且很是的不優雅。

因而，saripaar就出現了，一種基於規則的Android UI輸入驗證庫，經過註解便可標註驗證規則。

使用過程當中發現只有四個字：簡單好用。可是官方對註解的使用並無一份完整的文檔，故參考源碼整理了現有的全部註解（基於版本2.0.3）。

如何使用

導入依賴

第一步固然是導入依賴啦，可經過implementation 'com.mobsandgeeks:android-saripaar:(latest version)'導入saripaar，將(latest version)替換爲最新版本便可。

使用註解

對須要進行驗證的可輸入View加上註解來標註驗證規則，例

@Length(min = 6, max = 9)
private AppCompatEditText et1;

該註解表示et1中的輸入內容長度只能在6到9的閉區間。

實例化Validator

mValidator = new Validator(this);
mValidator.setValidationListener(this);

Validator負責驗證給定容器中的View，一般容器爲Activity或Fragment。但也能夠用包含View的其餘類做爲容器。

實現ValidationListener

public class MainActivity extends AppCompatActivity implements Validator.ValidationListener {

    // Code…

    @Override
    public void onValidationSucceeded() {
        Toast.makeText(this, "成功了！", Toast.LENGTH_LONG).show();
    }

    @Override
    public void onValidationFailed(List<ValidationError> errors) {
        Toast.makeText(this, "失敗了！", Toast.LENGTH_LONG).show();
    }
}

ValidationListener用戶監聽回調結果，並進行相應的處理。

調用驗證方法

btn.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View v) {
        mValidator.validate();
    }
});

其他的高級用法在此不作介紹，該文章主要介紹各個註解的使用。

註解

@AssertFalse

描述

用於判斷輸入內容是否爲false。

做用範圍

• CheckBox
• RadioButton
• RadioGroup

參數

• sequence：肯定規則的斷定順序，當單個View有多個規則時生效
• messageResId：錯誤提示文字的資源文件ID
• message：錯誤提示文字
  注：全部註解均有這三個參數，故以後註解省略不寫

---

@AssertTrue

描述

用於判斷輸入內容是否爲true。

做用範圍

• CheckBox
• RadioButton
• RadioGroup

---

@Checked

描述

用於判斷輸入內容是否爲預設值，默認預設值爲true。

做用範圍

• CheckBox
• RadioButton
• RadioGroup

參數

• value：用於設置預設值，默認爲true

---

@ConfirmEmail

描述

判斷當前輸入內容與被@Email註解的View的內容是否一致。
注：當前容器所持有的被@Email註解的View必須且只容許有一個。

做用範圍

• TextView

---

@ConfirmPassword

描述

判斷當前輸入內容與被@Password註解的View的內容是否一致。
注：當前容器所持有的被@Password註解的View必須且只容許有一個。

做用範圍

• TextView

---

@CreditCard

描述

判斷輸入內容是否符合信用卡卡號規則。

做用範圍

• TextView

參數

• cardTypes：是一個數組，用於肯定信用卡的類型，每種類型對應着不一樣的正則表達式
  • Type.AMEX，美國運通卡，對應着^(3[47]\d{13})$
  • Type.DINERS，大萊信用卡，對應着^(30[0-5]\d{11}|3095\d{10}|36\d{12}|3[8-9]\d{12})$
  • Type.DISCOVER，發現卡，對應着^(6011\d{12})$、^(64[4-9]\d{13})$和^(65\d{14})$
  • Type.MASTERCARD，萬事達卡，對應着^(5[1-5]\d{14})$
  • Type.VISA，簽證卡，對應着^(4)(\d{12}|\d{15})$
  • Type.NONE，不容許任何內置的信用卡，適用於自定義信用卡類型

---

@DecimalMax

描述

限制輸入內容的最大值，輸入內容會被強轉爲Double類型，若輸入文字不符合Double類型，會報ConversionException異常。

做用範圍

• TextView

參數

• value：double類型，最大值。

---

@DecimalMin

描述

限制輸入內容的最小值，輸入內容會被強轉爲Double類型，若輸入文字不符合Double類型，會報ConversionException異常。

做用範圍

• TextView

參數

• value：double類型，最小值。

---

@Digits

描述

判斷輸入內容是否爲數字，可定義整數部分以及小數部分的最大位數。

做用範圍

• TextView

參數

• integer：整數部分最大位數
• fraction：小數部分最大位數
  注：輸入內容需知足正則
  String.format("(\\d{0,%d})(\\.\\d{1,%d})?", integer, fraction);

---

@Domain

描述

判斷輸入內容是不是一個有效的域名。

做用範圍

• TextView

參數

• allowLocal：本地地址是否有效，默認爲false

---

@Email

描述

判斷輸入內容是不是一個有效的郵箱地址。

做用範圍

• TextView

參數

• allowLocal：本地地址是否有效，默認爲false

---

@Future

描述

判斷輸入的時間是不是將來時間（與當前時間相比）。輸入的時間必須知足相應的格式。

做用範圍

• TextView

參數

• dateFormat：時間的格式，默認爲dd-MM-yyyy，如下爲saripaar提供的格式（可自定義）
  • DateFormats.DMY：dd-MM-yyyy
  • DateFormats.YMD：yyyy-MM-dd
  • DateFormats.MDY：MM-dd-yyyy
  • DateFormats.DMY_TIME_12_HOURS：dd-MM-yyyy hh:mm aa
  • DateFormats.YMD_TIME_12_HOURS：yyyy-MM-dd hh:mm aa
  • DateFormats.MDY_TIME_12_HOURS：MM-dd-yyyy hh:mm aa
  • DateFormats.DMY_TIME_24_HOURS：dd-MM-yyyy kk:mm
  • DateFormats.YMD_TIME_24_HOURS：yyyy-MM-dd kk:mm
  • DateFormats.MDY_TIME_24_HOURS：MM-dd-yyyy kk:mm
• dateFormatResId：時間格式的資源ID

---

@IpAddress

描述

判斷輸入的內容是不是一個IP，IPv4或IPv6

做用範圍

• TextView

---

@Isbn

描述

判斷輸入的內容是不是一個Isbn，即國際標準書號。

做用範圍

• TextView

---

@Length

描述

限制輸入內容的文本長度，可自定義最大長度和最小長度。

做用範圍

• TextView

參數

• min：文本的最小長度，默認爲Integer.MIN_VALUE
• max：文本的最大長度，默認爲Integer.MAX_VALUE
• trim：是否須要先作trim操做，默認爲false

---

@Max

描述

限制輸入內容的最大值，輸入內容會被強轉爲Integer類型，若輸入文字不符合Integer類型，會報ConversionException異常。

做用範圍

• TextView

參數

• value：int類型，最大值。

---

@Min

描述

限制輸入內容的最小值，輸入內容會被強轉爲Integer類型，若輸入文字不符合Integer類型，會報ConversionException異常。

做用範圍

• TextView

參數

• value：int類型，最小值。

---

@NotEmpty

描述

判斷輸入內容是否非空。

做用範圍

• TextView

參數

• trim：判斷以前是否要先trim，默認爲false
• emptyText：設置「空字符串」，可自定義一段文本，當輸入此文本是則爲空
• emptyTextResId：設置「空字符串」的資源文件

---

@Order

描述

肯定校驗字段的順序。當一個容器有多個View須要檢驗時，可經過該註解肯定校驗順序。

做用範圍

• TextView
• CheckBox
• RadioButton
• RadioGroup
• Spinner

參數

• value：int類型，用於肯定順序

---

@Password

描述

用於校驗文本是否符合密碼的規則。

做用範圍

• TextView

參數

• min：最小字符數，默認爲6
• scheme：Scheme類型，利用正則肯定密碼的輸入格式，只能爲Scheme類型，不可自定義，默認爲Password.Scheme.ANY
  • Password.Scheme.ANY：.+
  • Password.Scheme.ALPHA：\w+
  • Password.Scheme.ALPHA_MIXED_CASE：(?=.*[a-z])(?=.*[A-Z]).+
  • Password.Scheme.NUMERIC：\d+
  • Password.Scheme.ALPHA_NUMERIC：(?=.*[a-zA-Z])(?=.*[\d]).+
  • Password.Scheme.ALPHA_NUMERIC_MIXED_CASE：(?=.*[a-z])(?=.*[A-Z])(?=.*[\d]).+
  • Password.Scheme.ALPHA_NUMERIC_SYMBOLS：(?=.*[a-zA-Z])(?=.*[\d])(?=.*([^\w])).+
  • Password.Scheme.ALPHA_NUMERIC_MIXED_CASE_SYMBOLS：(?=.*[a-z])(?=.*[A-Z])(?=.*[\d])(?=.*([^\w])).+

---

@Past

描述

判斷輸入的時間是不是過去時間（與當前時間相比）。輸入的時間必須知足相應的格式。

做用範圍

• TextView

參數

• dateFormat：時間的格式，默認爲dd-MM-yyyy，如下爲saripaar提供的格式（可自定義）
  • DateFormats.DMY：dd-MM-yyyy
  • DateFormats.YMD：yyyy-MM-dd
  • DateFormats.MDY：MM-dd-yyyy
  • DateFormats.DMY_TIME_12_HOURS：dd-MM-yyyy hh:mm aa
  • DateFormats.YMD_TIME_12_HOURS：yyyy-MM-dd hh:mm aa
  • DateFormats.MDY_TIME_12_HOURS：MM-dd-yyyy hh:mm aa
  • DateFormats.DMY_TIME_24_HOURS：dd-MM-yyyy kk:mm
  • DateFormats.YMD_TIME_24_HOURS：yyyy-MM-dd kk:mm
  • DateFormats.MDY_TIME_24_HOURS：MM-dd-yyyy kk:mm
• dateFormatResId：時間格式的資源ID

---

@Pattern

描述

判斷輸入的內容是否知足正則表達式。

做用範圍

• TextView

參數

• regex：正則表達式
• caseSensitive：是否區分大小寫

---

@Select

描述

判斷選擇的索引是否等於默認值，若是不等於則經過，默認值爲0。

做用範圍

• Spinner

參數

• defaultSelection：設置默認值

---

@Url

描述

判斷輸入的內容是不是一個url。

做用範圍

• TextView

參數

• schemes：是一個數組，url的協議數組，可自定義，默認爲{"http", "https", "ftp"}
• allowFragments：url片斷是否容許經過，默認爲true

---

對於@Optional和@Or

雖然該版本已經有了這兩個註解，可是並不能使用，參考做者在stackoverflow上的回覆，註解將會在2.1.0版本上線

總結

本篇文章簡單介紹了Android Saripaar的用法，並着重列舉了各個註解的做用以及各個參數的意思，方便之後的查詢。

經過閱讀源碼對saripaar有了更深的認識，並對基於註解的框架有了一個完備的認知。

之後若是有時間的話總結一下Android Saripaar實現的細節。