TextInput — ما هو، إدخال النص وReact Native

ما هو TextInput في React Native

TextInput هو مكون React Native يسمح للمستخدمين بإدخال النص باستخدام لوحة مفاتيح الجهاز. وهو اللبنة الأساسية لنماذج التسجيل وأشرطة البحث وحقول إدخال الرسائل وأي سيناريوهات أخرى تتطلب إدخال المستخدم. على عكس تطوير الويب، حيث توجد أنواع منفصلة من input (text، email، password، search)، في React Native يتم تنفيذ جميع هذه المتغيرات من خلال مكون TextInput واحد مع خصائص مختلفة.

يدعم TextInput وضعين من التشغيل: مُتحكم به (يُدار عبر حالة React) وغير مُتحكم به (باستخدام ref). في الوضع المُتحكم به، يتم تخزين قيمة الحقل في حالة المكون ويتم تحديثها عبر callback onChangeText. يُوصى بهذا النهج لمعظم التطبيقات لأنه يوفر مصدرًا واحدًا للحقيقة ويبسط التحقق.

وفقًا لـ React Native Handling Text Input، 2024، يتكيف TextInput تلقائيًا مع المنصة: على iOS يستخدم UITextField الأصلي، على Android — EditText. وهذا يضمن التشغيل السليم للإكمال التلقائي والتصحيح التلقائي وقوائم النظام (قص/نسخ/لصق) دون تكوين إضافي.

خصائص TextInput وAPI

يوفر TextInput مجموعة واسعة من الخصائص للتحكم في الإدخال والمظهر والسلوك. تنقسم جميع الخصائص إلى عدة فئات: إدارة القيمة، نوع لوحة المفاتيح، التنسيق، الأحداث، وميزات خاصة بالمنصة.

خصائص إدارة القيمة

value — قيمة الحقل الحالية (للوضع المُتحكم به). onChangeText — callback يُستدعى عند كل تغيير في النص. placeholder — نص تلميح يظهر عندما يكون الحقل فارغًا. defaultValue — القيمة الأولية للوضع غير المُتحكم به. maxLength يحدد الحد الأقصى لعدد الأحرف التي يمكن للمستخدم إدخالها.

أحداث TextInput

يدعم المكون onFocus (الحقل تلقى التركيز)، onBlur (الحقل فقد التركيز)، onSubmitEditing (المستخدم ضغط Enter/Return)، onKeyPress (ضغطة مفتاح). يتم استدعاء حدث onEndEditing بعد انتهاء التحرير عند فقدان التركيز. تسمح هذه الـ callbacks بتنفيذ منطق معقد للتحقق من صحة البيانات وإرسال النماذج.

خصائص خاصة بالمنصة

على iOS: clearButtonMode (زر المسح)، keyboardAppearance (لوحة مفاتيح فاتحة/داكنة)، returnKeyType (نوع زر Return)، enablesReturnKeyAutomatically. على Android: textContentType (الإكمال التلقائي)، underlineColorAndroid، inlineImageLeft. secureTextEntry يعمل على كلتا المنصتين لإدخال كلمات المرور.

الإدخال المُتحكم به وغير المُتحكم به

في React Native، يمكن لـ TextInput العمل في وضعين. في الوضع المُتحكم به، يدير React قيمة الحقل: تمرر القيمة من الحالة وتحدّثها عبر onChangeText. في الوضع غير المُتحكم به، يقوم React فقط بتهيئة الحقل، ويتم تخزين القيمة الشبيهة بـ DOM داخل المكون الأصلي.

TextInput مُتحكم به

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

const LoginForm = () => {
    const [email, setEmail] = useState('');
    const [password, setPassword] = useState('');

    return (
        <View>
            <TextInput
                placeholder="Email"
                value={email}
                onChangeText={setEmail}
                keyboardType="email-address"
                autoCapitalize="none"
            />
            <TextInput
                placeholder="Password"
                value={password}
                onChangeText={setPassword}
                secureTextEntry
                maxLength={32}
            />
        </View>
    );
};

في هذا المثال، كلا الحقلين يستخدمان الوضع المُتحكم به. حقل البريد الإلكتروني لديه نوع لوحة مفاتيح email-address مع تعطيل الأحرف الكبيرة التلقائية. حقل كلمة المرور يستخدم secureTextEntry لإخفاء أحرف الإدخال ومحدد بـ 32 حرفًا عبر maxLength.

TextInput غير مُتحكم به

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

const SimpleSearch = () => {
    const inputRef = useRef(null);

    const handleSearch = () => {
        console.log(inputRef.current.value());
    };

    return (
        <TextInput
            ref={inputRef}
            placeholder="Search..."
            onSubmitEditing={handleSearch}
        />
    );
};

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

أنواع لوحة المفاتيح وميزات المنصة

يدعم TextInput أنواعًا مختلفة من لوحة المفاتيح التي تُكيّف التخطيط وفقًا لتنسيق الإدخال المتوقع. اختيار نوع لوحة المفاتيح الصحيح يحسن تجربة المستخدم ويقلل من أخطاء الإدخال على الأجهزة المحمولة.

على iOS، تتوفر أنواع إضافية: numbers-and-punctuation، twitter، web-search (مع بحث صوتي). على Android، يتوفر أيضًا visible-password (يظهر كلمة المرور). اختيار keyboardType الصحيح هو جانب مهم من تجربة المستخدم في تطبيق الجوال.

تشمل ميزات المنصة أيضًا autoCapitalize (الأحرف الكبيرة التلقائية للكلمة الأولى)، autoCorrect (التصحيح التلقائي)، spellCheck (التدقيق الإملائي)، textContentType (الإكمال التلقائي على iOS). تعمل هذه الخصائص بشكل مختلف على كل منصة وتتطلب اختبارًا.

أمثلة عملية مع TextInput

لنفكر في سيناريوهين حقيقيين: حقل متعدد الأسطر لإدخال الرسائل وحقل مع قناع إدخال رقم الهاتف. كلاهما يستخدم TextInput مع خصائص مختلفة لتحقيق السلوك المطلوب.

مثال 1: حقل متعدد الأسطر للرسالة

لإدخال نص طويل (تعليقات، أوصاف)، يتحول TextInput إلى الوضع متعدد الأسطر عبر الخاصية multiline. في هذا الوضع، ينمو الحقل رأسيًا ويدعم فواصل الأسطر.

const MessageInput = ({ onSend }) => {
    const [text, setText] = useState('');

    return (
        <TextInput
            style={styles.input}
            multiline
            numberOfLines={4}
            placeholder="Write a message..."
            value={text}
            onChangeText={setText}
            textAlignVertical="top"
        />
    );
};

الخاصية multiline تُفعّل الوضع متعدد الأسطر، numberOfLines تحدد الارتفاع الأولي بالأسطر. textAlignVertical: 'top' يحاذي النص إلى الأعلى (افتراضيًا، في Android، TextInput متعدد الأسطر يركز النص رأسيًا).

مثال 2: حقل بتنسيق رقم الهاتف

لإدخال رقم هاتف، غالبًا ما يكون التنسيق في الوقت الفعلي مطلوبًا. من خلال دمج onChangeText مع التعبيرات النمطية، يمكنك تنفيذ قناع إدخال.

const PhoneInput = () => {
    const [phone, setPhone] = useState('');

    const formatPhone = (text) => {
        const cleaned = text.replace(/\D/g, '');
        if (cleaned.length <= 11) {
            return cleaned.replace(
                /(\d{1})(\d{3})(\d{3})(\d{2})(\d{2})/,
                '+$1 ($2) $3 $4 $5'
            );
        }
        return cleaned;
    };

    return (
        <TextInput
            keyboardType="phone-pad"
            value={phone}
            onChangeText={(t) => setPhone(formatPhone(t))}
            placeholder="+7 (999) 123 45 67"
            maxLength={20}
        />
    );
};

تزيل وظيفة formatPhone جميع الأحرف غير الرقمية وتنسّق الرقم إلى تنسيق دولي قياسي. keyboardType: 'phone-pad' يعرض لوحة مفاتيح الهاتف. يحسن هذا النهج تجربة المستخدم لإدخال أرقام الهاتف ويمنع أخطاء التنسيق.