مدیریت تعامل کاربر

‫Glance بااستفاده از کلاس‌های Action، مدیریت تعامل کاربر را ساده می‌کند. کلاس‌های Action Glance کنش‌هایی را که کاربر می‌تواند انجام دهد تعریف می‌کنند و می‌توانید عملیاتی را که در پاسخ به کنش انجام می‌شود مشخص کنید. می‌توانید Action را به هر عنصری با روش GlanceModifier.clickable اعمال کنید.

ابزارک‌های برنامه در فرایندی از دور اجرا می‌شوند، بنابراین کنش‌ها در زمان ایجاد تعریف می‌شوند و اجرا در فرایند از دور انجام می‌شود. در RemoteViews بومی، این کار بااستفاده از PendingIntents انجام می‌شود.

کنش‌های زیر در این صفحه شرح داده شده است:

راه‌اندازی فعالیت

برای راه‌اندازی فعالیت در تعامل کاربر، تابع actionStartActivity را به Button یا دیگر عناصر ترکیب‌پذیر بااستفاده از تعدیل‌کننده GlanceModifier.clickable ارائه دهید.

یکی از موارد زیر را به زبان actionStartActivity ارائه دهید:

‫Glance «کنش» را با هدف و پارامترهای ارائه‌شده به PendingIntent ترجمه می‌کند. در مثال زیر، وقتی کاربر روی دکمه کلیک می‌کند، NavigationActivity راه‌اندازی می‌شود:

@Composable
fun MyContent() {
    // ..
    Button(
        text = "Go Home",
        onClick = actionStartActivity<MyActivity>()
    )
}

راه‌اندازی سرویس

مشابه با راه‌اندازی فعالیت، سرویسی را در تعامل کاربر بااستفاده از یکی از روش‌های actionStartService راه‌اندازی کنید.

یکی از موارد زیر را به زبان actionStartService ارائه دهید:

@Composable
fun MyButton() {
    // ..
    Button(
        text = "Sync",
        onClick = actionStartService<SyncService>(
            isForegroundService = true // define how the service is launched
        )
    )
}

ارسال رویداد همه‌فرستی

رویداد همه‌فرستی را درباره تعامل کاربر بااستفاده از یکی از روش‌های actionSendBroadcast زیر ارسال کنید:

یکی از موارد زیر را به زبان actionSendBroadcast ارائه دهید:

@Composable
fun MyButton() {
    // ..
    Button(
        text = "Send",
        onClick = actionSendBroadcast<MyReceiver>()
    )
}

انجام کنش‌های سفارشی

«نگاه سریع» به‌جای راه‌اندازی هدف خاص، می‌تواند از کنش لامبدا یا actionRunCallback برای انجام کنش، مثل به‌روزرسانی کردن میانای کاربر یا وضعیت در تعامل کاربر استفاده کند.

اجرا کردن کنش‌های لامبدا

می‌توانید از توابع لامبدا به‌عنوان برگشت‌تماس برای تعاملات واسط کاربر استفاده کنید.

برای مثال، تابع لامبدا را به اصلاح‌کننده GlanceModifier.clickable ارسال کنید:

Text(
    text = "Submit",
    modifier = GlanceModifier.clickable {
        submitData()
    }
)

یا آن را به پارامتر onClick در عناصر ترکیبی که از آن پشتیبانی می‌کنند منتقل کنید:

Button(
    text = "Submit",
    onClick = {
        submitData()
    }
)

اجرای ActionCallback

یا از روش‌های actionRunCallback برای انجام کنش در تعامل کاربر استفاده کنید. برای انجام این کار، پیاده‌سازی سفارشی از ActionCallback ارائه دهید:

@Composable
private fun MyContent() {
    // ..
    Image(
        provider = ImageProvider(R.drawable.ic_hourglass_animated),
        modifier = GlanceModifier.clickable(
            onClick = actionRunCallback<RefreshAction>()
        ),
        contentDescription = "Refresh"
    )
}

class RefreshAction : ActionCallback {
    override suspend fun onAction(
        context: Context,
        glanceId: GlanceId,
        parameters: ActionParameters
    ) {
        // TODO implement
    }
}

با کلیک کاربر، روش suspend onAction ارائه‌شده در ActionCallback فراخوانده می‌شود و منطق تعریف‌شده را اجرا می‌کند (یعنی درخواست بازآوری داده‌ها).

برای به‌روزرسانی ابزاره پس‌از انجام کنش، نمونه جدیدی ایجاد کنید و update(..) را فراخوانی کنید. برای جزئیات بیشتر، بخش مدیریت وضعیت GlanceAppWidget را ببینید.

class RefreshAction : ActionCallback {
    override suspend fun onAction(
        context: Context,
        glanceId: GlanceId,
        parameters: ActionParameters
    ) {
        // do some work but offset long-term tasks (e.g a Worker)
        MyAppWidget().update(context, glanceId)
    }
}

ارائه پارامترها برای کنش‌ها

برای ارائه اطلاعات تکمیلی درباره کنش، از ActionParameters API برای ایجاد جفت کلید-مقدار تایپ‌شده استفاده کنید. برای مثال، برای تعریف مقصد کلیک‌شده:

private val destinationKey = ActionParameters.Key<String>(
    NavigationActivity.KEY_DESTINATION
)

class MyAppWidget : GlanceAppWidget() {

    // ..

    @Composable
    private fun MyContent() {
        // ..
        Button(
            text = "Home",
            onClick = actionStartActivity<NavigationActivity>(
                actionParametersOf(destinationKey to "home")
            )
        )
        Button(
            text = "Work",
            onClick = actionStartActivity<NavigationActivity>(
                actionParametersOf(destinationKey to "work")
            )
        )
    }

    override suspend fun provideGlance(context: Context, id: GlanceId) {
        provideContent { MyContent() }
    }
}

در زیر، پارامترها در هدفی که برای راه‌اندازی فعالیت استفاده می‌شود گنجانده شده است و به «فعالیت» هدف اجازه می‌دهد آن را بازیابی کند.

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val destination = intent.extras?.getString(KEY_DESTINATION) ?: return
        // ...
    }
}

پارامترها به ActionCallback نیز ارائه می‌شود. برای بازیابی مقدار، از Parameters.Key تعریف‌شده استفاده کنید:

class RefreshAction : ActionCallback {

    private val destinationKey = ActionParameters.Key<String>(
        NavigationActivity.KEY_DESTINATION
    )

    override suspend fun onAction(
        context: Context,
        glanceId: GlanceId,
        parameters: ActionParameters
    ) {
        val destination: String = parameters[destinationKey] ?: return
        // ...
    }
}