تنسيق إدخال النص المنسَّق

ملاحظة: تتوفّر واجهات برمجة التطبيقات التي تمت مناقشتها في هذه الصفحة بدءًا من الإصدار 1.12.0 من Compose Foundation والإصدار 1.5.0-alpha28 من Material 3. يتم حفظ الأنماط واستعادتها عند إجراء تغييرات على الإعدادات وعند إيقاف العملية نهائيًا، وذلك بدءًا من الإصدار 1.13.0-alpha01 من Compose Foundation.

يتيح إدخال النص المنسَّق للمستخدمين تنسيق ما يكتبونه، بما في ذلك جعل كلمة غامقة أو إضافة عنوان أو محاذاة فقرة أو إدراج @mention مميّز. في Compose، يمكنك إنشاء ذلك فوق حقول النص المستندة إلى الحالة (BasicTextField وTextField). تظهر الأنماط في TextFieldState إلى جانب النص، لذا تظلّ متوفّرة بعد التعديلات وتغييرات الاختيار وإعادة الإنشاء، وتظلّ متزامنة أثناء كتابة المستخدم وحذفه ولصقه.

توضّح هذه الصفحة كيفية تطبيق الأنماط وتعديلها وطلبها واستخراجها وإزالتها في TextFieldState باستخدام TextFieldBuffer، وكيفية تشغيل شريط أدوات التنسيق من TextFieldState.textStyles.

ملاحظة: لتطبيق تنسيق مرئي فقط لا يتم حفظه في TextFieldState، مثل تمييز البنية أو تنسيق رقم الهاتف، يمكنك استدعاء addStyle داخل OutputTransformation. يتم تفعيل نمط النص المنسَّق في TextFieldState.edit وInputTransformation تلقائيًا في Compose Foundation 1.12.0 من خلال ComposeFoundationFlags.isBasicTextFieldStyledTextEnabled. لمزيد من المعلومات حول التنسيق المرئي فقط، يُرجى الاطّلاع على تنسيق الإدخال قبل عرضه.

تطبيق أنماط الفقرات والأنماط المضمّنة

يمكنك تطبيق التنسيق على مستوى الحرف والفقرة داخل أي نطاق استقبال TextFieldBuffer، بما في ذلك TextFieldState.edit وInputTransformation.transformInput وOutputTransformation.transformOutput.

التحكّم في توسيع الحدود باستخدام ExpandPolicy

عند استدعاء addStyle، يمكنك تمرير ExpandPolicy لتحديد سلوك النطاق المنسَّق عندما يُدرج المستخدم أحرفًا جديدة مباشرةً عند حدوده start أو end:

• Insertion inside (start, end): يوسّع هذا الخيار دائمًا النطاق المنسَّق.
• الإدراج قبل start: يؤدي دائمًا إلى إزاحة كل من start وend إلى اليمين.
• الإدراج مباشرةً في start أو end: يتم التحكّم فيه من خلال ExpandPolicy الذي تحدّده.

يوضّح الجدول التالي خيارات ExpandPolicy المتاحة وحالات استخدامها الشائعة:

السياسة	سلوك الحدود	حالات الاستخدام المقترَحة	مثال
ExpandPolicy.InsideOnly	يظل النص المكتوب في start أو end خارج النطاق المنسَّق.	الرموز المميزة المنفصلة، مثل @mentions أو #hashtags أو الأقراص في الخلفية، حيث لا يجب أن تكتسب الكتابة بجانب العلامة لون خلفية العلامة.
ExpandPolicy.AtStart	يأخذ النص المكتوب في start النمط، ويظل النص المكتوب في end بدون نمط.	يجب أن يعتمد النص المكتوب مباشرةً أمام النص المنسَّق التنسيق نفسه أيضًا.
ExpandPolicy.AtEnd	يأخذ النص المكتوب في end النمط، ويظل النص المكتوب في start بدون نمط.	الكتابة العادية في محرِّر النصوص المنسّقة، حيث يؤدي الاستمرار في الكتابة بعد كلمة غامقة أو مائلة إلى مواصلة هذا التنسيق.
ExpandPolicy.AtBoth	يؤدي النص المكتوب في start أو end إلى توسيع النطاق واكتساب النمط.	مقتطفات نشطة أو مجموعات منسَّقة مستمرة يجب أن تتوسّع من أيّ من الحواف

تطبيق تنسيق الأحرف باستخدام SpanStyle

استخدِم addStyle مع SpanStyle لتطبيق تنسيق على مستوى الأحرف، مثل لون النص أو تمييز الخلفية أو FontWeight أو FontStyle أو وضع خط تحت TextRange معيّن في المخزن المؤقت.

السلوكيات الرئيسية لنطاقات SpanStyle

• ترتيب الطبقات: يتم تطبيق الأنماط بالترتيب الذي تضيفها به إلى المخزن المؤقت. إذا تم ضبط السمة نفسها بقيم مختلفة في نطاقات SpanStyle متعددة متداخلة، سيتم عرض النمط الذي تمت إضافته لاحقًا في الأعلى.
• متطلبات النطاق غير الفارغ: يجب تمرير نطاق غير مصغّر حيث start < end. إنّ استدعاء addStyle على تحديد مصغّر بطول 0 ليس له أي تأثير، ويؤدي تمرير فهارس معكوسة أو خارج الحدود إلى ظهور IllegalArgumentException.

ملاحظة: بما أنّ addStyle لا يؤثر في النص المحدّد الذي تم تصغيره، لا يمكن تنسيق أي نص عند الضغط على زر "غامق" باستخدام المؤشر فقط. لجعل الأحرف المكتوبة التالية غامقة، تتبَّع SpanStyle في انتظار المراجعة في عنصر الاحتفاظ بالحالة وطبِّقه على كل نطاق جديد في changes داخل InputTransformation، كما هو موضّح في المثال التالي.

TextField(
    state = rememberTextFieldState(),
    inputTransformation = InputTransformation {
        for (i in 0 until changes.changeCount) {
            val range = changes.getRange(i)
            if (!range.collapsed) {
                addStyle(
                    spanStyle = SpanStyle(
                        fontWeight = FontWeight.ExtraBold,
                        fontStyle = FontStyle.Italic,
                        color = Color.Red,
                    ),
                    range = range,
                    expandPolicy = ExpandPolicy.AtEnd
                )
            }
        }
    }
)
RichTextInput.kt

الشكل 1. تطبيق تنسيق أحمر غامق ومائل على البيانات التي أدخلها المستخدم ديناميكيًا

تطبيق تنسيق الفقرة باستخدام ParagraphStyle

استخدِم addStyle مع ParagraphStyle لتطبيق تنسيق هيكلي على مستوى الكتلة، مثل textAlign أو lineHeight أو textDirection أو textIndent على نطاق فقرة.

fun setParagraphAlignment(state: TextFieldState, alignment: TextAlign) {
    val targetRange = if (state.selection.collapsed) {
        TextRange(0, state.text.length)
    } else {
        state.selection
    }
    if (targetRange.collapsed) return
    state.edit {
        // 1. Remove existing paragraph styles in this range
        getParagraphStyles(targetRange).forEach { removeStyle(it) }
        // 2. Apply the new paragraph alignment
        addStyle(
            paragraphStyle = ParagraphStyle(textAlign = alignment),
            range = targetRange,
            expandPolicy = ExpandPolicy.InsideOnly
        )
    }
}
RichTextInput.kt

الشكل 2. تبديل محاذاة الفقرة بين البداية والوسط والنهاية باستخدام ParagraphStyle

تنبيه: يجب ألا تتداخل نطاقات ParagraphStyle في Compose بشكل صارم أو أن تكون متداخلة بالكامل. التداخلات الجزئية مثل [0, 10) و[5, 15) غير صالحة وتتسبب في ظهور IllegalArgumentException عند قياس التنسيق. يجب دائمًا إزالة نطاقات ParagraphStyle الحالية أو تعديلها قبل تطبيق نطاق جديد على الفقرة نفسها.

أخطاء يجب تجنُّبها في ParagraphStyle

نظرًا لأن ParagraphStyle ينطبق على مجموعات كاملة من النص، تجنب استخدامه في السيناريوهات التالية:

• التوسيع إلى الفقرات المجاورة: اضبط ExpandPolicy بعناية حتى لا تتداخل نطاقات ParagraphStyle المجاورة بعد تعديلات المستخدم. على سبيل المثال، إذا كان [0, 5) يستخدم ExpandPolicy.AtEnd و[5, 10) يستخدم ExpandPolicy.AtStart، يؤدي إدراج نص في الفهرس 5 إلى توسيع كلا النمطين إلى تداخل ويؤدي إلى ظهور IllegalArgumentException.
• تداخل نطاقات ParagraphStyle: على الرغم من أنّ النطاقات المتداخلة بالكامل (مثل [0, 10) و[2, 8)) صالحة في AnnotatedString، تجنَّب تداخل نطاقات ParagraphStyle في حقل نصي. يقسّم التنسيق النطاقات المتداخلة إلى فقرات منفصلة، ويمكن أن تؤدي التعديلات اللاحقة إلى تحويل النطاقات المتداخلة عن غير قصد إلى تداخل جزئي.

ملاحظة: في Compose 1.12.0، تعمل حدود ParagraphStyle كفواصل للفقرات (تطابق سلوك AnnotatedString الثابت في Text). يمكن أن يؤدي تطبيق ParagraphStyle على نطاق فرعي من فقرة أو بجوار حرف سطر جديد مباشرةً (\n) إلى إدراج فاصل أسطر مرئي إضافي. عند تنسيق نص متعدد الفقرات، يجب محاذاة نطاق ParagraphStyle مع حدود الفقرة الكاملة.

تعديل نمط في مكانه باستخدام TrackedRange

يؤدي استدعاء addStyle باستخدام TextRange وExpandPolicy إلى عرض مؤشر TrackedRange، والذي يمكن أن يكون TrackedRange<SpanStyle> أو TrackedRange<ParagraphStyle>. ‫TrackedRange هو مرجع ديناميكي لفاصل نمط في TextFieldBuffer يتم تعديله تلقائيًا وإزاحة الأحرف start وend عند إدراج النص أو حذفه أو استبداله حوله.

قابلية التغيير في المكان

ليس عليك استدعاء removeStyle وaddStyle لتعديل نمط حالي أو ضبط حدوده. داخل نطاق TextFieldBuffer، يوفّر TrackedRange خصائص الإضافة التي تعدّل الفاصل الزمني في مكانه مع الحفاظ على ترتيب الطبقات الأصلي بالنسبة إلى الأنماط الأخرى:

• TrackedRange<SpanStyle>.spanStyle: يقرأ حمولة SpanStyle أو يستبدلها في مكانها على TrackedRange<SpanStyle>.
• ‫TrackedRange<ParagraphStyle>.paragraphStyle: لقراءة حمولة ParagraphStyle أو استبدالها في TrackedRange<ParagraphStyle>
• ‫TrackedRange<*>.textRange: لقراءة حدود TextRange الحالية أو تعديلها في مكانها يؤدي ضبط نطاق مطوي أو معكوس أو خارج الحدود إلى عرض IllegalArgumentException.
• ‫TrackedRange<*>.expandPolicy: لقراءة ExpandPolicy أو تعديله في مكانه
• ‫TrackedRange<*>.isValid: تعرض true إذا كان الفاصل الزمني للنمط لا يزال نشطًا في المخزن المؤقت، أو false إذا تسببت التعديلات في تقليص طوله إلى 0 أو إذا تمت إزالته.

// Trim an existing bold span in place when the selection overlaps one edge
val range = style.textRange
if (range.start < selection.min && range.end <= selection.max) {
    // Selection covers the end of the span - shrink end boundary in place
    style.textRange = TextRange(range.start, selection.min)
} else if (range.start >= selection.min && range.end > selection.max) {
    // Selection covers the start of the span - shrink start boundary in place
    style.textRange = TextRange(selection.max, range.end)
}
RichTextInput.kt

قواعد حصر النطاق ومراحل النشاط

يُرجى مراعاة قواعد النطاق ومراحل النشاط التالية عند العمل مع مثيلات TrackedRange:

• محصورة في TextFieldBuffer: لا تتوفّر سمات الإضافة TrackedRange إلا ضمن نطاق TextFieldBuffer حيث تم إنشاء الاسم المعرِّف أو الاستعلام عنه.
• التقليص التلقائي عند التصغير: إذا أدّت تعديلات المستخدم إلى حذف جميع الأحرف التي يغطيها TrackedRange، يتقلّص طوله إلى 0، وتُرجع isValid القيمة false، وتتم إزالة النمط من المخزن المؤقت.

تنبيه: لا تخزِّن مثيلات TrackedRange في سمات ViewModel طويلة الأمد أو عناصر الاحتفاظ بالحالة الخارجية. يرتبط TrackedRange بجلسة تعديل واحدة في TextFieldBuffer، ولا يتضمّن أي خصائص يمكن الوصول إليها خارج هذه المجموعة، ويصبح غير صالح بشكل دائم إذا تم حذف النطاق أو التراجع عنه أو استعادته. للاطّلاع على الأنماط خارج مجموعة التعديل، يُرجى قراءة TextFieldState.textStyles بدلاً من ذلك.

الاستعلام عن الأنماط وإزالتها

توفّر أداة Compose طريقتَين لفحص الأنماط النشطة، وذلك حسب ما إذا كنت تغيّر حالة المخزن المؤقت أو حالة القراءة لواجهة المستخدم:

• داخل كتلة TextFieldBuffer: يمكنك استدعاء getSpanStyles وgetParagraphStyles مباشرةً على جهاز استقبال TextFieldBuffer للحصول على مؤشرات TrackedRange قابلة للتغيير.
• خارج مجموعة التعديل: يمكنك قراءة TextFieldState.textStyles التي تعرض قوائم AnnotatedString.Range غير قابلة للتغيير تعكس الحالة النهائية.

تنبيه: لا تستعلم عن state.textStyles داخل كتلة state.edit. state.textStyles يعكس فقط الحالة الملتزم بها قبل جلسة التعديل ولا يتضمن تغييرات المخزن المؤقت الجارية.

الاستعلام عن الأنماط المتقاطعة في TextFieldBuffer

تعرض الدالتان TextFieldBuffer.getSpanStyles وTextFieldBuffer.getParagraphStyles جميع مثيلات TrackedRange التي تتقاطع مع TextRange المحدّد، ويتم ترتيبها حسب وقت إضافتها إلى المخزن المؤقت.

على سبيل المثال، يمكنك الاستعلام عن getSpanStyles(selection) داخل state.edit لفحص أو تعديل الأنماط التي تغطي اختيار المستخدم الحالي:

state.edit {
    if (selection.collapsed) return@edit
    // Query all bold spans that overlap with the current selection
    val boldStyles: List<TrackedRange<SpanStyle>> = getSpanStyles(selection).filter {
        it.spanStyle.fontWeight == FontWeight.Bold
    }
    // ...
}
RichTextInput.kt

تستخدم فواصل الأنماط نطاقًا رياضيًا شبه مفتوح [start, end). يعتمد عرض نمط ملامس على ما إذا كنت تستعلم عن تحديد أو نقطة مؤشر واحدة:

• بالنسبة إلى التحديد غير الفارغ [start, end):
  • النتيجة: أي نمط يتداخل مع نطاق الاختيار أو يتضمّنه أو يقع داخله على سبيل المثال، يتطابق طلب البحث [5, 15) مع [0, 20) أو [8, 12) أو [0, 10).
  • الأنماط التي لا يتم عرضها: الأنماط التي تلامس حواف الحدود الخارجية فقط بدون تداخل الأحرف على سبيل المثال، يستبعد طلب البحث [5, 15) [0, 5) و[15, 25).
• بالنسبة إلى المؤشر المصغّر [index, index]:
  • النتيجة: أي نمط يحتوي على المؤشر أو يبدأ من موضع المؤشر على سبيل المثال، يتطابق المؤشر في 10 مع [0, 20) و[10, 20).
  • عدم الإرجاع (قاعدة نهاية اللمس): أي نمط ينتهي عند موضع المؤشر على سبيل المثال، يستبعد المؤشر عند 10 السمة [0, 10).

ملاحظة: يقيّم getSpanStyles وgetParagraphStyles حدود الفاصل الزمني شبه المفتوح [start, end) ويتجاهلان ExpandPolicy. لفحص نمط يلامس الحد النهائي عند مؤشر منهار (index > 0)، يمكنك الاستعلام عن نافذة الحرف السابق بدلاً من ذلك. بما أنّ TextRange تحتسب وحدات ترميز UTF-16 ويمكن أن يمتد رمز إيموجي واحد على عدة وحدات، يتم احتساب بداية النافذة باستخدام BreakIterator.getCharacterInstance() بدلاً من index - 1 لكي لا يبدأ طلب البحث في منتصف حرف.

إزالة الأنماط أو تبديلها باستخدام removeStyle

مرِّر مؤشر TrackedRange إلى removeStyle لحذف الفاصل الزمني المحدّد للنمط من TextFieldBuffer.

تعرض الدالة removeStyle القيمة true إذا تم العثور على TrackedRange وإزالته، أو false إذا سبق أن تمت إزالته أو كان ينتمي إلى مخزن مؤقت مختلف. وتزيل فقط الاسم المعرِّف المستهدَف على TrackedRange، مع ترك الأنماط المتداخلة الأخرى كما هي.

fun toggleBold(state: TextFieldState) {
    state.edit {
        if (selection.collapsed) return@edit
        // Query all bold spans that overlap with the current selection
        val boldStyles: List<TrackedRange<SpanStyle>> = getSpanStyles(selection).filter {
            it.spanStyle.fontWeight == FontWeight.Bold
        }
        if (boldStyles.isNotEmpty()) {
            // Remove or trim existing bold spans covering the selection
            for (style in boldStyles) {
                val range = style.textRange
                if (range.start >= selection.min && range.end <= selection.max) {
                    removeStyle(style)
                } else if (range.start < selection.min && range.end > selection.max) {
                    val oldEnd = range.end
                    style.textRange = TextRange(range.start, selection.min)
                    addStyle(
                        spanStyle = SpanStyle(fontWeight = FontWeight.Bold),
                        range = TextRange(selection.max, oldEnd),
                        expandPolicy = ExpandPolicy.AtEnd
                    )
                } else if (range.start < selection.min) {
                    style.textRange = TextRange(range.start, selection.min)
                } else {
                    style.textRange = TextRange(selection.max, range.end)
                }
            }
        } else {
            // No bold spans intersect the selection - apply bold
            addStyle(
                spanStyle = SpanStyle(fontWeight = FontWeight.Bold),
                range = selection,
                expandPolicy = ExpandPolicy.AtEnd
            )
        }
    }
}
RichTextInput.kt

الشكل 3. التبديل بين جعل النص غامقًا أو عاديًا

استخراج النص المنسَّق أو تسلسله

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

تعرض الدالتان state.textStyles.getSpanStyles وstate.textStyles.getParagraphStyles السمتَين List<AnnotatedString.Range<SpanStyle>> وList<AnnotatedString.Range<ParagraphStyle>>، ويمكنك تمريرهما مباشرةً إلى الدالة الإنشائية AnnotatedString:

fun TextFieldState.toAnnotatedString(): AnnotatedString {
    val fullRange = TextRange(0, text.length)
    return AnnotatedString(
        text = text.toString(),
        spanStyles = textStyles.getSpanStyles(fullRange),
        paragraphStyles = textStyles.getParagraphStyles(fullRange)
    )
}
RichTextInput.kt

مثال كامل في Jetchat

للاطّلاع على عملية تنفيذ كاملة تجمع بين أنماط الأحرف المضمّنة (الخط الغامق والمائل والمسطر والمشطوب واللون)، يمكنك الاطّلاع على نموذج Jetchat على GitHub:

• ‫RichTextState.kt: يدمج طلبات البحث عن نمط TextFieldState، وتبديل الامتداد، والاقتطاع أو التقسيم عبر حدود الاختيار، والمزيد.
• ‫UserInput.kt: يربط RichTextState بشريط أدوات تنسيق النص المنسّق وحقل إدخال الرسالة.

الشكل 4. تعديل النصوص المنسّقة في Jetchat