TextInput — چیست، ورود متن و React Native

TextInput در React Native چیست

TextInput یک کامپوننت React Native است که به کاربر اجازه می‌دهد متن را از طریق صفحه‌کلید دستگاه وارد کند. این عنصر اصلی برای فرم‌های ثبت‌نام، نوارهای جستجو، فیلدهای ورود پیام و هر سناریوی دیگری است که نیاز به ورود کاربر دارد. برخلاف توسعه وب که انواع مختلف input (text, email, password, search) وجود دارد، در React Native همه این گزینه‌ها از طریق یک کامپوننت TextInput با ویژگی‌های مختلف پیاده‌سازی می‌شوند.

TextInput از دو حالت کاری پشتیبانی می‌کند: کنترل‌شده (مدیریت شده از طریق state React) و کنترل‌نشده (با ref). در حالت کنترل‌شده، مقدار فیلد در state کامپوننت ذخیره می‌شود و از طریق callback onChangeText به‌روزرسانی می‌شود. این رویکرد برای اکثر برنامه‌ها توصیه می‌شود، زیرا یک منبع واحد حقیقت را فراهم می‌کند و اعتبارسنجی را ساده می‌سازد.

به گزارش React Native Handling Text Input, 2024، TextInput به‌طور خودکار با پلتفرم تطبیق می‌یابد: در iOS از UITextField بومی و در Android از EditText استفاده می‌کند. این امر عملکرد صحیح تصحیح خودکار، خودکارسازی و منوهای سیستمی (برش/کپی/چسباندن) را بدون تنظیمات اضافی تضمین می‌کند.

ویژگی‌ها و API کامپوننت TextInput

TextInput مجموعه گسترده‌ای از ویژگی‌ها را برای مدیریت ورود، ظاهر و رفتار ارائه می‌دهد. همه ویژگی‌ها به چند دسته تقسیم می‌شوند: مدیریت مقدار، نوع صفحه‌کلید، استایل‌دهی، رویدادها و ویژگی‌های پلتفرمی.

ویژگی‌های مدیریت مقدار

value — مقدار فعلی فیلد (برای حالت کنترل‌شده). onChangeText — callback که با هر تغییر متن فراخوانی می‌شود. placeholder — متن راهنما که وقتی فیلد خالی است نمایش داده می‌شود. defaultValue — مقدار اولیه برای حالت کنترل‌نشده. maxLength حداکثر تعداد کاراکترهایی را که کاربر می‌تواند وارد کند محدود می‌کند.

رویدادهای TextInput

کامپوننت از onFocus (فیلد فوکوس گرفت)، onBlur (فیلد فوکوس را از دست داد)، onSubmitEditing (کاربر Enter/Return را فشار داد)، onKeyPress (فشار دادن کلید) پشتیبانی می‌کند. رویداد onEndEditing پس از پایان ویرایش هنگام از دست دادن فوکوس فراخوانی می‌شود. این callbackها امکان پیاده‌سازی منطق پیچیده اعتبارسنجی و ارسال فرم‌ها را فراهم می‌کنند.

ویژگی‌های پلتفرمی

در iOS موجود است: clearButtonMode (دکمه پاک کردن)، keyboardAppearance (صفحه‌کلید روشن/تاریک)، returnKeyType (نوع دکمه Return)، enablesReturnKeyAutomatically. در Android موجود است: textContentType (تکمیل خودکار)، underlineColorAndroid، inlineImageLeft. secureTextEntry در هر دو پلتفرم برای ورود رمز عبور کار می‌کند.

ورود کنترل‌شده و کنترل‌نشده

در React Native، TextInput می‌تواند در دو حالت کار کند. در حالت کنترل‌شده، React مقدار فیلد را مدیریت می‌کند: شما value را از state ارسال می‌کنید و آن را از طریق onChangeText به‌روزرسانی می‌کنید. در حالت کنترل‌نشده، React فقط فیلد را مقداردهی اولیه می‌کند و مقدار شبیه به DOM در داخل کامپوننت بومی ذخیره می‌شود.

TextInput کنترل‌شده

حالت کنترل‌شده برای تمام فرم‌هایی که نیاز به اعتبارسنجی، فیلتر یا قالب‌بندی داده‌های ورودی دارند توصیه می‌شود. وضعیت فیلد با state کامپوننت 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 برای پنهان کردن کاراکترهای وارد شده استفاده می‌کند و از طریق maxLength به ۳۲ کاراکتر محدود شده است.

TextInput کنترل‌نشده

حالت کنترل‌نشده برای فیلدهای ساده‌ای مناسب است که نیازی به اعتبارسنجی یا واکنش فوری به ورود ندارند. مقدار فیلد در زمان ارسال فرم از طریق ref دریافت می‌شود.

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

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

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

در حالت کنترل‌نشده، کامپوننت سریع‌تر رندر می‌شود، زیرا نیازی به همگام‌سازی state با هر تغییر متن ندارد. با این حال، امکان فیلتر کردن، قالب‌بندی یا اعتبارسنجی ورود در زمان واقعی را از دست می‌دهید.

انواع صفحه‌کلید و ویژگی‌های پلتفرمی

TextInput از انواع مختلف صفحه‌کلید پشتیبانی می‌کند که چیدمان را با فرمت ورود مورد انتظار تطبیق می‌دهند. انتخاب نوع صحیح صفحه‌کلید تجربه کاربری را بهبود می‌بخشد و تعداد خطاهای ورود در دستگاه‌های همراه را کاهش می‌دهد.

در iOS انواع اضافی موجود است: numbers-and-punctuation (اعداد و علائم نگارشی)، twitter، web-search (با جستجوی صوتی). در Android همچنین visible-password (نمایش رمز عبور) موجود است. انتخاب صحیح keyboardType یک جنبه مهم UX در برنامه موبایل است.

ویژگی‌های پلتفرمی همچنین شامل autoCapitalize (بزرگ‌نویسی خودکار کلمه اول)، autoCorrect (تصحیح خودکار)، spellCheck (بررسی املا)، textContentType (تکمیل خودکار در iOS) می‌شود. این ویژگی‌ها در هر پلتفرم متفاوت کار می‌کنند و نیاز به آزمایش دارند.

مثال‌های عملی با TextInput

دو سناریوی واقعی را بررسی می‌کنیم: فیلد چندخطی برای ورود پیام و فیلد با ورود ماسک‌شده شماره تلفن. هر دو از TextInput با ویژگی‌های مختلف برای دستیابی به رفتار مورد نظر استفاده می‌کنند.

مثال ۱: فیلد چندخطی برای پیام

برای ورود متن طولانی (نظرات، توضیحات)، 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 چندخطی متن را به صورت عمودی وسط‌چین می‌کند).

مثال ۲: فیلد با قالب‌بندی شماره تلفن

برای ورود شماره تلفن اغلب قالب‌بندی در زمان واقعی مورد نیاز است. با ترکیب 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' صفحه‌کلید تلفن را نشان می‌دهد. چنین رویکردی UX را برای ورود شماره تلفن بهبود می‌بخشد و از خطاهای قالب‌بندی جلوگیری می‌کند.