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

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

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

اقدامات زیر در این صفحه شرح داده شده است:

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

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

یکی از موارد زیر را در actionStartActivity وارد کنید:

Glance، اکشن (Action) را با هدف و پارامترهای ارائه شده به یک 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 یک رویداد broadcast را در تعامل با کاربر ارسال کنید:

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

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

انجام اقدامات سفارشی

به جای راه‌اندازی یک هدف خاص، Glance می‌تواند از یک عمل lambda یا یک actionRunCallback برای انجام عملی مانند به‌روزرسانی رابط کاربری یا وضعیت در تعامل با کاربر استفاده کند.

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

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

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

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

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

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)
    }
}

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

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

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() }
    }
}

در زیر، پارامترها در intent مورد استفاده برای راه اندازی activity گنجانده شده اند و به Activity هدف اجازه می دهند تا آن را بازیابی کند. 

    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
        // ...
    }
}

قبلی
تست واحد با Glance
بعدی
معیارهای ویجت خود را پیگیری کنید