ส่งข้อมูลระหว่างจุดหมาย

การนำทางช่วยให้คุณแนบข้อมูลกับการดำเนินการนำทางได้โดยการกำหนดอาร์กิวเมนต์สำหรับปลายทาง เช่น ปลายทางโปรไฟล์ผู้ใช้อาจใช้อาร์กิวเมนต์รหัสผู้ใช้เพื่อกำหนดผู้ใช้ที่จะแสดง

โดยทั่วไป คุณควรเลือกส่งเฉพาะข้อมูลจำนวนน้อยที่สุดระหว่างปลายทาง เช่น คุณควรส่งคีย์เพื่อดึงออบเจ็กต์แทนที่จะส่งออบเจ็กต์เอง เนื่องจากพื้นที่ทั้งหมดสำหรับสถานะที่บันทึกไว้ทั้งหมดมีจำกัดใน Android หากต้องการส่งข้อมูลจำนวนมาก ให้ใช้ ViewModel ตามที่อธิบายไว้ในภาพรวมของ ViewModel

กำหนดอาร์กิวเมนต์ปลายทาง

หากต้องการส่งข้อมูลระหว่างปลายทาง ให้กำหนดอาร์กิวเมนต์ก่อนโดยเพิ่มอาร์กิวเมนต์ลงในปลายทางที่รับข้อมูล โดยทำตามขั้นตอนต่อไปนี้

  1. ในเครื่องมือแก้ไขการนําทาง ให้คลิกปลายทางที่รับอาร์กิวเมนต์
  2. ในแผงแอตทริบิวต์ ให้คลิกเพิ่ม (+)
  3. ในหน้าต่างเพิ่มลิงก์อาร์กิวเมนต์ที่ปรากฏขึ้น ให้ป้อนชื่ออาร์กิวเมนต์ ประเภทอาร์กิวเมนต์ ระบุว่าอาร์กิวเมนต์เป็นค่า Null ได้หรือไม่ และค่าเริ่มต้น (หากจำเป็น)
  4. คลิกเพิ่ม โปรดสังเกตว่าอาร์กิวเมนต์จะปรากฏในรายการอาร์กิวเมนต์ในแผงแอตทริบิวต์
  5. จากนั้นคลิกการดำเนินการที่เกี่ยวข้องซึ่งจะนำคุณไปยังปลายทางนี้ ในแผงแอตทริบิวต์ คุณควรเห็นอาร์กิวเมนต์ที่เพิ่มใหม่ในส่วนค่าเริ่มต้นของอาร์กิวเมนต์
  6. นอกจากนี้ คุณยังเห็นว่ามีการเพิ่มอาร์กิวเมนต์ใน XML ด้วย คลิกแท็บข้อความเพื่อสลับไปยังมุมมอง XML และสังเกตว่ามีการเพิ่มอาร์กิวเมนต์ลงในปลายทางที่รับอาร์กิวเมนต์ ตัวอย่างมีดังนี้

     <fragment android:id="@+id/myFragment" >
         <argument
             android:name="myArg"
             app:argType="integer"
             android:defaultValue="0" />
     </fragment>
    

ประเภทอาร์กิวเมนต์ที่รองรับ

ไลบรารีการนำทางรองรับอาร์กิวเมนต์ประเภทต่อไปนี้

ประเภท ไวยากรณ์ app:argType การรองรับค่าเริ่มต้น จัดการโดยเส้นทาง เว้นว่างได้
จำนวนเต็ม app:argType="integer" ใช่ ได้ ไม่
ทุ่น app:argType="float" ใช่ ได้ ไม่
ยาว app:argType="long" ใช่ - ค่าเริ่มต้นต้องลงท้ายด้วยคำต่อท้าย "L" เสมอ (เช่น "123L") ใช่ ไม่
บูลีน app:argType="boolean" ใช่ - "true" หรือ "false" ใช่ ไม่
สตริง app:argType="string" ใช่ ได้ ใช่
การอ้างอิงทรัพยากร app:argType="reference" ใช่ - ค่าเริ่มต้นต้องอยู่ในรูปแบบ "@resourceType/resourceName" (เช่น "@style/myCustomStyle") หรือ "0" ใช่ ไม่
Parcelable ที่กำหนดเอง app:argType="<type>" โดยที่ <type> คือชื่อคลาสที่สมบูรณ์ในตัวเองของ Parcelable รองรับค่าเริ่มต้นเป็น "@null" ไม่รองรับค่าเริ่มต้นอื่นๆ ไม่ ใช่
Custom Serializable app:argType="<type>" โดยที่ <type> คือชื่อคลาสที่สมบูรณ์ในตัวเองของ Serializable รองรับค่าเริ่มต้นเป็น "@null" ไม่รองรับค่าเริ่มต้นอื่นๆ ไม่ ใช่
Enum ที่กำหนดเอง app:argType="<type>" โดยที่ <type> คือชื่อที่สมบูรณ์ในตัวเองของ enum ใช่ - ค่าเริ่มต้นต้องตรงกับชื่อที่ไม่มีคุณสมบัติ (เช่น "SUCCESS" เพื่อให้ตรงกับ MyEnum.SUCCESS) ไม่ ไม่

หากประเภทอาร์กิวเมนต์รองรับค่า Null คุณสามารถประกาศค่าเริ่มต้นของ Null ได้โดยใช้ android:defaultValue="@null"

เส้นทาง, Deep Link และ URI พร้อมอาร์กิวเมนต์สามารถแยกวิเคราะห์จากสตริงได้ ซึ่งไม่สามารถทำได้โดยใช้ประเภทข้อมูลที่กำหนดเอง เช่น Parcelable และ Serializable ดังที่เห็นในตารางก่อนหน้า หากต้องการส่งข้อมูลที่ซับซ้อนที่กำหนดเอง ให้จัดเก็บข้อมูลไว้ที่อื่น เช่น ViewModel หรือฐานข้อมูล และส่งเฉพาะตัวระบุขณะไปยังส่วนต่างๆ จากนั้นดึงข้อมูลในตำแหน่งใหม่หลังจากที่การไปยังส่วนต่างๆ สิ้นสุดลง

เมื่อเลือกประเภทที่กำหนดเองประเภทใดประเภทหนึ่ง กล่องโต้ตอบเลือกคลาสจะปรากฏขึ้นและแจ้งให้คุณเลือกคลาสที่สอดคล้องกันสำหรับประเภทนั้น แท็บโปรเจ็กต์ช่วยให้คุณเลือกคลาสจากโปรเจ็กต์ปัจจุบันได้

คุณสามารถเลือก <inferred type> เพื่อให้ไลบรารีการนำทางกำหนดประเภทตามค่าที่ระบุได้

คุณสามารถเลือกอาร์เรย์เพื่อระบุว่าอาร์กิวเมนต์ควรเป็นอาร์เรย์ของค่าประเภทที่เลือก ข้อควรทราบ

  • ระบบไม่รองรับอาร์เรย์ของ Enum และอาร์เรย์ของการอ้างอิงทรัพยากร
  • อาร์เรย์รองรับค่าที่เว้นว่างได้ ไม่ว่าประเภทที่เกี่ยวข้องจะรองรับค่าที่เว้นว่างได้หรือไม่ก็ตาม เช่น การใช้ app:argType="integer[]" ช่วยให้คุณใช้ app:nullable="true" เพื่อระบุว่าการส่งอาร์เรย์ Null เป็นสิ่งที่ยอมรับได้
  • อาร์เรย์รองรับค่าเริ่มต้นเดียวคือ "@null" อาร์เรย์ไม่รองรับค่าเริ่มต้นอื่นๆ

ลบล้างอาร์กิวเมนต์ปลายทางในการดำเนินการ

อาร์กิวเมนต์ระดับปลายทางและค่าเริ่มต้นจะใช้โดยการดำเนินการทั้งหมดที่ไปยังปลายทาง หากจำเป็น คุณสามารถลบล้างค่าเริ่มต้นของอาร์กิวเมนต์ (หรือตั้งค่าหากยังไม่มี) ได้โดยกำหนดอาร์กิวเมนต์ที่ระดับการดำเนินการ อาร์กิวเมนต์นี้ต้องมีชื่อและประเภทเดียวกับอาร์กิวเมนต์ที่ประกาศในปลายทาง

XML ต่อไปนี้ประกาศการดำเนินการที่มีอาร์กิวเมนต์ซึ่งลบล้างอาร์กิวเมนต์ระดับปลายทางจากตัวอย่างก่อนหน้า

<action android:id="@+id/startMyFragment"
    app:destination="@+id/myFragment">
    <argument
        android:name="myArg"
        app:argType="integer"
        android:defaultValue="1" />
</action>

ใช้ Safe Args เพื่อส่งข้อมูลด้วยความปลอดภัยในการกำหนดประเภท

คอมโพเนนต์การนําทางมีปลั๊กอิน Gradle ที่เรียกว่า Safe Args ซึ่งจะสร้างออบเจ็กต์และคลาส Builder แบบง่ายสําหรับการนําทางที่ปลอดภัยต่อประเภทและการเข้าถึงอาร์กิวเมนต์ที่เกี่ยวข้อง เราขอแนะนำให้ใช้ Safe Args สำหรับการไปยังส่วนต่างๆ และการส่งข้อมูล เนื่องจากช่วยให้มั่นใจได้ถึงความปลอดภัยในการกำหนดประเภท

หากไม่ได้ใช้ Gradle คุณจะใช้ปลั๊กอิน Safe Args ไม่ได้ ในกรณีเหล่านี้ คุณสามารถใช้ Bundle เพื่อส่งข้อมูลโดยตรงได้

หากต้องการเพิ่ม Safe Args ลงในโปรเจ็กต์ ให้ใส่ classpath ต่อไปนี้ในไฟล์ build.gradle ระดับบนสุด

Groovy

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

Kotlin

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

นอกจากนี้ คุณยังต้องใช้ปลั๊กอินที่มีให้ 2 รายการนี้ด้วย

หากต้องการสร้างโค้ดภาษา Java ที่เหมาะสำหรับโมดูล Java หรือโมดูล Java และ Kotlin แบบผสม ให้เพิ่มบรรทัดต่อไปนี้ลงในไฟล์ build.gradle แอปหรือโมดูล

Groovy

plugins {
  id 'androidx.navigation.safeargs'
}

Kotlin

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

หรือหากต้องการสร้างโค้ด Kotlin ที่เหมาะสำหรับโมดูล Kotlin เท่านั้น ให้เพิ่ม

Groovy

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

Kotlin

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

คุณต้องมี android.useAndroidX=true ในไฟล์ gradle.properties ตามการย้ายข้อมูลไปยัง AndroidX

หลังจากเปิดใช้ Safe Args แล้ว โค้ดที่สร้างขึ้นจะมีคลาสและเมธอดที่ปลอดภัยในการกำหนดประเภทต่อไปนี้สำหรับการดำเนินการแต่ละอย่าง รวมถึงปลายทางการส่งและรับแต่ละรายการ

  • ระบบจะสร้างคลาสสำหรับปลายทางแต่ละแห่งที่การดำเนินการเริ่มต้นขึ้น ชื่อของคลาสนี้คือชื่อของจุดหมายต้นทางที่ต่อท้ายด้วยคำว่า "Directions" เช่น หากปลายทางต้นทางเป็น Fragment ที่ชื่อว่า SpecifyAmountFragment คลาสที่สร้างขึ้นจะชื่อว่า SpecifyAmountFragmentDirections

    คลาสนี้มีเมธอดสำหรับการดำเนินการแต่ละรายการที่กำหนดไว้ในปลายทางต้นทาง

  • สำหรับแต่ละการดำเนินการที่ใช้เพื่อส่งอาร์กิวเมนต์ ระบบจะสร้างคลาสภายในซึ่งมีชื่อตามการดำเนินการนั้น ตัวอย่างเช่น หากการดำเนินการชื่อ confirmationAction, คลาสจะชื่อ ConfirmationAction หากการดำเนินการมีอาร์กิวเมนต์ที่ไม่มี defaultValue คุณจะใช้คลาสการดำเนินการที่เกี่ยวข้องเพื่อตั้งค่าอาร์กิวเมนต์

  • ระบบจะสร้างคลาสสำหรับปลายทางที่รับข้อมูล ชื่อของคลาสนี้คือชื่อของปลายทางที่ต่อท้ายด้วยคำว่า "Args" เช่น หาก Fragment ปลายทางชื่อ ConfirmationFragment, คลาสที่สร้างขึ้นจะชื่อ ConfirmationFragmentArgs ใช้เมธอด fromBundle() ของคลาสนี้เพื่อดึงอาร์กิวเมนต์

ตัวอย่างต่อไปนี้แสดงวิธีใช้เมธอดเหล่านี้เพื่อตั้งค่าอาร์กิวเมนต์และส่งไปยังเมธอด navigate()

Kotlin

override fun onClick(v: View) {
   val amountTv: EditText = view!!.findViewById(R.id.editTextAmount)
   val amount = amountTv.text.toString().toInt()
   val action = SpecifyAmountFragmentDirections.confirmationAction(amount)
   v.findNavController().navigate(action)
}

Java

@Override
public void onClick(View view) {
   EditText amountTv = (EditText) getView().findViewById(R.id.editTextAmount);
   int amount = Integer.parseInt(amountTv.getText().toString());
   ConfirmationAction action =
           SpecifyAmountFragmentDirections.confirmationAction();
   action.setAmount(amount);
   Navigation.findNavController(view).navigate(action);
}

ในโค้ดสำหรับปลายทางที่รับ ให้ใช้เมธอด getArguments() เพื่อดึงข้อมูล Bundle และใช้เนื้อหาของ Bundle เมื่อใช้ทรัพยากร Dependency -ktx ผู้ใช้ Kotlin จะใช้ผู้รับมอบสิทธิ์พร็อพเพอร์ตี้ by navArgs() เพื่อเข้าถึงอาร์กิวเมนต์ได้ด้วย

Kotlin

val args: ConfirmationFragmentArgs by navArgs()

override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
    val tv: TextView = view.findViewById(R.id.textViewAmount)
    val amount = args.amount
    tv.text = amount.toString()
}

Java

@Override
public void onViewCreated(View view, @Nullable Bundle savedInstanceState) {
    TextView tv = view.findViewById(R.id.textViewAmount);
    int amount = ConfirmationFragmentArgs.fromBundle(getArguments()).getAmount();
    tv.setText(amount + "");
}

ใช้ Safe Args กับการดำเนินการทั่วโลก

เมื่อใช้ Safe Args กับการดำเนินการส่วนกลาง คุณต้องระบุค่า android:id สำหรับองค์ประกอบ <navigation> รูท ดังที่แสดงในตัวอย่างต่อไปนี้

<?xml version="1.0" encoding="utf-8"?>
<navigation xmlns:app="http://schemas.android.com/apk/res-auto"
            xmlns:tools="http://schemas.android.com/tools"
            xmlns:android="http://schemas.android.com/apk/res/android"
            android:id="@+id/main_nav"
            app:startDestination="@id/mainFragment">

    ...

</navigation>

Navigation จะสร้างคลาส Directions สำหรับองค์ประกอบ <navigation> ซึ่งอิงตามค่า android:id เช่น หากคุณมีองค์ประกอบ <navigation> ที่มี android:id=@+id/main_nav คลาสที่สร้างขึ้นจะเรียกว่า MainNavDirections ปลายทางทั้งหมดภายในองค์ประกอบ <navigation> มีเมธอดที่สร้างขึ้นสำหรับการเข้าถึงการดำเนินการส่วนกลางที่เกี่ยวข้องทั้งหมดโดยใช้เมธอดเดียวกับที่อธิบายไว้ในส่วนก่อนหน้า

ส่งข้อมูลระหว่างปลายทางด้วยออบเจ็กต์ Bundle

หากไม่ได้ใช้ Gradle คุณยังคงส่งอาร์กิวเมนต์ระหว่างปลายทางได้โดยใช้ออบเจ็กต์ Bundle สร้างออบเจ็กต์ Bundle แล้วส่งไปยังปลายทางโดยใช้ navigate() ดังตัวอย่างต่อไปนี้

Kotlin

val bundle = bundleOf("amount" to amount)
view.findNavController().navigate(R.id.confirmationAction, bundle)

Java

Bundle bundle = new Bundle();
bundle.putString("amount", amount);
Navigation.findNavController(view).navigate(R.id.confirmationAction, bundle);

ในโค้ดของปลายทางที่รับ ให้ใช้เมธอด getArguments() เพื่อดึงข้อมูล Bundle และใช้เนื้อหาของข้อมูลดังกล่าว

Kotlin

val tv = view.findViewById<TextView>(R.id.textViewAmount)
tv.text = arguments?.getString("amount")

Java

TextView tv = view.findViewById(R.id.textViewAmount);
tv.setText(getArguments().getString("amount"));

ส่งข้อมูลไปยังปลายทางเริ่มต้น

คุณสามารถส่งข้อมูลไปยังปลายทางเริ่มต้นของแอปได้ ก่อนอื่น คุณต้องสร้าง Bundle ที่เก็บข้อมูลอย่างชัดเจน จากนั้น ให้ใช้วิธีใดวิธีหนึ่งต่อไปนี้เพื่อส่ง Bundle ไปยังปลายทางเริ่มต้น

  • หากคุณสร้าง NavHost โดยใช้โปรแกรม ให้เรียกใช้ NavHostFragment.create(R.navigation.graph, args) โดยที่ args คือ Bundle ที่เก็บข้อมูลของคุณ
  • ไม่เช่นนั้น คุณสามารถตั้งค่าอาร์กิวเมนต์ปลายทางเริ่มต้นได้โดยเรียกใช้โอเวอร์โหลดของ NavController.setGraph() รายการใดรายการหนึ่งต่อไปนี้

หากต้องการดึงข้อมูลในปลายทางเริ่มต้น ให้เรียกใช้ Fragment.getArguments()

ข้อควรพิจารณาเกี่ยวกับ ProGuard

หากคุณย่อโค้ด คุณต้องป้องกันไม่ให้ชื่อคลาส Parcelable, Serializable และ Enum ถูกปรับให้ยากต่อการอ่าน (Obfuscation) ซึ่งเป็นส่วนหนึ่งของกระบวนการลดขนาด คุณสามารถทำได้ด้วยวิธีใดวิธีหนึ่งใน 2 วิธีต่อไปนี้

  • ใช้คำอธิบายประกอบ @Keep
  • ใช้กฎ keepnames

หัวข้อย่อยต่อไปนี้จะอธิบายแนวทางเหล่านี้

ใช้คำอธิบายประกอบ @Keep

ตัวอย่างต่อไปนี้จะเพิ่มคำอธิบายประกอบ @Keep ลงในคำจำกัดความของคลาสโมเดล

Kotlin

@Keep class ParcelableArg : Parcelable { ... }

@Keep class SerializableArg : Serializable { ... }

@Keep enum class EnumArg { ... }

Java

@Keep public class ParcelableArg implements Parcelable { ... }

@Keep public class SerializableArg implements Serializable { ... }

@Keep public enum EnumArg { ... }

ใช้กฎ keepnames

นอกจากนี้ คุณยังเพิ่มกฎ keepnames ลงในไฟล์ proguard-rules.pro ได้ด้วย ดังที่แสดงในตัวอย่างต่อไปนี้

proguard-rules.pro

...

-keepnames class com.path.to.your.ParcelableArg
-keepnames class com.path.to.your.SerializableArg
-keepnames class com.path.to.your.EnumArg

...

แหล่งข้อมูลเพิ่มเติม

ดูข้อมูลเพิ่มเติมเกี่ยวกับการนำทางได้ที่แหล่งข้อมูลเพิ่มเติมต่อไปนี้

Codelab

วิดีโอ