نص النمط

تحتوي الدالة المركّبة Text على مَعلمات اختيارية متعددة لتنسيق محتواها. في ما يلي، أدرجنا المَعلمات التي تغطي حالات الاستخدام الأكثر شيوعًا مع النص. للاطّلاع على جميع مَعلمات Text، يُرجى مراجعة الرمز المصدر لـ Compose Text.

عندما تضبط إحدى هذه المَعلمات، فإنّك تطبّق النمط على قيمة النص بالكامل. إذا كنت بحاجة إلى تطبيق أنماط متعددة ضمن السطر أو الفقرات نفسها، يُرجى الاطّلاع على القسم الخاص بالأنماط المضمّنة المتعددة.

أنماط النص الشائعة

توضّح الأقسام التالية الطرق الشائعة لتنسيق النص.

تغيير لون النص

@Composable
fun BlueText() {
    Text("Hello World", color = Color.Blue)
}
TextSnippets.kt

تغيير حجم النص

@Composable
fun BigText() {
    Text("Hello World", fontSize = 30.sp)
}
TextSnippets.kt

جعل النص مائلاً

استخدِم المَعلمة fontStyle لجعل النص مائلاً (أو اضبط FontStyle أخرى).

@Composable
fun ItalicText() {
    Text("Hello World", fontStyle = FontStyle.Italic)
}
TextSnippets.kt

تغميق النص

استخدِم المَعلمة fontWeight لتغميق النص (أو اضبط FontWeight أخرى).

@Composable
fun BoldText() {
    Text("Hello World", fontWeight = FontWeight.Bold)
}
TextSnippets.kt

إضافة ظل

تتيح لك المَعلمة style ضبط عنصر من النوع TextStyle وإعداد مَعلمات متعددة، مثل الظل. Shadow يتلقّى لونًا للظل، أو الإزاحة، أو مكان وجوده بالنسبة إلى Text ونصف قطر التمويه الذي يحدّد مدى تمويهه.

@Composable
fun TextShadow() {
    val offset = Offset(5.0f, 10.0f)
    Text(
        text = "Hello world!",
        style = TextStyle(
            fontSize = 24.sp,
            shadow = Shadow(
                color = Color.Blue, offset = offset, blurRadius = 3f
            )
        )
    )
}
TextSnippets.kt

إضافة أنماط متعددة في النص

لضبط أنماط مختلفة ضمن الدالة المركّبة Text نفسها، استخدِم AnnotatedString، وهي سلسلة يمكن إضافة تعليقات توضيحية إليها باستخدام أنماط التعليقات التوضيحية العشوائية.

‫AnnotatedString هي فئة بيانات تحتوي على ما يلي:

• قيمة Text
• List من SpanStyleRange، أي ما يعادل النمط المضمّن مع نطاق الموضع ضمن قيمة النص
• ‫List من ParagraphStyleRange، يحدّد محاذاة النص واتجاهه وارتفاع السطر ونمط المسافة البادئة للنص

يُستخدم TextStyle في الدالة المركّبة Text، بينما يُستخدم SpanStyle وParagraphStyle في AnnotatedString. لمزيد من المعلومات حول الأنماط المتعددة في فقرة، يُرجى الاطّلاع على إضافة أنماط متعددة في فقرة.

يحتوي AnnotatedString على أداة إنشاء تمنع أخطاء الكتابة لتسهيل إنشاء: buildAnnotatedString.

@Composable
fun MultipleStylesInText() {
    Text(
        buildAnnotatedString {
            withStyle(style = SpanStyle(color = Color.Blue)) {
                append("H")
            }
            append("ello ")

            withStyle(style = SpanStyle(fontWeight = FontWeight.Bold, color = Color.Red)) {
                append("W")
            }
            append("orld")
        }
    )
}
TextSnippets.kt

عرض HTML مع روابط في النص

استخدِم AnnotatedString.fromHtml() لعرض نص بتنسيق HTML مع روابط قابلة للنقر في تطبيق Jetpack Compose. تحوّل هذه الدالة سلسلة تحتوي على علامات HTML إلى AnnotatedString، ما يتيح تنسيق الروابط والتعامل معها.

مثال: HTML مع رابط منسَّق

يعرض هذا المقتطف نصًا بتنسيق HTML مع رابط، مع تطبيق نمط معين على الرابط:

@Composable
fun AnnotatedHtmlStringWithLink(
    modifier: Modifier = Modifier,
    htmlText: String = """
       <h1>Jetpack Compose</h1>
       <p>
           Build <b>better apps</b> faster with <a href="https://www.android.com">Jetpack Compose</a>
       </p>
    """.trimIndent()
) {
    Text(
        AnnotatedString.fromHtml(
            htmlText,
            linkStyles = TextLinkStyles(
                style = SpanStyle(
                    textDecoration = TextDecoration.Underline,
                    fontStyle = FontStyle.Italic,
                    color = Color.Blue
                )
            )
        ),
        modifier
    )
}
HtmlStyling.kt

نقاط رئيسية حول الرمز

• تحوّل الدالة AnnotatedString.fromHtml() السلسلة htmlText إلى AnnotatedString. تخصّص المَعلمة linkStyles مظهر الرابط.

• يحدّد TextLinkStyles نمط الروابط ضمن ملف HTML. يضبط SpanStyle زخرفة النص ونمط الخط ولون الروابط.

• تعرض الدالة المركّبة Text القيمة الناتجة AnnotatedString.

النتيجة

يتيح هذا المقتطف تفعيل "Jetpack Compose" كرابط قابل للنقر، ومصمَّم باللون الأزرق، ومسطّر ومائل:

الشكل 2. عنوان وفقرة، حيث تكون عبارة "Jetpack Compose" في الفقرة عبارة عن رابط منسَّق يمكن النقر عليه

تفعيل ميزة "الأنماط المتقدّمة" باستخدام Brush

لتفعيل نمط نص أكثر تقدّمًا، يمكنك استخدام واجهة برمجة التطبيقات Brush مع TextStyle وSpanStyle. في أي مكان تستخدم فيه عادةً TextStyle أو SpanStyle، يمكنك الآن أيضًا استخدام Brush.

استخدام فرشاة لتنسيق النص

يمكنك ضبط النص باستخدام فرشاة مدمجة في "TextStyle". على سبيل المثال، يمكنك ضبط فرشاة linearGradient على النص على النحو التالي:

val gradientColors = listOf(Cyan, LightBlue, Purple /*...*/)

Text(
    text = text,
    style = TextStyle(
        brush = Brush.linearGradient(
            colors = gradientColors
        )
    )
)
TextSnippets.kt

الشكل 3: باستخدام دالة linearGradient في Brush API مع قائمة محدّدة من الألوان

أنت لست مقيدًا بنظام الألوان هذا أو نمط التلوين هذا. على الرغم من أنّنا قدّمنا مثالاً بسيطًا لتسليط الضوء على النص، يمكنك استخدام أي من الفُرَش المضمّنة أو حتى SolidColor لتحسين النص.

عمليات التكامل

بما أنّه يمكنك استخدام Brush مع كل من TextStyle وSpanStyle، فإنّ عملية الدمج مع TextField وbuildAnnotatedString تكون سلسة.

لمزيد من المعلومات حول استخدام واجهة برمجة التطبيقات Brush API ضمن TextField، يُرجى الاطّلاع على تنسيق الإدخال باستخدام Brush API.

تنسيق إضافي باستخدام SpanStyle

تطبيق فرشاة على جزء من النص

إذا أردت تطبيق فرشاة على أجزاء من النص فقط، استخدِم buildAnnotatedString وواجهة برمجة التطبيقات SpanStyle، بالإضافة إلى الفرشاة والتدرج اللوني الذي تختاره.

Text(
    text = buildAnnotatedString {
        append("Do not allow people to dim your shine\n")
        withStyle(
            SpanStyle(
                brush = Brush.linearGradient(
                    colors = rainbowColors
                )
            )
        ) {
            append("because they are blinded.")
        }
        append("\nTell them to put some sunglasses on.")
    }
)
TextSnippets.kt

الشكل 4. يتم استخدام فرشاة تلقائية مع linearGradient كنمط لـ "Text".

درجة التعتيم في جزء من النص

لضبط عتامة جزء معيّن من النص، استخدِم المَعلمة الاختيارية alpha في SpanStyle. استخدِم الفرشاة نفسها لكلا الجزأين من النص، وغيِّر مَعلمة ألفا في النطاق المقابل. في عينة التعليمات البرمجية، يتم عرض الجزء الأول من النص بنصف درجة التعتيم (alpha =.5f)، بينما يتم عرض الجزء الثاني بدرجة التعتيم الكاملة (alpha = 1f).

val brush = Brush.linearGradient(colors = rainbowColors)

buildAnnotatedString {
    withStyle(
        SpanStyle(
            brush = brush, alpha = .5f
        )
    ) {
        append("Text in ")
    }
    withStyle(
        SpanStyle(
            brush = brush, alpha = 1f
        )
    ) {
        append("Compose ❤️")
    }
}
TextSnippets.kt

الشكل 5. استخدام مَعلمة ألفا في buildAnnotatedString وSpanStyle، بالإضافة إلى linearGradient لإضافة تعتيم إلى جزء من النص

تطبيق تأثير النص المتحرك على النص

يمكنك تطبيق المُعدِّل basicMarquee على أي دالة مركّبة لإنشاء تأثير تمرير متحرك. يحدث تأثير النص المتحرك إذا كان المحتوى واسعًا جدًا بحيث لا يتناسب مع القيود المتاحة. بشكل تلقائي، يتضمّن basicMarquee إعدادات معيّنة (مثل السرعة والتأخير الأولي)، ولكن يمكنك تعديل هذه المَعلمات لتخصيص التأثير.

ينفّذ المقتطف التالي تأثير شريط متحرك أساسي على دالة Text مركّبة:

@Composable
fun BasicMarqueeSample() {
    // Marquee only animates when the content doesn't fit in the max width.
    Column(Modifier.width(400.dp)) {
        Text(
            "Learn about why it's great to use Jetpack Compose",
            modifier = Modifier.basicMarquee(),
            fontSize = 50.sp
        )
    }
}
TextSnippets.kt

الشكل 6: تم تطبيق المُعدِّل basicMarquee على النص.

مراجع إضافية

• تحسين تلوين النص في Compose
• تلوين النص باستخدام فرشاة متحركة في Compose
• إتاحة روابط متعددة في سلسلة نصية واحدة