تلميح

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

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

الشكل 1. تلميح عادي (1) وتلميح غني بصريًا (2).

مساحة عرض واجهة برمجة التطبيقات

يمكنك استخدام الدالة المركّبة 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 تلميحًا يتضمّن النص "إضافة إلى المفضّلة". وبحسب الجهاز، يمكن للمستخدمين عرض التلميح بالطرق التالية:
  • تمرير مؤشر الماوس فوق الرمز
  • الضغط مع الاستمرار على الرمز على جهاز جوّال

النتيجة

ينتج هذا المثال تلميح أداة عاديًا أعلى الرمز:

الشكل 2. تلميح عادي يظهر عندما يمرّر المستخدم مؤشر الماوس فوق رمز القلب أو يضغط عليه مع الاستمرار

عرض تلميح تفاعلي

استخدِم تلميحًا منسّقًا لتقديم سياق إضافي حول عنصر في واجهة المستخدم. ينشئ هذا المثال تلميحًا متعدد الأسطر بتنسيق منسّق يتضمّن عنوانًا مرتبطًا بعنصر 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() معلومات تحديد المواضع لتلميحات الأدوات المنسّقة.

النتيجة

ينتج عن هذا المثال تلميح أداة غني بصريًا يتضمّن عنوانًا مرفقًا برمز معلومات:

الشكل 3. تلميح غني بصريًا يتضمّن عنوانًا ورمز معلومات

تخصيص تلميح غني

تعرض مقتطفة الرمز هذه تلميحًا منسقًا يتضمّن عنوانًا وإجراءات مخصّصة وسهمًا مخصّصًا يظهر فوق زر رمز الكاميرا:

@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 حجم سهم تلميح الأدوات.

النتيجة

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

الشكل 4. تلميح أداة غني مخصّص يتضمّن إجراء إغلاق مرتبطًا برمز كاميرا

مراجع إضافية

• ‫التصميم المتعدد الأبعاد: تلميحات الأدوات