تلميح

استخدِم نصائح التلميح لإضافة سياق إلى زر أو عنصر آخر من عناصر واجهة المستخدم. هناك نوعان من التلميح:

• نصائح بسيطة: لوصف عناصر أزرار الرموز أو الإجراءات التي تؤديها
• نصائح توضيحية غنية: يمكنك تقديم مزيد من التفاصيل، مثل وصف قيمة إحدى الميزات. يمكن أن تتضمّن أيضًا عنوانًا ورابطًا وأزرارًا اختيارية.

واجهة برمجة التطبيقات

يمكنك استخدام العنصر القابل للتجميع 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 هي دالة LAMBDA تحدّد محتوى التلميح باستخدام العنصر القابل للتجميع 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 إلى أنّه يجب عرض التلميح، يتم تنفيذ دالة التلميح 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() } } دالّة متعدّدة المهام لعرض التلميح يدويًا باستخدام tooltipState.show.
• تسمح المَعلمة action بإضافة عناصر تفاعلية إلى معلومات توضيحية، مثل زر.
• تعمل المَعلمة caretSize على تعديل حجم سهم التلميح.

النتيجة

ينتج عن هذا المثال ما يلي:

مراجع إضافية

• تصميم المواد: نصائح التلميح