نص النمط

تتضمّن العناصر القابلة للتجميع 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.

تحذير: إنّ الاستخدام الحالي لواجهة برمجة التطبيقات Brush API في TextStyle هو تجريبي. يمكن أن تتغيّر واجهات برمجة التطبيقات التجريبية في المستقبل.

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

اضبط النص باستخدام فرشاة مدمجة في 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. استخدام مَعلمة alpha في buildAnnotatedString وSpanStyle، بالإضافة إلى linearGradient لإضافة مستوى شفافية إلى جزء من النص

مصادر إضافية

للحصول على أمثلة إضافية على التخصيص، يُرجى الاطّلاع على منشور المدوّنة تحسين ميزة "إنشاء نص تلوينه". إذا كنت مهتمًا بمعرفة المزيد عن كيفية دمج Brush مع واجهة برمجة التطبيقات Animations API، يمكنك الاطّلاع على مقالة تلوين النص باستخدام فرشاة متحركة في أداة "الإنشاء".

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

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