تلميح

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

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

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

يمكنك استخدام الدالة المركّبة 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، يتم عرضه لمدة ثانية واحدة تقريبًا. يمكنك إغلاق هذا التلميح من خلال النقر في أي مكان آخر على الشاشة أو باستخدام زر الإغلاق.
• عند تنفيذ إجراء الإغلاق، يشغّل النظام دالة coroutine لاستدعاء tooltipState.dismiss. يتحقّق هذا الاختبار من عدم حظر تنفيذ الإجراء أثناء عرض التلميح.
• يطلق onClick = coroutineScope.launch { tooltipState.show() } } روتينًا مشتركًا لعرض تلميح الشاشة يدويًا باستخدام tooltipState.show.
• تتيح المَعلمة action إضافة عناصر تفاعلية إلى تلميح، مثل زر.
• تعدّل المَعلمة caretSize حجم سهم تلميح الشاشة.

النتيجة

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

مراجع إضافية

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