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

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

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

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

می‌توانید از ترکیب‌پذیر 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 composable تعریف می‌کند.
  • 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 composable defines the tooltip's content, including the title and body text. 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 راه‌اندازی می‌کند. This verifies the action execution isn't blocked while the tooltip is displayed.
• onClick = coroutineScope.launch { tooltipState.show() } } یک روال همکار را برای نمایش دستی نکته‌ابزار بااستفاده از tooltipState.show راه‌اندازی می‌کند.
• پارامتر action امکان افزودن عناصر تعاملی به نکته‌ابزار را فراهم می‌کند، مثل دکمه.
• پارامتر caretSize اندازه پیکان نکته‌ابزار را تغییر می‌دهد.

نتیجه

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

منابع بیشتر

• طراحی مواد: نکته‌ابزارها