Safe Args

建議您使用 Safe Args Gradle 外掛程式在目的地之間導覽。此外掛程式會產生物件和建構工具類別，方便您在目的地之間進行類型安全導覽。使用 Safe Args 在目的地之間導覽及在目的地之間傳遞資料。

啟用 Safe Args

如要在專案中新增 Safe Args，請在頂層 build.gradle 檔案中納入下列 classpath：

buildscript {
    repositories {
        google()
    }
    dependencies {
        def nav_version = "2.7.7"
        classpath "androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version"
    }
}

buildscript {
    repositories {
        google()
    }
    dependencies {
        val nav_version = "2.7.7"
        classpath("androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version")
    }
}

您也必須從兩個可用的外掛程式之中選擇一項套用。

如要產生適合 Java 或混用 Java 及 Kotlin 模組的 Java 語言程式碼，請將以下這一行新增至應用程式或模組的 build.gradle 檔案：

plugins {
  id 'androidx.navigation.safeargs'
}

plugins {
    id("androidx.navigation.safeargs")
}

或者，如要產生適合 Kotlin 模組的 Kotlin 程式碼，請加入：

plugins {
  id 'androidx.navigation.safeargs.kotlin'
}

plugins {
    id("androidx.navigation.safeargs.kotlin")
}

根據遷移至 AndroidX 一文，gradle.properties 檔案中必須含有 android.useAndroidX=true。

產生的程式碼

啟用 Safe Args 之後，產生的程式碼會包含您定義的各項操作類別和方法，以及對應至各個傳送和接收目的地的類別。

Safe Args 會為每個動作產生的目的地產生類別。產生的類別名稱會在原始目的地的類別名稱中加入「Directions」（路線）。舉例來說，如果原始目的地的名稱為 SpecifyAmountFragment，則產生的類別名稱為 SpecifyAmountFragmentDirections。

產生的類別會為原始目的地中定義的每種動作提供靜態方法。此方法會將任何已定義的操作參數做為引數並傳回 NavDirections 物件，您可以直接將其傳遞至 navigate()。

Safe Args 範例

舉例來說，假設有一個導覽圖包含可連接兩個目的地 (SpecifyAmountFragment 和 ConfirmationFragment) 的單一操作，其中 ConfirmationFragment 採用您在操作中提供的單一 float 參數。

Safe Args 會產生具有單一方法 actionSpecifyAmountFragmentToConfirmationFragment() 的 SpecifyAmountFragmentDirections 類別，以及名為 ActionSpecifyAmountFragmentToConfirmationFragment 的內部類別。該內部類別來自於 NavDirections，其中儲存了相關的操作 ID 及 float 參數。接著，系統會將傳回的 NavDirections 物件直接傳遞至 navigate()，如以下範例所示：

override fun onClick(v: View) {
    val amount: Float = ...
    val action =
        SpecifyAmountFragmentDirections
            .actionSpecifyAmountFragmentToConfirmationFragment(amount)
    v.findNavController().navigate(action)
}

@Override
public void onClick(View view) {
    float amount = ...;
    action =
        SpecifyAmountFragmentDirections
            .actionSpecifyAmountFragmentToConfirmationFragment(amount);
    Navigation.findNavController(view).navigate(action);
}

如要進一步瞭解如何透過 Safe Args 在目的地之間傳遞資料，請參閱「使用 Safe Args 傳遞類型安全的資料」。

使用 Safe Args 確保類型安全

使用 Safe Args Gradle 外掛程式在目的地之間瀏覽。此外掛程式會產生簡單的物件和建構工具類別，可以啟用類型安全瀏覽功能及在不同到達網頁之間傳遞引數。

如要在專案中新增 Safe Args，請在頂層 build.gradle 檔案中納入下列 classpath：

buildscript {
    repositories {
        google()
    }
    dependencies {
        def nav_version = "2.7.7"
        classpath "androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version"
    }
}

buildscript {
    repositories {
        google()
    }
    dependencies {
        val nav_version = "2.7.7"
        classpath("androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version")
    }
}

您也必須從兩個可用的外掛程式之中選擇一項套用。

如要產生適合 Java 或混用 Java 及 Kotlin 模組的 Java 語言程式碼，請將以下這一行新增至應用程式或模組的 build.gradle 檔案：

plugins {
  id 'androidx.navigation.safeargs'
}

plugins {
    id("androidx.navigation.safeargs")
}

或者，如要產生適合 Kotlin 模組的 Kotlin 程式碼，請加入：

plugins {
  id 'androidx.navigation.safeargs.kotlin'
}

plugins {
    id("androidx.navigation.safeargs.kotlin")
}

根據遷移至 AndroidX 一文，gradle.properties 檔案中必須含有 android.useAndroidX=true。

啟用安全機制之後，外掛程式會產生程式碼，其中包含您定義的每個操作的類別和方法。對於每個動作，Safe Args 也會為每個「原始目的地」(也就是該動作的來源目的地) 產生類別。產生的類別名稱是由原始目的地類別名稱和「Directions」一詞組合而成。舉例來說，如果到達網頁名稱為 SpecifyAmountFragment，產生的類別就會命名為 SpecifyAmountFragmentDirections。產生的類別會為原始目的地中定義的每種動作提供靜態方法。這個方法會將任何已定義的操作參數視為引數，並傳回可傳遞至 navigate() 的 NavDirections 物件。

舉例來說，假設有一個導覽圖，其中包含單一動作，可將原始目的地 (SpecifyAmountFragment) 連接至接收目的地 (ConfirmationFragment)。

Safe Args 會產生具有單一方法 actionSpecifyAmountFragmentToConfirmationFragment() 的 SpecifyAmountFragmentDirections 類別，該方法會傳回 NavDirections 物件。接著，系統可將傳回的 NavDirections 物件直接傳遞至 navigate()，如以下範例所示：

override fun onClick(view: View) {
    val action =
        SpecifyAmountFragmentDirections
            .actionSpecifyAmountFragmentToConfirmationFragment()
    view.findNavController().navigate(action)
}

@Override
public void onClick(View view) {
    NavDirections action =
        SpecifyAmountFragmentDirections
            .actionSpecifyAmountFragmentToConfirmationFragment();
    Navigation.findNavController(view).navigate(action);
}

如要進一步瞭解如何透過 Safe Args 在目的地之間傳送資料，請參閱「在目的地之間傳遞資料」一文中的「使用 Safe Args 傳送類型安全的資料」。