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

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

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

سطح میانای برنامه‌سازی کاربردی

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

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

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

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

@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 یک نکته‌ابزار با نوشتار «افزودن به موارد دلخواه» تولید می‌کند.
  • TooltipDefaults.rememberPlainTooltipPositionProvider() موقعیت پیش‌فرض را برای نکته‌ابزارهای ساده ارائه می‌دهد.
  • ‫tooltip تابع لامبدایی است که محتوای نکته‌ابزار را بااستفاده از عنصر ترکیبی PlainTooltip تعریف می‌کند.
  • Text(plainTooltipText) نوشتار را در نکته‌ابزار نمایش می‌دهد.
  • tooltipState وضعیت نکته‌ابزار را کنترل می‌کند.
• ‫IconButton دکمه‌ای کلیک‌کردنی با نماد ایجاد می‌کند.
  • Icon(...) نماد قلب را در دکمه نمایش می‌دهد.
  • وقتی کاربری با IconButton تعامل برقرار می‌کند، TooltipBox نکته‌ابزاری را با نوشتار «افزودن به موارد دلخواه» نشان می‌دهد. بسته به دستگاه، کاربران می‌توانند راهنمای ابزار را به روش‌های زیر راه‌اندازی کنند:
  • نگه داشتن مکان‌نما روی نماد
  • فشار طولانی روی نماد در دستگاه همراه

نتیجه

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

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

از راهنمای ابزار غنی برای ارائه زمینه اضافی درباره عنصر واسط کاربر استفاده کنید. این مثال نکته‌ابزار غنی چندخطی با عنوانی ایجاد می‌کند که به 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 نشان می‌دهد که نکته‌ابزار باید نمایش داده شود، لامبدای نکته‌ابزار اجرا می‌شود و TooltipBox RichTooltip را نمایش می‌دهد. TooltipBox به‌عنوان لنگر و محتوی برای هم محتوا و هم نکته‌ابزار عمل می‌کند.
  • در این مورد، محتوا یک عنصر IconButton است که رفتار کنش ضربه‌زدنی را ارائه می‌دهد. وقتی در هر جایی از محتوای TooltipBox فشار طولانی (در دستگاه‌های لمسی) یا نگه‌داشته شود (مانند اشاره‌گر موشواره)، ابزارنمایی نمایش داده می‌شود تا اطلاعات بیشتری نشان دهد.
• عنصر ترکیبی RichTooltip محتوای نکته‌ابزار را تعریف می‌کند، ازجمله عنوان و نوشتار اصلی. TooltipDefaults.rememberRichTooltipPositionProvider() اطلاعات جای‌گیری برای نکته‌ابزارهای غنی ارائه می‌دهد.

نتیجه

این مثال نکته‌ابزار غنی‌ای با عنوان پیوست‌شده به نماد اطلاعات تولید می‌کند:

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

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

@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 یک راهنمای ابزار با عنوان و کنش بستن نمایش می‌دهد.
• وقتی نکته‌ابزار فعال می‌شود، چه با فشار طولانی یا نگه داشتن نشانگر موشواره روی TooltipBox محتوا، نکته‌ابزار حدود یک ثانیه نمایش داده می‌شود. می‌توانید این نکته‌ابزار را با تک‌ضرب زدن در جای دیگری از صفحه‌نمایش یا بااستفاده از دکمه اقدام بستن ببندید.
• وقتی کنش بستن اجرا می‌شود، سیستم یک روال هم‌زمان راه‌اندازی می‌کند تا tooltipState.dismiss را فراخوانی کند. این کار تأیید می‌کند که اجرای کنش درحالی‌که نکته‌ابزار نمایش داده می‌شود مسدود نشود.
• ‫onClick = coroutineScope.launch { tooltipState.show() } } یک روال همکار برای نمایش دستی نکته‌ابزار بااستفاده از tooltipState.show راه‌اندازی می‌کند.
• پارامتر action امکان افزودن عناصر تعاملی به نکته‌ابزار را فراهم می‌کند، مثل دکمه.
• پارامتر caretSize اندازه پیکان ابزارک را تغییر می‌دهد.

نتیجه

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

منابع بیشتر

• طراحی سه‌بعدی: نکته‌ابزارها