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

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

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

سطح API

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

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

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

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

@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 یک تابع lambda است که محتوای راهنمای ابزار را با استفاده از PlainTooltip composable تعریف می کند.
  • Text(plainTooltipText) متن داخل راهنمای ابزار را نمایش می دهد.
  • tooltipState وضعیت راهنمای ابزار را کنترل می کند.
• IconButton یک دکمه قابل کلیک با یک نماد ایجاد می کند.
  • Icon(...) یک نماد قلب را در داخل دکمه نمایش می دهد.
  • هنگامی که کاربر با IconButton تعامل می کند، TooltipBox راهنمای ابزار را با متن "افزودن به موارد دلخواه" نشان می دهد. بسته به دستگاه، کاربران می توانند راهنمای ابزار را به روش های زیر فعال کنند:
  • با مکان نما روی نماد حرکت کنید
  • فشردن طولانی نماد روی دستگاه تلفن همراه

نتیجه

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

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

از یک راهنمای ابزار غنی برای ارائه زمینه اضافی در مورد یک عنصر UI استفاده کنید. این مثال یک راهنمای ابزار غنی چند خطی با عنوانی ایجاد می کند که به یک 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 نشان می دهد که راهنمای ابزار باید نشان داده شود، راهنمای ابزار Lambda اجرا می شود، و 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)
                        }
                    }
                },
                caretSize = DpSize(32.dp, 16.dp)
            ) {
                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() } } یک coroutine را برای نمایش دستی راهنمای ابزار با استفاده از tooltipState.show راه اندازی می کند.
• پارامتر action امکان افزودن عناصر تعاملی را به یک راهنمای ابزار، مانند یک دکمه، می دهد.
• پارامتر caretSize اندازه پیکان راهنمای ابزار را تغییر می دهد.

نتیجه

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

منابع اضافی

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