نص النمط

تتضمّن العناصر القابلة للتجميع من النوع 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، ما يعادل النمط المضمّن مع نطاق 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" كرابط قابل للنقر، ويتم تصميمه باللون الأزرق ويُسطَّر ويُكتب مائلًا:

تفعيل التنسيق المتقدّم باستخدام 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

ولا تقتصر على استخدام هذا المخطط اللوني أو نمط التلوين المحدّد. على الرغم من أنّنا قدمنا مثالاً بسيطًا للتمييز، يمكنك استخدام أيّ من الفرش المدمجة أو حتى 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

التعتيم في نطاق نصي

لضبط مستوى الشفافية لجزء معيّن من النص، استخدِم المَعلمة 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

تطبيق تأثير المظلة على النص

يمكنك تطبيق المُعدِّل 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 المُطبَّق على النص

مصادر إضافية

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