تلميح

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

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

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

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