سطوح در Jetpack Compose Glimmer

دستگاه‌های XR قابل‌اعمال

این راهنمایی به شما کمک می‌کند برای این نوع دستگاه‌های واقعیت گسترده تجربه بسازید.

آشنایی با انواع دستگاه‌های XR →

آشنایی با انواع دستگاه‌های XR →

در Jetpack Compose Glimmer، عنصر surface یک واحد سازنده اساسی است که یک ناحیه بصری متمایز یا یک مرز فیزیکی برای عناصری مانند دکمه‌ها و کارت‌ها را نشان می‌دهد.

سطح مسئولیت ویژگی‌های بصری و فیزیکی زیر را برعهده دارد:

• برش: فرزندانش را به شکل مشخصی برش می‌دهد.
• حاشیه: حاشیه داخلی‌ای رسم می‌کند تا مرز مؤلفه را برجسته کند. وقتی متمرکز باشد، حاشیه پهن‌تری با برجستگی متمرکز رسم می‌کند.
• پس‌زمینه: رنگ پس‌زمینه‌ای را به سطح اعمال می‌کند.
• جلوه‌های عمق: براساس وضعیت عنصر (مثل پیش‌فرض درمقایسه با متمرکز)، DepthEffect سایه ارائه می‌کند.
• رنگ محتوا: رنگی برای نوشتار و نمادهای داخل سطح ارائه می‌دهد که به‌طور پیش‌فرض از رنگ پس‌زمینه محاسبه می‌شود.
• وضعیت‌های تعامل: وقتی سطح فشرده می‌شود، رونهاد فشرده‌ای رسم می‌کند و وقتی تمرکز می‌کند، حاشیه پهن‌تری با برجستگی رسم می‌کند.

مثال: ایجاد سطح

کد زیر سطحی با برش، پس‌زمینه، و حاشیه‌های پیش‌فرض ایجاد می‌کند:

@Composable
fun SurfaceSample() {
    Box(Modifier.surface().padding(horizontal = 24.dp, vertical = 20.dp)) {
        Text("This is a surface")
    }
}

تعامل و تمرکز

سطوح به‌طور پیش‌فرض قابل‌تمرکز نیستند، بنابراین کاربران نمی‌توانند با آن‌ها تعامل داشته باشند. در اکثر موارد، سطوح باید تعاملی باشند تا به کاربران اجازه دهند به‌طور پیوسته تمرکز را جابه‌جا کنند و بین عناصر پیمایش کنند. می‌توانید از اصلاح‌گر «نوشتن» focusable برای سطوحی که فقط برای قابل‌تمرکز شدن درنظر گرفته شده‌اند استفاده کنید. به‌همین ترتیب، می‌توانید بااستفاده از اصلاح‌گر Compose clickable سطحی کلیک‌کردنی ایجاد کنید. همچنین می‌توانید از اصلاح‌کننده‌های دیگر برای سطوحی که نیاز به کنش دارند استفاده کنید.

کد زیر نمونه‌هایی از سطوح قابل‌تمرکز و کلیک‌کردنی را نشان می‌دهد:

@Composable
fun FocusableSurfaceSample() {
    val interactionSource = remember { MutableInteractionSource() }
    Box(
        modifier = Modifier
            .size(100.dp)
            .surface(interactionSource = interactionSource)
            .focusable(interactionSource = interactionSource),
        contentAlignment = Alignment.Center
    ) {
        Text("Focusable")
    }
}

@Composable
fun ClickableSurfaceSample() {
    val interactionSource = remember { MutableInteractionSource() }
    Box(
        modifier = Modifier
            .size(100.dp)
            .surface(interactionSource = interactionSource)
            .focusable(interactionSource = interactionSource)
            .clickable(
                interactionSource = interactionSource,
                indication = null
            ) { /* Handle click action */ },
        contentAlignment = Alignment.Center
    ) {
        Text("Clickable")
    }
}
SurfaceSamples.kt

نکات کلیدی درباره کد

• منبع تعامل هم‌رسانی‌شده برای سطوح کانونی: هم .surface() و هم .focusable() باید از interactionSource یکسانی استفاده کنند. این کار به سطح اجازه می‌دهد به تغییرات تمرکز واکنش نشان دهد.

• منبع تعامل هم‌رسانی‌شده برای سطوح کلیک‌کردنی: هم .surface() و هم .clickable() باید interactionSource یکسانی داشته باشند. این کار تضمین می‌کند که وضعیت‌های دیداری (مثل فشار دادن یا تمرکز کردن) همگام‌سازی شوند و به سطح اجازه می‌دهد به درونداد کاربر واکنش دیداری نشان دهد.

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

SurfaceDepthEffect

کلاس SurfaceDepthEffect گذار سایه‌ها بین حالت‌های تعامل را مدیریت می‌کند:

• depthEffect: جلوه سایه که وقتی سطح در حالت پیش‌فرض خود است استفاده می‌شود.
• focusedDepthEffect: جلوه سایه که وقتی سطح در کانون توجه است استفاده می‌شود.