تلميح

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

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

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

يمكنك استخدام الدالة المركّبة 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)
                        }
                    }
                },
            ) {
                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 حجم سهم تلميح الأداة.

النتيجة

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

مراجع إضافية

• ‫Material Design: تلميحات الأدوات