راه‌اندازی لبه به لبه

نمایشگر لبه به لبه به برنامه شما اجازه می‌دهد تا رابط کاربری خود را پشت نوارهای سیستم - نوار وضعیت، نوار عنوان و نوار ناوبری - ترسیم کند تا به یک تجربه کاربری فراگیرتر دست یابد. اگر دستگاه‌هایی را هدف قرار می‌دهید که اندروید ۱۵ (سطح API 35) یا بالاتر را اجرا می‌کنند، لبه به لبه به طور پیش‌فرض اعمال می‌شود .

برای نمایش صحیح محتوا به صورت لبه به لبه در تمام نسخه‌های اندروید، این مراحل راه‌اندازی را دنبال کنید. بدون این مراحل، برنامه شما ممکن است رنگ‌های یکدست را پشت نوارهای سیستم ترسیم کند یا محتوای خود را همزمان با انتقال‌های صفحه‌کلید روی صفحه (IME) متحرک نکند.

۱. نمایشگر لبه به لبه را فعال کنید

برای فعال کردن لبه به لبه در نسخه‌های قبلی اندروید، enableEdgeToEdge() را در متد Activity.onCreate() خود فراخوانی کنید:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    enableEdgeToEdge()
    ...
}

به طور پیش‌فرض، enableEdgeToEdge() نوارهای سیستم را شفاف می‌کند، به جز در حالت ناوبری ۳ دکمه‌ای، که در آن یک نوار شفاف برای کنتراست بهتر به نوار ناوبری اعمال می‌شود. رنگ آیکون‌های سیستم و نوار با تم روشن یا تاریک سیستم سازگار می‌شود.

۲. پیکربندی windowSoftInputMode

در ورودی AndroidManifest.xml مربوط به Activity، android:windowSoftInputMode="adjustResize" را تنظیم کنید. این تنظیم به برنامه شما اجازه می‌دهد تا IME insets را دریافت کند و شما را قادر می‌سازد تا طرح‌بندی خود را با padding هنگام ظاهر شدن یا ناپدید شدن صفحه کلید روی صفحه تنظیم کنید.

<!-- In your AndroidManifest.xml file: -->
<activity
  android:name=".ui.MainActivity"
  android:label="@string/app_name"
  android:windowSoftInputMode="adjustResize"
  android:theme="@style/Theme.MyApplication"
  android:exported="true">
  ...
</activity>

۳. همپوشانی‌ها را با استفاده از خطوط درج (insets) مدیریت کنید

پس از فعال شدن قابلیت نمایش لبه به لبه، ممکن است برخی از محتوای برنامه و عناصر رابط کاربری شما پشت میله‌های سیستم نمایش داده شوند. برای جلوگیری از پنهان شدن عناصر حیاتی یا تعاملی توسط میله‌های سیستم یا همپوشانی با حرکات سیستم، باید از درج (inset) جلوگیری کنید.

Insetها بخش‌هایی از صفحه نمایش را توصیف می‌کنند که با رابط کاربری سیستم یا حرکات سیستم تلاقی دارند. انواع اصلی insetهایی که برای نمایش لبه به لبه باید در نظر گرفته شوند عبارتند از:

• درج نوارهای سیستم: نواحی نمایش نوارهای سیستم را نشان می‌دهد. از این موارد برای جلوگیری از مبهم شدن رابط کاربری توسط نوارهای سیستم استفاده کنید.
• برش‌های داخلی نمایشگر: نشان‌دهنده‌ی قسمت‌هایی از صفحه نمایش دستگاه هستند که در آن‌ها بریدگی فیزیکی (مانند ناچ دوربین) وجود دارد.

در نوشتن، می‌توانید با استفاده از خط‌کش، اصلاح‌کننده‌های فاصله‌گذاری یا اصلاح‌کننده‌های اندازه‌ی درج، درون‌صفحه‌ای‌ها را مدیریت کنید. برای راهنمایی دقیق‌تر به «درباره‌ی درون‌صفحه‌ای‌های پنجره» مراجعه کنید.

مباحث پیشرفته

برای موارد استفاده پیشرفته‌ترِ لبه به لبه، موارد زیر را در نظر بگیرید.

حالت فراگیر

برخی از محتواها، مانند ویدیوها یا نقشه‌ها، از یک تجربه کاملاً فراگیر که در آن نوارهای سیستم پنهان هستند، بهره‌مند می‌شوند. می‌توانید نوارهای سیستم را با استفاده از WindowInsetsControllerCompat پنهان کنید:

val windowInsetsController =
    WindowCompat.getInsetsController(window, window.decorView)

// Hide the system bars.
windowInsetsController.hide(WindowInsetsCompat.Type.systemBars())

// Show the system bars.
windowInsetsController.show(WindowInsetsCompat.Type.systemBars()) For example, use either `Scaffold`,

رنگ‌ها و آیکون‌های نوار سیستم

هنگام استفاده از لبه به لبه، ممکن است پس‌زمینه برنامه شما از پشت نوارهای سیستم قابل مشاهده باشد، بنابراین ممکن است لازم باشد رنگ آیکون‌های نوار سیستم را برای کنتراست بهتر تنظیم کنید.

برای تغییر آیکون‌های نوار وضعیت به روشن یا تیره، از WindowInsetsControllerCompat استفاده کنید:

// Set status bar icons to dark
WindowCompat.getInsetsController(window, window.decorView)
    .isAppearanceLightStatusBars = true

// Set status bar icons to light
WindowCompat.getInsetsController(window, window.decorView)
    .isAppearanceLightStatusBars = false

محافظت از میله سیستم

اگرچه enableEdgeToEdge() نوارهای سیستمی شفاف یا نیمه‌شفاف پیش‌فرض را ارائه می‌دهد، ممکن است لازم باشد آن را سفارشی کنید. برای تصمیم‌گیری در مورد زمان استفاده از نوارهای شفاف در مقابل نیمه‌شفاف، به راهنمای طراحی نوارهای سیستمی اندروید و راهنمای طراحی Edge-to-edge مراجعه کنید.

برای اینکه نوار ناوبری سه دکمه‌ای به جای نیمه‌شفاف، کاملاً شفاف باشد، می‌توانید اعمال کنتراست را غیرفعال کنید:

window.isNavigationBarContrastEnforced = false

برای اطلاعات بیشتر، به «درباره محافظت از نوار سیستم» مراجعه کنید.

دیالوگ‌ها

برای نمایش پنجره‌های محاوره‌ای تمام صفحه به صورت لبه به لبه، تابع WindowCompat.enableEdgeToEdge را در متد onStart() مربوط به پنجره محاوره‌ای فراخوانی کنید:

class MyAlertDialogFragment : DialogFragment() {
    override fun onStart(){
        super.onStart()
        dialog?.window?.let { WindowCompat.enableEdgeToEdge(it) }
    }
    ...
}