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

از tooltip ها برای اضافه کردن متن به یک دکمه یا عنصر رابط کاربری دیگر استفاده کنید. دو نوع tooltip وجود دارد:

• نکات راهنمای ساده : عناصر یا عملکردهای دکمه‌های آیکون را شرح دهید.
• نکات راهنمای غنی : جزئیات بیشتری مانند توصیف ارزش یک ویژگی ارائه می‌دهد. همچنین می‌تواند شامل عنوان، لینک و دکمه‌های اختیاری باشد.

شکل 1. یک راهنمای ابزار ساده (1) و یک راهنمای ابزار غنی (2).

سطح API

شما می‌توانید از TooltipBox composable برای پیاده‌سازی tooltipها در برنامه خود استفاده کنید. شما می‌توانید ظاهر TooltipBox با این پارامترهای اصلی کنترل کنید:

• positionProvider : ابزارک را نسبت به محتوای لنگر قرار می‌دهد. شما معمولاً از یک ارائه‌دهنده موقعیت پیش‌فرض از TooltipDefaults استفاده می‌کنید، یا در صورت نیاز به منطق موقعیت‌یابی سفارشی، می‌توانید مورد دلخواه خود را ارائه دهید.
• tooltip : ترکیبی که شامل محتوای tooltip است. معمولاً از ترکیب‌های PlainTooltip یا RichTooltip استفاده می‌کنید.
  • از PlainTooltip برای توصیف عناصر یا عملکردهای دکمه‌های آیکون استفاده کنید.
  • از RichTooltip برای ارائه جزئیات بیشتر، مانند توصیف مقدار یک ویژگی، استفاده کنید. RichTooltipها می‌توانند شامل عنوان، لینک و دکمه‌های اختیاری باشند.
• state : نگهدارنده‌ی حالتی که شامل منطق رابط کاربری و حالت عنصر برای این tooltip است.
• content : محتوای قابل ترکیبی که tooltip به آن متصل شده است.

نمایش یک راهنمای ابزار ساده

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

@Composable
fun PlainTooltipExample(
    modifier: Modifier = Modifier,
    plainTooltipText: String = "Add to favorites"
) {
    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberPlainTooltipPositionProvider(),
        tooltip = {
            PlainTooltip { Text(plainTooltipText) }
        },
        state = rememberTooltipState()
    ) {
        IconButton(onClick = { /* Do something... */ }) {
            Icon(
                imageVector = Icons.Filled.Favorite,
                contentDescription = "Add to favorites"
            )
        }
    }
}
Tooltips.kt

نکات کلیدی در مورد کد

• TooltipBox یک tooltip با متن "افزودن به علاقه‌مندی‌ها" تولید می‌کند.
  • TooltipDefaults.rememberPlainTooltipPositionProvider() موقعیت پیش‌فرض را برای tooltipهای ساده فراهم می‌کند.
  • tooltip یک تابع لامبدا است که محتوای tooltip را با استفاده از PlainTooltip composable تعریف می‌کند.
  • Text(plainTooltipText) متن درون tooltip را نمایش می‌دهد.
  • tooltipState وضعیت tooltip را کنترل می‌کند.
• IconButton یک دکمه قابل کلیک با یک آیکون ایجاد می‌کند.
  • Icon(...) یک آیکون قلب را درون دکمه نمایش می‌دهد.
  • وقتی کاربر با IconButton تعامل می‌کند، TooltipBox تولتیپ را با متن "افزودن به علاقه‌مندی‌ها" نشان می‌دهد. بسته به دستگاه، کاربران می‌توانند تولتیپ را به روش‌های زیر فعال کنند:
  • قرار دادن نشانگر ماوس روی آیکون
  • فشار دادن طولانی مدت آیکون در دستگاه تلفن همراه

نتیجه

این مثال یک tooltip ساده روی یک آیکون تولید می‌کند:

شکل ۲. یک راهنمای ابزار ساده که وقتی کاربر موس را روی آیکون قلب می‌برد یا آن را برای مدت طولانی فشار می‌دهد، ظاهر می‌شود.

نمایش یک راهنمای ابزار غنی

از یک راهنمای ابزار غنی برای ارائه اطلاعات بیشتر در مورد یک عنصر رابط کاربری استفاده کنید. این مثال یک راهنمای ابزار غنی چند خطی با عنوانی که به یک Icon متصل است، ایجاد می‌کند:

@Composable
fun RichTooltipExample(
    modifier: Modifier = Modifier,
    richTooltipSubheadText: String = "Rich Tooltip",
    richTooltipText: String = "Rich tooltips support multiple lines of informational text."
) {
    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberRichTooltipPositionProvider(),
        tooltip = {
            RichTooltip(
                title = { Text(richTooltipSubheadText) }
            ) {
                Text(richTooltipText)
            }
        },
        state = rememberTooltipState()
    ) {
        IconButton(onClick = { /* Icon button's click event */ }) {
            Icon(
                imageVector = Icons.Filled.Info,
                contentDescription = "Show more information"
            )
        }
    }
}
Tooltips.kt

نکات کلیدی در مورد کد

• TooltipBox شنونده‌های رویداد را برای تعاملات کاربر مدیریت می‌کند و TooltipState را بر اساس آن به‌روزرسانی می‌کند. وقتی TooltipState اعلام می‌کند که tooltip باید نمایش داده شود، لامبدا tooltip اجرا می‌شود و TooltipBox RichTooltip نمایش می‌دهد. TooltipBox به عنوان لنگر و ظرف برای محتوا و tooltip عمل می‌کند.
  • در این حالت، محتوا یک کامپوننت IconButton است که رفتار عملی قابل لمس را فراهم می‌کند. وقتی روی هر جایی از محتوای TooltipBox به مدت طولانی فشار داده شود (در دستگاه‌های لمسی) یا ماوس روی آن قرار گیرد (مانند اشاره‌گر ماوس)، tooltip برای نمایش اطلاعات بیشتر نمایش داده می‌شود.
• تابع ترکیبی RichTooltip محتوای tooltip، شامل عنوان و متن بدنه را تعریف می‌کند. TooltipDefaults.rememberRichTooltipPositionProvider() اطلاعات موقعیت‌یابی را برای tooltipهای غنی فراهم می‌کند.

نتیجه

این مثال یک راهنمای ابزار غنی با عنوانی متصل به یک آیکون اطلاعات تولید می‌کند:

شکل ۳. یک راهنمای ابزار غنی با عنوان و یک آیکون اطلاعات.

یک راهنمای ابزار غنی را سفارشی کنید

این قطعه کد یک راهنمای ابزار غنی با عنوان، اقدامات سفارشی و یک هشتک (فلش) سفارشی را که در بالای دکمه نماد دوربین نمایش داده می‌شود، نمایش می‌دهد:

@Composable
fun AdvancedRichTooltipExample(
    modifier: Modifier = Modifier,
    richTooltipSubheadText: String = "Custom Rich Tooltip",
    richTooltipText: String = "Rich tooltips support multiple lines of informational text.",
    richTooltipActionText: String = "Dismiss"
) {
    val tooltipState = rememberTooltipState()
    val coroutineScope = rememberCoroutineScope()

    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberRichTooltipPositionProvider(),
        tooltip = {
            RichTooltip(
                title = { Text(richTooltipSubheadText) },
                action = {
                    Row {
                        TextButton(onClick = {
                            coroutineScope.launch {
                                tooltipState.dismiss()
                            }
                        }) {
                            Text(richTooltipActionText)
                        }
                    }
                },
            ) {
                Text(richTooltipText)
            }
        },
        state = tooltipState
    ) {
        IconButton(onClick = {
            coroutineScope.launch {
                tooltipState.show()
            }
        }) {
            Icon(
                imageVector = Icons.Filled.Camera,
                contentDescription = "Open camera"
            )
        }
    }
}
Tooltips.kt

نکات کلیدی در مورد کد

• یک RichToolTip یک tooltip با عنوان و عملکرد رد کردن نمایش می‌دهد.
• وقتی این گزینه فعال می‌شود، چه با نگه داشتن طولانی مدت انگشت روی ToolTipBox و چه با نگه داشتن ماوس روی محتوای آن، حدود یک ثانیه نمایش داده می‌شود. می‌توانید با ضربه زدن روی هر جای دیگری از صفحه یا استفاده از دکمه‌ی رد کردن، این ابزار را غیرفعال کنید.
• وقتی اکشن dismiss اجرا می‌شود، سیستم یک coroutine برای فراخوانی tooltipState.dismiss اجرا می‌کند. این کار تأیید می‌کند که اجرای اکشن در حین نمایش tooltip مسدود نشده باشد.
• onClick = coroutineScope.launch { tooltipState.show() } } یک کوروتین را برای نمایش دستی tooltip با استفاده از tooltipState.show اجرا می‌کند.
• پارامتر action امکان اضافه کردن عناصر تعاملی به یک tooltip، مانند یک دکمه، را فراهم می‌کند.
• پارامتر caretSize اندازه فلش tooltip را تغییر می‌دهد.

نتیجه

این مثال موارد زیر را تولید می‌کند:

شکل ۴. یک راهنمای ابزار سفارشی غنی با عملکرد رد کردن که به یک آیکون دوربین متصل است.

منابع اضافی

• طراحی متریال: نکات راهنما