هماهنگ کردن میانای کاربر با نوار وضعیت سیستم

تا Wear OS 7 (میانای برنامه‌سازی کاربردی ۳۷)، پلاتفرم نوار وضعیت سیستم را روی پنجره‌های برنامه ارائه نمی‌کرد—برنامه‌ها کل صفحه را دراختیار داشتند و می‌توانستند هر محتوایی را در موقعیت بالا (ساعت ۱۲) ترسیم کنند (مانند ساعت TimeText درون‌برنامه، سرایندهای منحنی سفارشی، یا کنترل‌های بالا).

از Wear OS 8 شروع می‌شود—و اکنون برای آزمایش پیش‌نمایش اولیه در Wear OS 7.1 Beta Preview Emulator (API 37.2-beta1) دردسترس است—سیستم یک نوار وضعیت را روی پنجره‌های برنامه در موقعیت ساعت ۱۲ برای نمایش زمان و نشانگرهای وضعیت ارائه می‌دهد. برای جلوگیری از هم‌پوشانی با نوار وضعیت سیستم، برنامه‌ها باید از ارائه ساعت خود (TimeText) خودداری کنند و به حاشیه‌های پنجره نوار وضعیت بالا احترام بگذارند (که به‌طور خودکار توسط AppScaffold و ScreenScaffold از Wear Compose 1.8 به بعد مدیریت می‌شود)، یا نوار وضعیت سیستم را زمانی که تجربه فراگیر تمام‌صفحه نیاز است، پنهان کنند.

مزایای کلیدی شامل موارد زیر است:

• ثبات بصری: طرح حروف، جای‌گذاری، و صفحه پشتی یکسان برای ساعت در سراسر سیستم و همه برنامه‌ها.
• نشانگرهای وضعیت سیستم: به پلاتفرم اجازه می‌دهد نمادهای وضعیت (مانند نشانگرهای فعال میکروفون و مکان، وضعیت اتصال، یا اطلاعات باتری) و زمان را در سطوح مختلف نمایش دهد. هر بار فقط یک نماد براساس اولویت نشان داده می‌شود.
• هماهنگی خودکار پیمایش و انتقال: وقتی با Jetpack Compose برای Wear OS 1.8 جفت می‌شود، نوار وضعیت سیستم به‌طور خودکار هنگام پیمایش کاربران در محتوا پنهان می‌شود و پس‌از یک تأخیر کوتاه (۲ ثانیه) در حالت غیرفعال دوباره ظاهر می‌شود.

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

برای شروع، مراحل پیش‌نیاز زیر را تکمیل کنید:

1. «پیش‌نمایش استودیو Android» (Canary) را نصب کنید.
2. در «مدیر SDK»، «تصویر سیستم شبیه‌ساز پیش‌نمایش Wear OS 7.1» (میانای برنامه‌سازی کاربردی 37.2-beta1) را بارگیری کنید. این نسخه دسترسی زودرس به نوار وضعیت سیستم Wear OS 8 را پیش‌از کیت توسعه نرم‌افزار Wear OS 8 ارائه می‌دهد.
3. در «مدیر دستگاه»، بااستفاده از تصویر API 37.2-beta1، دستگاه مجازی Wear OS ایجاد و راه‌اندازی کنید.

برای پشتیبانی از نوار وضعیت سیستم در برنامه‌تان، نسخه targetSdk برنامه‌تان را به ۳۵ یا بالاتر به‌روز کنید. پلاتفرم فقط نوار وضعیت سیستم را برای برنامه‌هایی که API 35 و بالاتر را هدف قرار می‌دهند فعال می‌کند تا سازگاری با نسخه‌های قدیمی‌تر برای برنامه‌های قدیمی حفظ شود. علاوه‌براین، وابستگی‌های Wear Compose خود را به جدیدترین نسخه آلفا (درحال‌حاضر 1.8.0-alpha02) به‌روز کنید، همان‌طور که در قطعه کد زیر نشان داده شده است. اگر برنامه‌تان از نسخه قدیمی‌تر Wear Compose استفاده می‌کند، می‌توانید از مهارت انتقال Wear Compose Material 3 برای تسهیل انتقال استفاده کنید.

android {
    defaultConfig {
        targetSdk = 35
    }
}

dependencies {
    implementation("androidx.wear.compose:compose-foundation:1.8.0-alpha02")
    implementation("androidx.wear.compose:compose-material3:1.8.0-alpha02")
}

استفاده از نوار وضعیت سیستم

در جدیدترین نسخه آلفای Wear Compose Material 3 1.8.0 (درحال‌حاضر 1.8.0-alpha02)، کتابخانه به‌طور خودکار برنامه شما را با ادغام کردن ویژگی com.google.wear.ENABLE_GLOBAL_STATUS_BAR <meta-data> در AndroidManifest.xml شما فعال می‌کند. در زمان اجرا، AppScaffold و ScreenScaffold بررسی می‌کنند که آیا نوار وضعیت سیستم در دستگاه فعال است یا نه و آیا این ویژگی موافقت مانیفست روی true تنظیم شده است یا نه:

• در شبیه‌ساز پیش‌نمایش / Wear OS 8+‎ (درصورت موافقت): AppScaffold TimeText داخلی خود را سرکوب می‌کند تا نوار وضعیت سیستم به‌طور تمیز در موقعیت ساعت ۱۲ بدون تکرار ارائه شود. ScreenScaffold re-calculates contentPadding to take Status Bar inset boundaries into account and coordinates hiding and showing the status bar as the list scrolls.
• در Wear OS 7 و دستگاه‌های قدیمی‌تر (یا وقتی موافقت نشده باشد): AppScaffold به‌طور خودکار به ارائه TimeText استاندارد درون‌برنامه برمی‌گردد، و سازگاری کامل با نسخه قدیمی را از یک پایگاه کد واحد حفظ می‌کند.

@Composable
fun GsbSampleApp() {
    // AppScaffold coordinates the system status bar across the app
    // and falls back to rendering TimeText on Wear OS 7 and earlier.
    AppScaffold {
        val columnState = rememberTransformingLazyColumnState()

        // ScreenScaffold includes status bar top inset clearance in
        // contentPadding and hides/shows the status bar during list scrolling.
        ScreenScaffold(scrollState = columnState) { contentPadding ->
            TransformingLazyColumn(
                state = columnState,
                contentPadding = contentPadding,
            ) {
                item {
                    ListHeader { Text("Hello Status Bar") }
                }
                items(count = 15) { index ->
                    Button(onClick = { /* Handle click */ }) {
                        Text("Item #${index + 1}")
                    }
                }
            }
        }
    }
}

هنگام اجرای نمونه، این چیزی است که باید انتظار داشته باشید:

• در حالت سکون (بالای فهرست): نوار وضعیت سیستم در موقعیت ساعت ۱۲ نمایش داده می‌شود. سرصفحه «Hello Status Bar» زیر ناحیه درج نوار وضعیت قرار می‌گیرد، بدون اینکه بریده شود یا هم‌پوشانی داشته باشد.
• پیمایش به پایین: وقتی در موارد فهرست پیمایش می‌کنید، نوار وضعیت پنهان می‌شود و موارد فهرست به‌صورت لبه‌به‌لبه در پشت قاب بالایی پیمایش می‌شوند.
• بیکار: وقتی پیمایش را متوقف می‌کنید و صفحه را رها می‌کنید، نوار وضعیت به‌طور خودکار پس‌از حدود ۲ ثانیه دوباره ظاهر می‌شود.

مدیریت سناریوها و سفارشی‌سازی‌های رایج

بخش‌های زیر نحوه مدیریت سناریوهای رایجی را که ممکن است هنگام کار با نوار وضعیت سیستم با آن‌ها مواجه شوید شرح می‌دهند.

رسیدگی به صفحه‌های غیرقابل‌پیمایش (ثابت)

در صفحه‌هایی که به‌جای فهرست پیمایشی از چیدمان ایستا (مثل Column یا Box) استفاده می‌کنند، contentPadding ارائه‌شده توسط ScreenScaffold را در چیدمان ریشه‌ای خود اعمال کنید تا عناصر واسط کاربر بالایی با نوار وضعیت سیستم هم‌پوشانی نداشته باشند:

AppScaffold {
    ScreenScaffold { contentPadding ->
        Column(modifier = Modifier.padding(contentPadding)) {
            Text("Static Screen Content")
        }
    }
}

کار با مؤلفه‌های تعاملی تمام‌صفحه

مؤلفه‌های تعاملی تمام‌صفحه در Wear Compose Material 3—شامل AlertDialog، Dialog، Stepper، TimePicker، و DatePicker—به‌طور خودکار نوار وضعیت سیستم را هنگام نمایش روی صفحه پنهان می‌کنند تا کنترل‌های آن‌ها دسترسی کامل به بالای نمایشگر دایره‌ای داشته باشند. وقتی بسته شد، نوار وضعیت سیستم به‌طور خودکار بااستفاده از میانای برنامه‌سازی کاربردی کنترل‌کننده درج‌های پنجره بازیابی می‌شود.

رفتن به حالت فراگیر

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

درنظر گرفتن زمان استفاده از حالت تمرکز بر محتوا در سطح صفحه

اگر فقط صفحه‌نمایش خاصی در برنامه‌تان باید تمام‌صفحه / فراگیر باشد، StatusBarSuppression() را در محتوای ScreenScaffold فراخوانی کنید. ScreenScaffold به‌طور خودکار نوار وضعیت سیستم را پنهان می‌کند (و لایه داخلی نوار وضعیت بالا را حذف می‌کند) درحالی‌که آن صفحه فعال است، سپس نوار وضعیت سیستم را هنگام پیمایش به صفحه‌های دیگر بازیابی می‌کند:

AppScaffold {
    ScreenScaffold() {
        StatusBarSuppression()
        // Full-screen immersive content
    }
}

درنظر گرفتن زمان استفاده از حالت فراگیر در سطح برنامه

اگر کل برنامه شما (یا Activity) تجربه تمام‌صفحه فراگیر در همه صفحه‌ها است، از StatusBarSuppression در سطح AppScaffold استفاده کنید و محتوایتان را بپوشانید تا نوار وضعیت سیستم در همه صفحه‌ها پنهان شود:

// Use StatusBarSuppression at AppScaffold level and wrap your content
// to suppress status bar in the entire scaffold.
AppScaffold {
    StatusBarSuppression {
        SwipeDismissableNavHost(...) {
            // Nested screens inherit suppression and 0.dp padding
        }
    }
}

نمایش لغوهای نوشتار زمان سفارشی

اگر لازم است سرصفحه منحنی سفارشی نمایش دهید یا موقتاً از نوار وضعیت سیستم در صفحه‌نمایش خاصی یا در سراسر برنامه‌تان درطول انتقال برای Wear OS 8 انصراف دهید، ارسال timeText قابل‌ترکیب سفارشی نوار وضعیت سیستم را سرکوب می‌کند:

// Screen-level custom TimeText override:
ScreenScaffold(
    timeText = { TimeText { timeTextCurvedText("Custom Status") } },
) {
    // Content
}

// App-level opt-out using in-app TimeText:
AppScaffold(
    timeText = { TimeText() },
) {
    // Screens
}

پیاده‌سازی بااستفاده از «نماها» (توصیه نمی‌شود)

اگر برنامه‌تان به‌جای Jetpack Compose برای Wear OS از Android Views استفاده می‌کند، بااستفاده از AndroidManifest.xml موافقت کنید. برخلاف جدیدترین نسخه آلفای Wear Compose Material 3 که نوار وضعیت سیستم را به‌طور خودکار فعال می‌کند، برنامه‌های مبتنی بر View باید با افزودن برچسب ENABLE_GLOBAL_STATUS_BAR <meta-data> در <application> به‌طور صریح موافقت کنند:

<application ...>
    <meta-data
        android:name="com.google.wear.ENABLE_GLOBAL_STATUS_BAR"
        android:value="true" />
</application>

نظارت بر درج‌های پنجره بالایی

از ViewCompat.setOnApplyWindowInsetsListener استفاده کنید و مقدار windowInsets.getInsets(WindowInsetsCompat.Type.statusBars()) را بررسی کنید. وقتی statusBarInsets.top > 0، واسط کاربر قدیمی ساعت ۱۲ را بردارید و حاشیه داخلی بالا را تنظیم کنید؛ درغیراین‌صورت، به واسط کاربر قدیمی برگردید:

ViewCompat.setOnApplyWindowInsetsListener(rootView) { view, windowInsets ->
    val statusBarInsets = windowInsets.getInsets(
        WindowInsetsCompat.Type.statusBars()
    )

    if (statusBarInsets.top > 0) {
        // status bar is visible: remove legacy 12 o'clock UI and apply top inset padding
        view.updatePadding(top = statusBarInsets.top)
    } else {
        // status bar is not visible: fall back to legacy UI and padding
    }

    WindowInsetsCompat.CONSUMED
}

پنهان کردن و نمایش دادن نوار وضعیت به‌صورت برنامه‌نویسی‌شده

برخلاف ScreenScaffold در Compose، برنامه‌های مبتنی بر View باید به‌طور صریح نوار وضعیت سیستم را پنهان یا نمایان کنند (برای مثال، هنگام ورود به نمای فراگیر تمام‌صفحه یا هماهنگ کردن رفتار پیمایش) بااستفاده از WindowInsetsControllerCompat:

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

// Hide the status bar
insetsController.hide(WindowInsetsCompat.Type.statusBars())

// Show the status bar
insetsController.show(WindowInsetsCompat.Type.statusBars())

آزمایش برنامه

هنگام آزمایش کردن برنامه‌تان در «شبیه‌ساز پیش‌نمایش Wear OS 7.1 Beta» (‏API 37.2-beta1)، موارد زیر را بررسی کنید:

• ساعت فقط یک‌بار نشان داده می‌شود: بررسی کنید که فقط زمان نوار وضعیت سیستم در موقعیت ساعت ۱۲ نشان داده شود و هیچ TimeText قدیمی درون‌برنامه و محتوای برنامه با آن هم‌پوشانی نداشته باشد.
• حاشیه داخلی بالا: بررسی کنید که عنوان‌های صفحه، سرصفحه‌ها، و دکمه‌های بالا زیر نوار وضعیت نشان داده شوند.
• کادرهای گفتگو و هم‌پوشانی‌های تمام‌صفحه: بررسی کنید که کادرهای گفتگو، انتخابگرها، مراحل، و فعالیت‌های تمام‌صفحه سفارشی هنگام باز شدن نوار وضعیت را پنهان کنند و هنگام بسته شدن آن را بازیابی کنند.