تصميم الرسم البياني للتنقل

يستخدم مكوِّن التنقّل رسمًا بيانيًا للتنقُّل لإدارة التنقّل في تطبيقك. الرسم البياني للتنقل هو بنية بيانات تحتوي على كل وجهة داخل تطبيقك والروابط بينها.

أنواع الوجهات

هناك ثلاثة أنواع عامة من الوجهات: المستضافة ومربع الحوار والنشاط. يوضح الجدول التالي أنواع الوجهات الثلاثة هذه وأغراضها.

Type

الوصف

حالات الاستخدام

مستضافة

يملأ مضيف التنقّل بالكامل. وهذا يعني أنّ حجم الوجهة المستضافة يتطابق مع حجم مضيف التنقّل، ولا تكون الوجهات السابقة مرئية.

الشاشات الرئيسية والتفاصيل

مربّع حوار

يعرض مكونات واجهة المستخدم المركّبة. واجهة المستخدم هذه غير مرتبطة بموقع مضيف التنقّل أو بحجمه. تظهر الوجهات السابقة أسفل الوجهة.

التنبيهات والاختيارات والنماذج.

النشاط

يمثل شاشات أو ميزات فريدة داخل التطبيق.

تعمل كنقطة خروج إلى الرسم البياني للتنقل الذي يبدأ نشاط Android جديدًا تتم إدارته بشكل منفصل عن مكوِّن التنقل.

في تطوير Android الحديث، يتكوّن التطبيق من نشاط واحد. وبالتالي، من الأفضل استخدام وجهات الأنشطة عند التفاعل مع أنشطة الجهات الخارجية أو كجزء من عملية نقل البيانات.

يحتوي هذا المستند على أمثلة للوجهات المستضافة، وهي الوجهات الأكثر شيوعًا والأكثر أهمية. راجِع الأدلة التالية للحصول على معلومات عن الوجهات الأخرى:

أُطر العمل

على الرغم من أنّ سير العمل العام نفسه ينطبق في كل حالة، يعتمد إنشاء مضيف التنقّل والرسم البياني على إطار عمل واجهة المستخدم الذي تستخدمه.

  • إنشاء: استخدِم مادة عرض NavHost القابلة للإنشاء. أنشِئ NavGraph لها باستخدام Kotlin DSL. يمكنك إنشاء الرسم البياني بطريقتَين:
    • كجزء من NavHost: يمكنك إنشاء الرسم البياني للتنقّل مباشرةً كجزء من إضافة NavHost.
    • برمجيًا: استخدِم طريقة NavController.createGraph() لإنشاء NavGraph وتمريرها إلى NavHost مباشرةً.
  • الأجزاء: عند استخدام الأجزاء مع إطار عمل طرق العرض لواجهة المستخدم، استخدِم NavHostFragment كمضيف. هناك عدة طرق لإنشاء رسم بياني للتنقّل:
    • برمجيًا: استخدِم Kotlin DSL لإنشاء NavGraph وتطبيقه مباشرةً على NavHostFragment.
      • إنّ الدالة createGraph() المستخدمة مع الترميز الرقمي للغة Kotlin لكل من الأجزاء وأداة Compose هي نفسها.
    • XML: اكتب مضيف التنقّل والرسم البياني مباشرةً بتنسيق XML.
    • محرر "استوديو Android": استخدِم أداة تعديل واجهة المستخدم التصويرية في "استوديو Android" لإنشاء الرسم البياني وضبطه كملف موارد XML.

إنشاء

في ميزة "إنشاء"، استخدم NavHost القابل للإنشاء لإنشاء الرسم البياني للتنقل. فكّر في المثال التالي:

val navController = rememberNavController()

NavHost(navController = navController, startDestination = "profile") {
    composable("profile") { Profile( /* ... */ ) }
    composable("friendslist") { FriendsList( /* ... */ ) }
    // Add more destinations similarly.
}
  1. تؤدي استدعاء العنصر NavHost إلى تمرير NavController وسلسلة route الخاصة بوجهة البداية.
  2. تم تمرير دالة lambda إلى NavHost لاستدعاء NavController.creatGraph() في النهاية وعرض رمز NavGraph.
  3. المكالمات إلى NavGraphBuilder.composable() تضيف وجهات إلى NavGraph الناتجة.
  4. في هذه الحالة، الوجهات هي العنصران Profile وFriendsList. تصبح سلسلتا المسار "profile" و"friendslist" المفتاحين اللذان يحددان الوجهتين.

لفهم دالة lambda التي تنشئ NavGraph بشكلٍ أفضل، يمكنك إنشاء الرسم البياني نفسه كما في المقتطف السابق، ويمكنك إنشاء NavGraph بشكل منفصل باستخدام NavController.createGraph() وتمريرها إلى NavHost مباشرةً:

val navGraph by remember(navController) {
  navController.createGraph(startDestination = "profile") {
    composable("profile") { Profile() }
    composable("friendslist") { FriendsList() }
  }
}
NavHost(navController, navGraph)

مثال مبسَّط

مثال مبسّط ولكن كامل على عملي NavController وNavHost معًا:

// Define the Profile composable.
@Composable
fun Profile(onNavigateToFriendsList: () -> Unit) {
  Text("Profile")
  Button(onClick = { onNavigateToFriendsList() }) {
    Text("Go to Friends List")
  }
}

// Define the FriendsList composable.
@Composable
fun FriendsList(onNavigateToProfile: () -> Unit) {
  Text("Friends List")
  Button(onClick = { onNavigateToProfile() }) {
    Text("Go to Profile")
  }
}

// Define the MyApp composable, including the `NavController` and `NavHost`.
@Composable
fun MyApp() {
  val navController = rememberNavController()
  NavHost(navController, startDestination = "profile") {
    composable("profile") { Profile(onNavigateToFriendsList = { navController.navigate("friendslist") }) }
    composable("friendslist") { FriendsList(onNavigateToProfile = { navController.navigate("profile") }) }
  }
}

كما يوضِّح المقتطف، بدلاً من تمرير NavController إلى المواد المواد الإبداعية، يمكنك عرض حدث لـ NavHost. وهذا يعني أنّه يجب أن تحتوي المواد المركّبة على معلَمة من النوع () -> Unit تمرّر لها NavHost دالة lambda التي تستدعي NavController.navigate().

أجزاء

كما هو موضّح في الأقسام السابقة، عند استخدام الأجزاء، يتوفّر لك خيار إنشاء رسم بياني للتنقّل بطريقة آلية باستخدام أداة Kotlin DSL أو XML أو محرِّر "استوديو Android".

توضح الأقسام التالية بالتفصيل هذه الأساليب المختلفة.

آليًا

توفّر خدمة Kotlin DSL طريقة آلية لإنشاء رسم بياني للتنقّل باستخدام الأجزاء. وهو من نواحٍ كثيرة أكثر إتقانًا وحداثة من استخدام ملف مورد XML.

ضع في الاعتبار المثال التالي، الذي ينفذ رسمًا بيانيًا للتنقل على شاشتين.

أولاً، من الضروري إنشاء NavHostFragment، التي يجب ألا تتضمّن عنصر app:navGraph:

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <androidx.fragment.app.FragmentContainerView
        android:id="@+id/nav_host_fragment"
        android:name="androidx.navigation.fragment.NavHostFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
</FrameLayout>

بعد ذلك، مرِّر id من NavHostFragment إلى NavController.findNavController(). يؤدي ذلك إلى ربط NavController بوحدة NavHostFragment.

وبعد ذلك، تربط المكالمة إلى NavController.createGraph() الرسم البياني بـ NavController وبالتالي أيضًا بـ NavHostFragment:

// Retrieve the NavController.
val navController = findNavController(R.id.nav_host_fragment)

// Add the graph to the NavController with `createGraph()`.
navController.graph = navController.createGraph(
    startDestination = "profile"
) {
    // Associate each destination with one of the route constants.
    fragment<ProfileFragment>("profile") {
        label = "Profile"
    }

    fragment<FriendsListFragment>("friendsList") {
        label = "Friends List"
    }

    // Add other fragment destinations similarly.
}

ويشبه استخدام DSL بهذه الطريقة إلى حد كبير سير العمل الموضح في القسم السابق حول إنشاء. على سبيل المثال، تنشئ الدالة NavController.createGraph() هنا وهنا تنشئ NavGraph. وبالمثل، يضيف "NavGraphBuilder.composable()" وجهات قابلة للتعديل إلى الرسم البياني، ولكن NavGraphBuilder.fragment() يضيف وجهة مجزأة هنا.

لمعرفة المزيد من المعلومات عن كيفية استخدام Kotlin DSL، يُرجى الاطّلاع على إنشاء رسم بياني باستخدام NavGraphBuilder DSL.

XML

يمكنك كتابة ملف XML بنفسك مباشرةً. يتطابق المثال التالي مع مثال شاشتين من القسم السابق.

أولاً، يجب إنشاء NavHostFragment. يعمل هذا كمضيف التنقل الذي يحتوي على الرسم البياني الفعلي للتنقل.

الحد الأدنى من تنفيذ NavHostFragment:

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <androidx.fragment.app.FragmentContainerView
        android:id="@+id/nav_host_fragment"
        android:name="androidx.navigation.fragment.NavHostFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:navGraph="@navigation/nav_graph" />

</FrameLayout>

يتضمّن NavHostFragment السمة app:navGraph. استخدم هذه السمة لتوصيل الرسم البياني للتنقل بمضيف التنقل. وفي ما يلي مثال على كيفية تنفيذ الرسم البياني:

<navigation xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/nav_graph"
    app:startDestination="@id/profile">

    <fragment
        android:id="@+id/profile"
        android:name="com.example.ProfileFragment"
        android:label="Profile">

        <!-- Action to navigate from Profile to Friends List. -->
        <action
            android:id="@+id/action_profile_to_friendslist"
            app:destination="@id/friendslist" />
    </fragment>

    <fragment
        android:id="@+id/friendslist"
        android:name="com.example.FriendsListFragment"
        android:label="Friends List" />

    <!-- Add other fragment destinations similarly. -->
</navigation>

يمكنك استخدام الإجراءات لتحديد الاتصالات بين الوجهات المختلفة. في هذا المثال، يحتوي الجزء profile على إجراء يؤدي إلى الانتقال إلى friendslist. لمزيد من المعلومات، راجع استخدام إجراءات التنقل والأجزاء.

محرِّر

يمكنك إدارة الرسم البياني للتنقُّل في تطبيقك باستخدام "محرِّر التنقل" في "استوديو Android". هذه في الأساس واجهة مستخدم تصويرية يمكنك استخدامها لإنشاء وتعديل XML على NavigationFragment، كما هو موضّح في القسم السابق.

لمزيد من المعلومات، اطّلع على محرر التنقل.

الرسوم البيانية المتداخلة

يمكنك أيضًا استخدام الرسوم البيانية المتداخلة. وهذا ينطوي على استخدام الرسم البياني كوجهة تنقل. لمزيد من المعلومات، يمكنك الاطّلاع على الرسوم البيانية المتداخلة.

قراءات إضافية

لمعرفة المزيد من مفاهيم التنقّل الأساسية، يُرجى الاطّلاع على الأدلة التالية: