تلميح

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

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

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

يمكنك استخدام العنصر القابل للإنشاء 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 هي دالة لامدا تحدّد محتوى التلميح باستخدام العنصر القابل للإنشاء 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 إلى ضرورة عرض التلميح، يتم تنفيذ دالة لامدا الخاصة بالتلميح، ويعرض 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 حجم سهم التلميح.

النتيجة

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

مراجع إضافية

• نظام التصميم المتعدد الأبعاد: التلميحات