運算式語言可讓您編寫運算式,處理檢視畫面派發的事件。資料繫結程式庫會自動產生必要的類別,將版面配置中的檢視畫面與資料物件繫結。
資料繫結版面配置檔案略有不同,且開頭為 layout 的根標記,接著是 data 元素和 view 根元素。此檢視畫面元素即為非繫結版面配置檔案中的根。以下程式碼顯示版面配置檔案範例:
<?xml version="1.0" encoding="utf-8"?>
<layout xmlns:android="http://schemas.android.com/apk/res/android">
<data>
<variable name="user" type="com.example.User"/>
</data>
<LinearLayout
android:orientation="vertical"
android:layout_width="match_parent"
android:layout_height="match_parent">
<TextView android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="@{user.firstName}"/>
<TextView android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="@{user.lastName}"/>
</LinearLayout>
</layout>
data 中的 user 變數描述了可用於此版面配置的屬性:
<variable name="user" type="com.example.User" />
版面配置中的運算式會使用 @{} 語法寫入屬性。在以下範例中,TextView 文字設為 user 變數的 firstName 屬性:
<TextView android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="@{user.firstName}" />
資料物件
假設您有一個用於描述 User 實體的純物件:
Kotlin
data class User(val firstName: String, val lastName: String)
Java
public class User { public final String firstName; public final String lastName; public User(String firstName, String lastName) { this.firstName = firstName; this.lastName = lastName; } }
這類物件的資料不會變更。在應用程式中,資料通常只會讀取一次,之後就不會再變更。您也可以使用遵循一組慣例的物件,例如在 Java 程式設計語言中使用存取子方法,如以下範例所示:
Kotlin
// Not applicable in Kotlin. data class User(val firstName: String, val lastName: String)
Java
public class User { private final String firstName; private final String lastName; public User(String firstName, String lastName) { this.firstName = firstName; this.lastName = lastName; } public String getFirstName() { return this.firstName; } public String getLastName() { return this.lastName; } }
從資料繫結的角度來看,這兩個類別是等效的。用於 android:text 屬性的運算式 @{user.firstName} 會存取前一個類別中的 firstName 欄位,以及後一個類別中的 getFirstName() 方法。如果存在 firstName() 方法,也會解析為該方法。
繫結資料
系統會為每個版面配置檔案產生繫結類別。根據預設,類別名稱會根據版面配置檔案名稱轉換為 Pascal 命名法,並加上 Binding 後置字元。舉例來說,上述版面配置檔案名稱為 activity_main.xml,因此對應產生的繫結類別為 ActivityMainBinding。
這個類別會保留版面配置屬性 (例如 user 變數) 到版面配置檢視畫面的所有繫結,並知道如何為繫結運算式指派值。建議您在加載版面配置時建立繫結,如以下範例所示:
Kotlin
override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val binding: ActivityMainBinding = DataBindingUtil.setContentView( this, R.layout.activity_main) binding.user = User("Test", "User") }
Java
@Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); ActivityMainBinding binding = DataBindingUtil.setContentView(this, R.layout.activity_main); User user = new User("Test", "User"); binding.setUser(user); }
在執行階段,應用程式會在 UI 中顯示「Test」使用者。或者,您也可以使用 LayoutInflater 取得檢視畫面,如以下範例所示:
Kotlin
val binding: ActivityMainBinding = ActivityMainBinding.inflate(getLayoutInflater())
Java
ActivityMainBinding binding = ActivityMainBinding.inflate(getLayoutInflater());
如果您在 Fragment、ListView 或 RecyclerView 轉接器中使用資料繫結項目,建議您使用繫結類別或 DataBindingUtil 類別的 inflate() 方法,如以下程式碼範例所示:
Kotlin
val listItemBinding = ListItemBinding.inflate(layoutInflater, viewGroup, false) // or val listItemBinding = DataBindingUtil.inflate(layoutInflater, R.layout.list_item, viewGroup, false)
Java
ListItemBinding binding = ListItemBinding.inflate(layoutInflater, viewGroup, false); // or ListItemBinding binding = DataBindingUtil.inflate(layoutInflater, R.layout.list_item, viewGroup, false);
運算式語言
常見功能
運算式語言與代管程式碼中的運算式非常相似。您可以在運算式語言中使用下列運算子和關鍵字:
- 數學:
+ - / * % - 字串串連:
+ - 邏輯檢視表:
&& || - 二進位:
& | ^ - 一元:
+ - ! ~ - 轉折:
>> >>> << - 比較:
== > < >= <=(<必須逸出為<) instanceof- 分組依據:
() - 常值,例如字元、字串、數字、
null - 投放
- 方法呼叫
- 欄位存取權
- 陣列存取:
[] - 三元運算子:
?:
例如:
android:text="@{String.valueOf(index + 1)}"
android:visibility="@{age > 13 ? View.GONE : View.VISIBLE}"
android:transitionName='@{"image_" + id}'
缺少作業
您可以在代管程式碼中使用的運算式語法,缺少下列運算:
thissupernew- 明確一般叫用
空值聯合運算子
空值聯合運算子 (??) 會選擇左側運算元 (如果不是 null),或右側運算元 (如果前者是 null):
android:text="@{user.displayName ?? user.lastName}"
這在功能上等同於下列項目:
android:text="@{user.displayName != null ? user.displayName : user.lastName}"
屬性參考資料
運算式可以使用下列格式參照類別中的屬性,這與欄位、getter 和 ObservableField 物件的格式相同:
android:text="@{user.lastName}"
避免空值指標例外狀況
產生的資料繫結程式碼會自動檢查 null 值,並避免空值指標例外狀況。舉例來說,在運算式 @{user.name} 中,如果 user 為空值,user.name 會指派預設值 null。如果您參照 user.age,其中 age 的類型為 int,則資料繫結會使用 0 的預設值。
查看參考資料
運算式可以使用下列語法,依 ID 參照版面配置中的其他檢視畫面:
android:text="@{exampleText.text}"
在以下範例中,TextView 檢視畫面會參照相同版面配置中的 EditText 檢視畫面:
<EditText
android:id="@+id/example_text"
android:layout_height="wrap_content"
android:layout_width="match_parent"/>
<TextView
android:id="@+id/example_output"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="@{exampleText.text}"/>
集合
您可以使用 [] 運算子存取常見的集合,例如陣列、清單、稀疏清單和對應,以便操作。
<data>
<import type="android.util.SparseArray"/>
<import type="java.util.Map"/>
<import type="java.util.List"/>
<variable name="list" type="List<String>"/>
<variable name="sparse" type="SparseArray<String>"/>
<variable name="map" type="Map<String, String>"/>
<variable name="index" type="int"/>
<variable name="key" type="String"/>
</data>
...
android:text="@{list[index]}"
...
android:text="@{sparse[index]}"
...
android:text="@{map[key]}"
您也可以使用 object.key 標記法參照對應中的值。例如,您可以將上述範例中的 @{map[key]} 替換為 @{map.key}。
字串常值
您可以使用單引號括住屬性值,這樣就能在運算式中使用雙引號,如以下範例所示:
android:text='@{map["firstName"]}'
您也可以使用雙引號括住屬性值。此時,字串常值必須以反引號 ` 括住,如下所示:
android:text="@{map[`firstName`]}"
資源
運算式可透過下列語法參照應用程式資源:
android:padding="@{large? @dimen/largePadding : @dimen/smallPadding}"
您可以提供參數,評估格式字串和複數:
android:text="@{@string/nameFormat(firstName, lastName)}"
android:text="@{@plurals/banana(bananaCount)}"
android:text="@{@string/example_resource(user.lastName, exampleText.text)}"
如果複數形式採用多個參數,請傳遞所有參數:
Have an orange
Have %d oranges
android:text="@{@plurals/orange(orangeCount, orangeCount)}"
部分資源需要明確的類型評估,如下表所示:
| 類型 | 一般參考資料 | 運算式參考資料 |
|---|---|---|
String[] |
@array |
@stringArray |
int[] |
@array |
@intArray |
TypedArray |
@array |
@typedArray |
Animator |
@animator |
@animator |
StateListAnimator |
@animator |
@stateListAnimator |
color int |
@color |
@color |
ColorStateList |
@color |
@colorStateList |
事件處理
資料繫結可讓您編寫運算式處理從檢視畫面分派的事件,例如 onClick() 方法。事件屬性名稱由事件監聽器方法的名稱決定,但有少數例外。舉例來說,View.OnClickListener 具有 onClick() 方法,因此這個事件的屬性為 android:onClick。
點擊事件有一些專門的事件處理常式,需要使用 android:onClick 以外的屬性,以免發生衝突。您可以使用下列屬性,避免這類衝突:
| 類別 | 事件監聽器 setter | 屬性 |
|---|---|---|
SearchView |
setOnSearchClickListener(View.OnClickListener) |
android:onSearchClick |
ZoomControls |
setOnZoomInClickListener(View.OnClickListener) |
android:onZoomIn |
ZoomControls |
setOnZoomOutClickListener(View.OnClickListener) |
android:onZoomOut |
您可以使用下列兩種機制來處理事件,詳情請參閱後續章節:
- 方法參照:在運算式中,您可以參照符合事件監聽器方法簽章的方法。當運算式評估為方法參照時,資料繫結會將方法參照和擁有者物件包裝在事件監聽器中,並在目標檢視畫面上設定該事件監聽器。如果運算式評估結果為
null,資料繫結不會建立事件監聽器,而是設定null事件監聽器。 - 事件監聽器繫結:這些是事件發生時評估的 lambda 運算式。資料繫結一律會建立事件監聽器,並在檢視畫面上設定。事件調度後,事件監聽器會評估 lambda 運算式。
方法參考資料
您可以直接將事件繫結至處理常式方法,類似於將 android:onClick 指派給活動中的方法。與 View onClick 屬性相比,其優點在於運算式會在編譯時間處理。因此,如果方法不存在或簽章不正確,您會收到編譯時間錯誤。
方法參照和事件監聽器繫結之間的主要差異,在於實際的事件監聽器實作是在資料繫結時建立,而不是在事件觸發時建立。如果您想在事件發生時評估運算式,請使用事件監聽器繫結。
如要將事件指派給處理常式,請使用一般繫結運算式,並將值設為要呼叫的方法名稱。舉例來說,請參考以下版面配置資料物件範例:
Kotlin
class MyHandlers { fun onClickFriend(view: View) { ... } }
Java
public class MyHandlers { public void onClickFriend(View view) { ... } }
繫結運算式可將檢視畫面的點擊事件監聽器指派給 onClickFriend() 方法,如下所示:
<?xml version="1.0" encoding="utf-8"?>
<layout xmlns:android="http://schemas.android.com/apk/res/android">
<data>
<variable name="handlers" type="com.example.MyHandlers"/>
<variable name="user" type="com.example.User"/>
</data>
<LinearLayout
android:orientation="vertical"
android:layout_width="match_parent"
android:layout_height="match_parent">
<TextView android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="@{user.firstName}"
android:onClick="@{handlers::onClickFriend}"/>
</LinearLayout>
</layout>
事件監聽器繫結
事件監聽器繫結是指在事件發生時執行的繫結運算式。做法類似於方法參照,但事件監聽器繫結可讓您執行任意資料繫結運算式。這項功能適用於 Gradle 2.0 以上版本的 Android Gradle 外掛程式。
在方法參照中,方法的參數必須與事件監聽器的參數相符。在事件監聽器繫結中,只有傳回值必須與事件監聽器的預期傳回值相符,除非預期值為 void。例如,假設下列展示器類別具有 onSaveClick() 方法:
Kotlin
class Presenter { fun onSaveClick(task: Task){} }
Java
public class Presenter { public void onSaveClick(Task task){} }
您可以將點擊事件繫結至 onSaveClick() 方法,如下所示:
<?xml version="1.0" encoding="utf-8"?>
<layout xmlns:android="http://schemas.android.com/apk/res/android">
<data>
<variable name="task" type="com.android.example.Task" />
<variable name="presenter" type="com.android.example.Presenter" />
</data>
<LinearLayout android:layout_width="match_parent" android:layout_height="match_parent">
<Button android:layout_width="wrap_content" android:layout_height="wrap_content"
android:onClick="@{() -> presenter.onSaveClick(task)}" />
</LinearLayout>
</layout>
在運算式中使用回呼時,資料繫結會自動建立必要的事件監聽器,並為事件註冊。當檢視畫面觸發事件時,資料繫結會評估指定的運算式。與一般繫結運算式一樣,在評估這些事件監聽器運算式時,您會取得資料繫結的空值和執行緒安全。
在上述範例中,傳遞至 onClick(View) 的 view 參數並未定義。事件監聽器繫結提供兩種事件監聽器參數選項:您可以忽略方法的所有參數,或為所有參數命名。如果您想為參數命名,可以在運算式中使用這些參數。例如,您可以將上述運算式寫成:
android:onClick="@{(view) -> presenter.onSaveClick(task)}"
如要在運算式中使用參數,請按照下列步驟操作:
Kotlin
class Presenter { fun onSaveClick(view: View, task: Task){} }
Java
public class Presenter { public void onSaveClick(View view, Task task){} }
android:onClick="@{(theView) -> presenter.onSaveClick(theView, task)}"
您也可以使用含有多個參數的 lambda 運算式:
Kotlin
class Presenter { fun onCompletedChanged(task: Task, completed: Boolean){} }
Java
public class Presenter { public void onCompletedChanged(Task task, boolean completed){} }
<CheckBox android:layout_width="wrap_content" android:layout_height="wrap_content"
android:onCheckedChanged="@{(cb, isChecked) -> presenter.completeChanged(task, isChecked)}" />
如果您監聽的事件傳回的值類型不是 void,則運算式也必須傳回相同類型的值。舉例來說,如要監聽輕觸並按住 (長按) 事件,運算式必須傳回布林值。
Kotlin
class Presenter { fun onLongClick(view: View, task: Task): Boolean { } }
Java
public class Presenter { public boolean onLongClick(View view, Task task) { } }
android:onLongClick="@{(theView) -> presenter.onLongClick(theView, task)}"
如果運算式因 null 物件而無法評估,資料繫結會傳回該類型的預設值,例如參照類型的 null、int 的 0 或 boolean 的 false。
如需使用含有述詞的運算式 (例如三元運算式),可以使用 void 做為符號:
android:onClick="@{(v) -> v.isVisible() ? doSomething() : void}"
避免使用複雜的事件監聽器
事件監聽器運算式功能強大,可讓程式碼更容易閱讀。另一方面,含有複雜運算式的事件監聽器會使版面配置更難閱讀及維護。請盡量簡化運算式,例如將 UI 中的可用資料傳遞至回呼方法。在從事件監聽器運算式叫用的回呼方法中,實作任何商業邏輯。
匯入、變數和包含
資料繫結程式庫提供匯入、變數和包含等功能。匯入作業可讓您在版面配置檔案中輕鬆參照類別。變數可讓您描述可用於繫結運算式的屬性。Includes 可讓您在應用程式中重複使用複雜的版面配置。
匯入
匯入功能可讓您在版面配置檔案中參照類別,就像在受管理程式碼中一樣。您可以在 data 元素中使用零或多個 import 元素。以下程式碼範例會將 View 類別匯入版面配置檔案:
<data>
<import type="android.view.View"/>
</data>
匯入 View 類別後,您就可以從繫結運算式中參照該類別。以下範例說明如何參照 View 類別的 VISIBLE 和 GONE 常數:
<TextView
android:text="@{user.lastName}"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:visibility="@{user.isAdult ? View.VISIBLE : View.GONE}"/>
類型別名
如果類別名稱衝突,您可以將其中一個類別重新命名為別名。以下範例會將 com.example.real.estate 套件中的 View 類別重新命名為 Vista:
<import type="android.view.View"/>
<import type="com.example.real.estate.View"
alias="Vista"/>
接著,您可以在版面配置檔案中使用 Vista 參照 com.example.real.estate.View,並使用 View 參照 android.view.View。
匯入其他類別
您可以在變數和運算式中,將匯入的類型做為類型參照。以下範例顯示 User 和 List 做為變數類型:
<data>
<import type="com.example.User"/>
<import type="java.util.List"/>
<variable name="user" type="User"/>
<variable name="userList" type="List<User>"/>
</data>
您可以使用匯入的類型來轉換運算式的部分內容。以下範例會將 connection 屬性轉換為 User 類型:
<TextView
android:text="@{((User)(user.connection)).lastName}"
android:layout_width="wrap_content"
android:layout_height="wrap_content"/>
在運算式中參照靜態欄位和方法時,也可以使用匯入的類型。下列程式碼會匯入 MyStringUtils 類別,並參照其 capitalize 方法:
<data>
<import type="com.example.MyStringUtils"/>
<variable name="user" type="com.example.User"/>
</data>
…
<TextView
android:text="@{MyStringUtils.capitalize(user.lastName)}"
android:layout_width="wrap_content"
android:layout_height="wrap_content"/>
就像在代管程式碼中一樣,java.lang.* 會自動匯入。
變數
您可以在 data 元素中使用多個 variable 元素。每個 variable 元素都會描述可在版面配置上設定的屬性,以便在版面配置檔案中的繫結運算式中使用。以下範例宣告 user、image 和 note 變數:
<data>
<import type="android.graphics.drawable.Drawable"/>
<variable name="user" type="com.example.User"/>
<variable name="image" type="Drawable"/>
<variable name="note" type="String"/>
</data>
變數類型會在編譯時間檢查,因此如果變數實作 Observable 或屬於可觀測集合,則必須反映在類型中。如果變數是未實作 Observable 介面的基礎類別或介面,則「不會」觀測變數。
如果各種設定 (例如橫向或直向) 有不同的版面配置檔案,系統會合併變數。這些版面配置檔案之間不得有衝突的變數定義。
產生的繫結類別會為每個所述變數提供 setter 和 getter。在呼叫 setter 之前,變數會採用預設的代管程式碼值,例如參照類型為 null、int 為 0、boolean 為 false 等。
系統會產生名為 context 的特殊變數,以便視需要用於繫結運算式。context 的值是根層級檢視畫面 getContext() 方法中的 Context 物件。context 變數會由具有該名稱的明確變數宣告覆寫。
收錄
您可以使用屬性中的應用程式命名空間和變數名稱,將變數從包含版面配置傳遞至包含版面配置的繫結。以下範例顯示 name.xml 和 contact.xml 版面配置檔案中包含的 user 變數:
<?xml version="1.0" encoding="utf-8"?>
<layout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:bind="http://schemas.android.com/apk/res-auto">
<data>
<variable name="user" type="com.example.User"/>
</data>
<LinearLayout
android:orientation="vertical"
android:layout_width="match_parent"
android:layout_height="match_parent">
<include layout="@layout/name"
bind:user="@{user}"/>
<include layout="@layout/contact"
bind:user="@{user}"/>
</LinearLayout>
</layout>
資料繫結不支援將 include 做為 merge 元素的直接子項。舉例來說,系統不支援以下版面配置:
<?xml version="1.0" encoding="utf-8"?>
<layout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:bind="http://schemas.android.com/apk/res-auto">
<data>
<variable name="user" type="com.example.User"/>
</data>
<merge><!-- Doesn't work -->
<include layout="@layout/name"
bind:user="@{user}"/>
<include layout="@layout/contact"
bind:user="@{user}"/>
</merge>
</layout>