تلميح

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

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

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

يمكنك استخدام العنصر القابل للإنشاء 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)
                        }
                    }
                },
                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 حجم سهم تلميح الأداة.

النتيجة

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

مراجع إضافية

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