یک قطعه ایجاد کنید

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

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

محیط خود را تنظیم کنید

قطعات نیاز به وابستگی به کتابخانه قطعه 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.8.4"

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

کاتلین

dependencies {
    val fragment_version = "1.8.4"

    // 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 تعبیه شود تا بخشی از UI به طرح‌بندی آن فعالیت کمک کند. 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 برای نمونه سازی را مشخص می کند. وقتی طرح اکتیویتی بالا می‌رود، قطعه مشخص‌شده نمونه‌سازی می‌شود، onInflate() روی قطعه نمونه‌سازی‌شده جدید فراخوانی می‌شود، و یک FragmentTransaction برای افزودن قطعه به 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();
        }
    }
}

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

در مثال قبلی، توجه داشته باشید که تراکنش قطعه تنها زمانی ایجاد می شود که 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 getter برای بازیابی هر آرگومان استفاده کرد.

کاتلین

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 پوشش داده شده‌اند.