پیش‌نمایش رابط کاربری خود را در Compose for Wear OS مشاهده کنید

پیش‌نمایش‌های نوشتن اندروید استودیو به شما امکان می‌دهد تا کامپوننت‌های Wear OS خود را در اندازه‌های مختلف صفحه نمایش ساعت، حاشیه‌های گرد و مقیاس‌های فونت، مستقیماً در IDE بررسی و تأیید کنید - بدون اینکه برنامه خود را روی یک ساعت یا شبیه‌ساز فیزیکی مستقر کنید.

از آنجا که دستگاه‌های Wear OS دارای نمایشگرهای دایره‌ای هستند که در آن گوشه‌ها محتوا را برش می‌دهند و پوشش‌های سیستمی مانند TimeText و ScrollIndicator در امتداد لبه صفحه نمایش منحنی می‌شوند، پیکربندی پیش‌نمایش‌ها به‌طور خاص برای Wear OS برای تشخیص زودهنگام مشکلات طرح‌بندی ضروری است.

وابستگی‌های پیش‌نمایش را تنظیم کنید

برای استفاده از حاشیه‌نویسی‌های پیش‌نمایش Wear OS Compose و تعاریف دستگاه، وابستگی‌های زیر را به فایل build.gradle.kts ماژول خود اضافه کنید:

dependencies {
    // Provides @WearPreview* multipreview annotations
    // (such as @WearPreviewDevices and @WearPreviewFontScales)
    implementation("androidx.wear.compose:compose-ui-tooling:1.7.0")

    // Provides WearDevices constants
    // (such as WearDevices.SMALL_ROUND and WearDevices.LARGE_ROUND)
    implementation("androidx.wear:wear-tooling-preview:1.0.0")

    // Standard Compose preview support and interactive/animation inspection
    implementation("androidx.compose.ui:ui-tooling-preview")
    debugImplementation("androidx.compose.ui:ui-tooling")
}

انتخاب کنید چه چیزی را پیش‌نمایش دهید: صفحه نمایش در مقابل اجزا

نحوه پیکربندی پیش‌نمایش بستگی به این دارد که آیا در حال پیش‌نمایش یک صفحه کامل یا یک جزء رابط کاربری جداگانه هستید.

پیش‌نمایش تمام صفحه ( AppScaffold + ScreenScaffold )

هنگام پیش‌نمایش کل صفحه، همیشه صفحه خود را در AppScaffold و ScreenScaffold با استفاده از حاشیه‌نویسی پیش‌نمایش دستگاه Wear قرار دهید. این کار صفحه نمایش دایره‌ای ساعت را رندر می‌کند و تضمین می‌کند که:

• TimeText در لبه منحنی بالای صفحه ساعت نمایش داده می‌شود.
• ScrollIndicator در امتداد قاب سمت راست ظاهر می‌شود.
• EdgeButton به درستی در موقعیت مناسب قرار گرفته و در منحنی پایین برش داده شده است.
• فاصله‌گذاری محتوا و برش دایره‌ای صفحه نمایش، دقیقاً منعکس‌کننده سخت‌افزار ساعت واقعی هستند.

@WearPreviewDevices
@Composable
fun WorkoutScreenPreview() {
    MaterialTheme {
        // AppScaffold provides the top-level TimeText overlay
        AppScaffold {
            // WorkoutScreen contains its own ScreenScaffold and content
            WorkoutScreen(
                heartRate = 142,
                elapsedTime = "12:45"
            )
        }
    }
}
WearPreviews.kt

گرد کوچک (۱۹۲x۱۹۲dp)

گرد بزرگ (۲۲۷x۲۲۷dp)

پیش‌نمایش اجزای ایزوله‌شده

هنگام پیش‌نمایش اجزای جداگانه - مانند یک Card ، Button یا تراشه وضعیت سفارشی - پارامتر device را حذف کنید و از یک @Preview استاندارد با پس‌زمینه تیره استفاده کنید. این تضمین می‌کند که رنگ‌ها و کنتراست Wear Material 3 بدون رندر کردن یک صفحه نمایش ساعت دایره‌ای کامل، به طور دقیق ظاهر می‌شوند:

@Preview(
    showBackground = true,
    backgroundColor = 0xFF000000
)
@Composable
fun HeartRateCardPreview() {
    MaterialTheme {
        HeartRateCard(bpm = 142, zone = "Aerobic")
    }
}
WearPreviews.kt

پیش‌نمایش کامپوننت ایزوله (بدون قاب دستگاه).

حاشیه‌نویسی‌های پیش‌نمایش چندگانه داخلی

بسته androidx.wear.compose.ui.tooling.preview حاشیه‌نویسی‌های داخلی ارائه می‌دهد که به‌طور خودکار پس‌زمینه‌های تیره ( backgroundColor = 0xFF000000 ، showBackground = true ) و ابعاد دایره‌ای دستگاه ساعت را پیکربندی می‌کنند:

شما می‌توانید @WearPreviewDevices ‎ و @WearPreviewFontScales ‎ را روی یک تابع پیش‌نمایش یکسان قرار دهید تا یک ماتریس تست جامع ایجاد کنید:

@WearPreviewDevices
@WearPreviewFontScales
@Composable
fun MessageDetailScreenPreview() {
    MaterialTheme {
        AppScaffold {
            MessageDetailScreen(
                sender = "Alex",
                body = "Running 5 mins late!"
            )
        }
    }
}
WearPreviews.kt

حاشیه‌نویسی‌های پیش‌نمایش سفارشی و مشخصات سخت‌افزاری

وقتی به کنترل دقیق‌تری نیاز دارید - مانند آزمایش ابعاد سخت‌افزاری خاص، رشته‌های محلی طولانی یا ترکیب‌های بدترین حالت - می‌توانید @Preview را مستقیماً پیکربندی کنید یا حاشیه‌نویسی‌های multipreview سفارشی خود را تعریف کنید.

ثابت‌های WearDevices موجود و مشخصات سخت‌افزاری سفارشی

شیء androidx.wear.tooling.preview.devices.WearDevices شناسه‌های استاندارد دستگاه را ارائه می‌دهد:

• WearDevices.SMALL_ROUND ( "id:wearos_small_round" , 192x192dp)
• WearDevices.LARGE_ROUND ( "id:wearos_large_round" ، 227x227dp)

برای پیش‌نمایش در نمایشگرهای گرد بسیار بزرگ (مانند ساعت‌های ۴۴ تا ۴۵ میلی‌متری یا مدل‌های Ultra با وضوح ۲۴۰x۲۴۰dp)، یک رشته spec: سفارشی را به پارامتر device ارسال کنید:

@Preview(
    name = "XL Round Watch (240dp)",
    device = "spec:width=240dp,height=240dp,dpi=320,isRound=true",
    showBackground = true,
    backgroundColor = 0xFF000000
)
@Composable
fun WorkoutScreenXlPreview() {
    MaterialTheme {
        AppScaffold {
            WorkoutScreen(heartRate = 142, elapsedTime = "12:45")
        }
    }
}
WearPreviews.kt

ایجاد حاشیه‌نویسی چند پیش‌نمایشی سفارشی

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

@Preview(
    name = "1. Standard Large Round",
    group = "Layout extremes",
    device = WearDevices.LARGE_ROUND,
    backgroundColor = 0xFF000000,
    showBackground = true
)
@Preview(
    name = "2. Extreme Small Round (Largest Font + German)",
    group = "Layout extremes",
    device = WearDevices.SMALL_ROUND,
    fontScale = 1.24f,
    locale = "de-rDE",
    backgroundColor = 0xFF000000,
    showBackground = true
)
annotation class WearPreviewExtremes
WearPreviews.kt

۱. گرد بزرگ استاندارد

۲. گرد خیلی کوچک (بزرگترین فونت + آلمانی)

پیش‌نمایش ستون‌های پیمایش ( TransformingLazyColumn )

به طور پیش‌فرض، یک TransformingLazyColumn با اولین آیتم خود ( index = 0 ) که به بالای صفحه پین ​​شده است، مقداردهی اولیه می‌شود. با این حال، در Wear OS، آیتم‌ها با نزدیک شدن به لبه‌های منحنی بالا و پایین صفحه، ارتفاع و گوشه‌های گرد خود را تغییر می‌دهند ( SurfaceTransformation )، و EdgeButton فقط زمانی ظاهر می‌شود که به پایین اسکرول شود.

برای پیش‌نمایش نحوه نمایش فهرست خود هنگام پیمایش به سمت پایین یا در پایین فهرست:

مرحله ۱: TransformingLazyColumnState در صفحه نمایش خود به حالت قابل ترکیب (composable) درآورید.

به تابع ترکیب صفحه نمایش خود اجازه دهید پارامتر TransformingLazyColumnState را با مقدار پیش‌فرض rememberTransformingLazyColumnState() بپذیرد:

@Composable
fun InboxScreen(
    messages: List<Message>,
    columnState: TransformingLazyColumnState = rememberTransformingLazyColumnState(),
) {
    val transformationSpec = rememberTransformationSpec()

    ScreenScaffold(
        scrollState = columnState,
        edgeButton = {
            EdgeButton(onClick = { /* Compose new */ }) {
                Text("New message")
            }
        }
    ) { contentPadding ->
        TransformingLazyColumn(
            state = columnState,
            contentPadding = contentPadding,
        ) {
            items(messages.size) { index ->
                Card(
                    onClick = {},
                    modifier = Modifier
                        .fillMaxWidth()
                        .transformedHeight(this, transformationSpec)
                        .minimumVerticalContentPadding(
                            CardDefaults.minimumVerticalListContentPadding
                        ),
                    transformation = SurfaceTransformation(transformationSpec),
                ) {
                    Text(messages[index].subject)
                }
            }
        }
    }
}
WearPreviews.kt

مرحله ۲: مقدار initialAnchorItemIndex را در @Preview خود وارد کنید.

rememberTransformingLazyColumnState دو پارامتر اولیه اختیاری برای اسکرول می‌پذیرد:

• initialAnchorItemIndex: Int : وقتی روی یک اندیس غیر منفی (مثلاً 3 ) تنظیم شود، لیست با قرار گرفتن آن آیتم در مرکز نمای watch مقداردهی اولیه می‌شود.
• initialAnchorItemScrollOffset: Int : افست پیکسلی اختیاری که نسبت به آیتم لنگر مرکزی اعمال می‌شود.

شما می‌توانید پیش‌نمایش‌های کنار هم ایجاد کنید که حالت‌های بالا ، وسط (پیمایش‌شده) و پایین ( EdgeButton قابل مشاهده) را دقیقاً در یک صفحه نمایش نشان می‌دهند:

@WearPreviewLargeRound
@Composable
fun InboxScreenTopPreview() {
    MaterialTheme {
        AppScaffold {
            // Default (-1): Pinned to top of list (index 0)
            InboxScreen(messages = sampleMessages)
        }
    }
}

@WearPreviewLargeRound
@Composable
fun InboxScreenScrolledMiddlePreview() {
    MaterialTheme {
        AppScaffold {
            // Centers item index 3 in the viewport, showing top/bottom item morphing
            InboxScreen(
                messages = sampleMessages,
                columnState = rememberTransformingLazyColumnState(
                    initialAnchorItemIndex = 3
                )
            )
        }
    }
}

@WearPreviewLargeRound
@Composable
fun InboxScreenBottomEdgeButtonPreview() {
    MaterialTheme {
        AppScaffold {
            // Anchors on the last item so the EdgeButton is visible at the bottom
            InboxScreen(
                messages = sampleMessages,
                columnState = rememberTransformingLazyColumnState(
                    initialAnchorItemIndex = sampleMessages.lastIndex
                )
            )
        }
    }
}
WearPreviews.kt

بالا (پیش‌فرض -1 )

میانه ( initialAnchorItemIndex = 3 )

پایین ( EdgeButton باز شده)

نکته: همچنین می‌توانید روی هر @Preview در اندروید استودیو، روی « شروع حالت تعاملی» کلیک کنید تا با ماوس یا ترک‌پد خود، TransformingLazyColumn را به صورت زنده پیمایش کنید و تغییر شکل SurfaceTransformation ، انیمیشن‌های ورودی EdgeButton و حرکت ScrollIndicator را به صورت بلادرنگ بررسی کنید.

محافظ ScrollIndicator در حین ضبط اسکرول ( LocalScrollCaptureInProgress )

وقتی ابزارهای تست اسکرین‌شات سیستمی (اسکرین‌شات‌های طولانی) یا اسکرین‌شات‌های چند فریمی، یک صفحه پیمایشی TransformingLazyColumn را ثبت می‌کنند، Compose مقدار LocalScrollCaptureInProgress.current را روی true تنظیم می‌کند و همزمان چندین کاشی viewport را به صورت عمودی به هم می‌چسباند.

از آنجا که ScreenScaffold به طور خودکار scrollIndicator خود را در حین ضبط اسکرول پنهان نمی‌کند، نوار اسکرول شناور روی هر کاشی دوخته شده از یک اسکرین شات طولانی تکرار می‌شود، مگر اینکه صریحاً آن را با !LocalScrollCaptureInProgress.current محافظت کنید:

ScreenScaffold(
    scrollState = columnState,
    scrollIndicator = {
        if (!LocalScrollCaptureInProgress.current) {
            ScrollIndicator(state = columnState)
        }
    }
) { contentPadding ->
    // TransformingLazyColumn content...
    // ...
}
WearPreviews.kt