نص النمط

تتضمّن الدالة البرمجية القابلة للإنشاء 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 مع قائمة محدّدة من الألوان

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

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

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

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

تنسيق إضافي باستخدام 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

تعتيم جزء من النص

لضبط درجة التعتيم لجزء معيّن من النص، استخدِم SpanStyle's المَعلمة الاختيارية alpha استخدِم الفرشاة نفسها لكلا الجزأين من النص، وغيِّر المَعلمة alpha في الجزء المقابل. في عينة التعليمات البرمجية، يظهر الجزء الأول من النص بنصف درجة التعتيم (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 والمَعلمة alpha في 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
• إتاحة روابط متعدّدة في سلسلة نصية واحدة