ایجاد قطعه

تکه نشان‌دهنده بخش مدولار میانای کاربر در یک فعالیت است. قطعه چرخه حیات خودش را دارد، رویدادهای ورودی خودش را دریافت می‌کند، و می‌توانید درحین اجرای فعالیت حاوی قطعه، قطعه‌ها را اضافه یا حذف کنید.

این سند نحوه ایجاد قطعه و گنجاندن آن در فعالیت را شرح می‌دهد.

راه‌اندازی محیط

قطعه‌ها به وابستگی به کتابخانه قطعه AndroidX نیاز دارند. برای افزودن این وابستگی، باید مخزن Google Maven را به فایل settings.gradle پروژه‌تان اضافه کنید.

شیک

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        ...
    }
}

کاتلین

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        ...
    }
}

برای گنجاندن کتابخانه AndroidX Fragment در پروژه‌تان، وابستگی‌های زیر را در فایل build.gradle برنامه‌تان اضافه کنید:

شیار

dependencies {
    def fragment_version = "1.9.1"

    // Java language implementation
    implementation "androidx.fragment:fragment:$fragment_version"
    // Kotlin
    implementation "androidx.fragment:fragment-ktx:$fragment_version"
}

کاتلین

dependencies {
    val fragment_version = "1.9.1"

    // Java language implementation
    implementation("androidx.fragment:fragment:$fragment_version")
    // Kotlin
    implementation("androidx.fragment:fragment-ktx:$fragment_version")
}

ایجاد کلاس قطعه

برای ایجاد قطعه، کلاس AndroidX Fragment را گسترش دهید و روش‌های آن را لغو کنید تا منطق برنامه‌تان را درج کنید، مشابه روشی که کلاس Activity را ایجاد می‌کنید. برای ایجاد یک قطعه حداقلی که چیدمان خودش را تعریف می‌کند، منبع چیدمان قطعه‌تان را به سازنده پایه ارائه دهید، همان‌طور که در مثال زیر نشان داده شده است:

کاتلین

class ExampleFragment : Fragment(R.layout.example_fragment)

جاوا

class ExampleFragment extends Fragment {
    public ExampleFragment() {
        super(R.layout.example_fragment);
    }
}

کتابخانه Fragment همچنین کلاس‌های پایه قطعه تخصصی‌تری را ارائه می‌دهد:

DialogFragment

کادر گفتگوی شناور را نمایش می‌دهد. استفاده از این کلاس برای ایجاد کادر گفتگو جایگزین خوبی برای استفاده از روش‌های کمکی کادر گفتگو در کلاس Activity است، زیرا قطعه‌ها به‌طور خودکار ایجاد و پاک‌سازی Dialog را مدیریت می‌کنند. برای جزئیات بیشتر، نمایش کادرهای گفتگو با DialogFragment را ببینید.

PreferenceFragmentCompat

سلسله‌مراتب اشیاء Preference را به‌صورت فهرست نمایش می‌دهد. می‌توانید از PreferenceFragmentCompat برای ایجاد صفحه تنظیمات برای برنامه‌تان استفاده کنید.

افزودن قطعه به فعالیت

به‌طورکلی، قطعه شما باید در AndroidX FragmentActivity جاسازی شود تا بخشی از واسط کاربر را به طرح‌بندی آن فعالیت اضافه کند. FragmentActivity کلاس پایه برای AppCompatActivity است، بنابراین اگر ازقبل برای ارائه سازگاری با نسخه قدیمی در برنامه‌تان، AppCompatActivity را زیرکلاس‌بندی می‌کنید، نیازی نیست کلاس پایه فعالیتتان را تغییر دهید.

می‌توانید قطعه‌تان را به سلسله‌مراتب نمای فعالیت اضافه کنید، یا با تعریف کردن قطعه در فایل چیدمان فعالیتتان یا با تعریف کردن محفظه قطعه در فایل چیدمان فعالیتتان و سپس افزودن قطعه به‌صورت برنامه‌نویسی‌شده از داخل فعالیتتان. در هر دو مورد، باید FragmentContainerView اضافه کنید که مکانی را که قطعه باید در آن قرار گیرد در سلسله‌مراتب نمای فعالیت تعریف کند. اکیداً توصیه می‌شود که همیشه از FragmentContainerView به‌عنوان نگهدارنده برای قطعه‌ها استفاده کنید، زیرا FragmentContainerView شامل اصلاحات خاصی برای قطعه‌ها است که سایر گروه‌های نما مانند FrameLayout ارائه نمی‌دهند.

افزودن قطعه ازطریق XML

برای افزودن اعلانی یک قطعه به XML چیدمان فعالیتتان، از عنصر FragmentContainerView استفاده کنید.

در اینجا نمونه‌ای از چیدمان فعالیت حاوی یک FragmentContainerView آورده شده است:

<!-- res/layout/example_activity.xml -->
<androidx.fragment.app.FragmentContainerView
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/fragment_container_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:name="com.example.ExampleFragment" />

مشخصه android:name نام کلاس Fragment را برای نمونه‌سازی مشخص می‌کند. When the activity's layout is inflated, the specified fragment is instantiated, onInflate() is called on the newly instantiated fragment, and a FragmentTransaction is created to add the fragment to the FragmentManager.

توجه: می‌توانید از مشخصه class به‌جای android:name به‌عنوان روشی جایگزین برای مشخص کردن اینکه کدام Fragment نمونه‌سازی شود استفاده کنید.

افزودن قطعه به‌صورت برنامه‌نویسی‌شده

برای افزودن برنامه‌نویسی‌شده قطعه به چیدمان فعالیت، چیدمان باید شامل FragmentContainerView باشد تا به‌عنوان ظرف قطعه عمل کند، همان‌طور که در مثال زیر نشان داده شده است:

<!-- res/layout/example_activity.xml -->
<androidx.fragment.app.FragmentContainerView
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/fragment_container_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

برخلاف رویکرد XML، در اینجا از مشخصه android:name در FragmentContainerView استفاده نمی‌شود، بنابراین هیچ قطعه خاصی به‌طور خودکار نمونه‌سازی نمی‌شود. به‌جای آن، از FragmentTransaction برای نمونه‌سازی قطعه و افزودن آن به چیدمان فعالیت استفاده می‌شود.

وقتی فعالیتتان درحال اجرا است، می‌توانید تراکنش‌های قطعه‌ای مثل افزودن، برداشتن، یا جایگزین کردن قطعه را انجام دهید. در FragmentActivity، می‌توانید نمونه‌ای از FragmentManager را دریافت کنید، که می‌توان از آن برای ایجاد FragmentTransaction استفاده کرد. سپس می‌توانید قطعه‌تان را در روش onCreate() فعالیتتان بااستفاده از FragmentTransaction.add() نمونه‌سازی کنید، شناسه ViewGroup محفظه را در طرح‌بندی‌تان و کلاس قطعه‌ای را که می‌خواهید اضافه کنید ارسال کنید، و سپس تراکنش را همان‌طور که در مثال زیر نشان داده شده است ثبت کنید:

کاتلین

class ExampleActivity : AppCompatActivity(R.layout.example_activity) {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (savedInstanceState == null) {
            supportFragmentManager.commit {
                setReorderingAllowed(true)
                add<ExampleFragment>(R.id.fragment_container_view)
            }
        }
    }
}

جاوا

public class ExampleActivity extends AppCompatActivity {
    public ExampleActivity() {
        super(R.layout.example_activity);
    }
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        if (savedInstanceState == null) {
            getSupportFragmentManager().beginTransaction()
                .setReorderingAllowed(true)
                .add(R.id.fragment_container_view, ExampleFragment.class, null)
                .commit();
        }
    }
}

توجه: همیشه باید از setReorderingAllowed(true) هنگام انجام FragmentTransaction استفاده کنید. برای اطلاعات بیشتر درباره تراکنش‌های مرتب‌شده، تراکنش‌های قطعه را ببینید.

در مثال قبلی، توجه داشته باشید که تراکنش قطعه فقط زمانی ایجاد می‌شود که savedInstanceState برابر با null باشد. این کار برای اطمینان از این است که قطعه فقط یک‌بار، هنگام ایجاد اولیه فعالیت، اضافه شود. وقتی تغییر پیکربندی رخ می‌دهد و فعالیت دوباره ایجاد می‌شود، savedInstanceState دیگر null نیست و نیازی نیست تکه برای بار دوم اضافه شود، زیرا تکه به‌طور خودکار از savedInstanceState بازیابی می‌شود.

اگر قطعه شما به برخی داده‌های اولیه نیاز دارد، می‌توان با ارائه Bundle در فراخوانی FragmentTransaction.add()، آرگومان‌ها را به قطعه شما ارسال کرد، همان‌طور که در زیر نشان داده شده است:

کاتلین

class ExampleActivity : AppCompatActivity(R.layout.example_activity) {
      override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (savedInstanceState == null) {
            val bundle = bundleOf("some_int" to 0)
            supportFragmentManager.commit {
                setReorderingAllowed(true)
                add<ExampleFragment>(R.id.fragment_container_view, args = bundle)
            }
        }
    }
}

جاوا

public class ExampleActivity extends AppCompatActivity {
    public ExampleActivity() {
        super(R.layout.example_activity);
    }
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        if (savedInstanceState == null) {
            Bundle bundle = new Bundle();
            bundle.putInt("some_int", 0);

            getSupportFragmentManager().beginTransaction()
                .setReorderingAllowed(true)
                .add(R.id.fragment_container_view, ExampleFragment.class, bundle)
                .commit();
        }
    }
}

سپس می‌توان آرگومان‌های Bundle را با فراخوانی requireArguments() از داخل قطعه بازیابی کرد و از روش‌های مناسب دریافت‌کننده Bundle برای بازیابی هر آرگومان استفاده کرد.

کاتلین

class ExampleFragment : Fragment(R.layout.example_fragment) {
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        val someInt = requireArguments().getInt("some_int")
        ...
    }
}

جاوا

class ExampleFragment extends Fragment {
    public ExampleFragment() {
        super(R.layout.example_fragment);
    }

    @Override
    public void onViewCreated(@NonNull View view, Bundle savedInstanceState) {
        int someInt = requireArguments().getInt("some_int");
        ...
    }
}

همچنین مراجعه کنید به

تراکنش‌های Fragment و FragmentManager با جزئیات بیشتر در راهنمای مدیر Fragment پوشش داده شده‌اند.