تلميح

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

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

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

يمكنك استخدام العنصر القابل للإنشاء 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: تلميحات الأدوات