تلميح

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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

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

النتيجة

يعرض هذا المثال نصيحة توضيحية عادية فوق رمز:

عرض تلميح غني

استخدِم نصائح توضيحية غنية لتوفير سياق إضافي عن عنصر واجهة المستخدم. ينشئ هذا المثال تلميحًا توضيحيًا غنيًا متعدّد الأسطر يتضمّن عنوانًا مرتبطًا بعلامة 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، ويتم عرض 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)
                        }
                    }
                },
                caretSize = DpSize(32.dp, 16.dp)
            ) {
                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 على تعديل حجم سهم التلميح.

النتيجة

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

مراجع إضافية

• تصميم المواد: نصائح التلميح