الفرق بين المراجعتين ل"ReactNative/textinput"
رقية-بورية (نقاش | مساهمات) |
جميل-بيلوني (نقاش | مساهمات) |
||
سطر 877: | سطر 877: | ||
== مرجع الدوال == | == مرجع الدوال == | ||
− | === | + | === الدالة <code>.focus()</code> === |
<syntaxhighlight class="react" lang="javascript">focus();</syntaxhighlight> | <syntaxhighlight class="react" lang="javascript">focus();</syntaxhighlight> |
مراجعة 11:10، 3 مارس 2021
يُعَدّ المكون TextInput
من المكونات الأساسية في React Native، حيث يسمح للمستخدم بإدخال النصوص عن طريق لوحة المفاتيح، ويمكن التحكم في نوع الإدخال (نص، وأرقام، وبريد إلكتروني، وكلمة مرور ...إلخ) ونوع لوحة المفاتيح وغيرها من الخاصيات (props) التي سيأتي بيانها لاحقًا.
توضِّح الشيفرة أدناه كيفية استخدام المكون TextInput
، حيث يُستمع للحدث onChangeText
الذي يُحدِّث القيمة الخاصة بالمكون TextInput
والمخزّنة في الحالة (State) عند الضغط على أيّ زرّ في لوحة المفاتيح. وتوجد أحداث أخرى، مثل: onSubmitEditing
وonFocus
ستُشرح وظائفها لاحقًا.
import React from 'react';
import { TextInput } from 'react-native';
const UselessTextInput = () => {
const [value, onChangeText] = React.useState('Useless Placeholder');
return (
<TextInput
style={{ height: 40, borderColor: 'gray', borderWidth: 1 }}
onChangeText={text => onChangeText(text)}
value={value}
/>
);
}
export default UselessTextInput;
تُستخدم الدالتان ()focus.
و()blur.
للتركيز على العنصر أو لنقل التركيز بعيدًا عنه بطريقة برمجية.
تكون بعض الخاصيّات متاحةً فقط في إحدى الحالتين multiline={true/false}
، مثل: خواص الإطارات (borderBottomColor
، وborderLeftWidth
و غيرها) حيث لا تعمل هذه الخواص مع الخاصية multiline=true
، ويمكن الحصول على نفس تأثير هذه الخواص عن طريق وضع المكون TextInput
داخل المكون View
وتطبيق هذه الخواص على الأخير.
مثال
import React from 'react';
import { View, TextInput } from 'react-native';
const UselessTextInput = (props) => {
return (
<TextInput
{...props}
editable
maxLength={40}
/>
);
}
const UselessTextInputMultiline = () => {
const [value, onChangeText] = React.useState('Useless Multiline Placeholder');
return (
<View
style={{
backgroundColor: value,
borderBottomColor: '#000000',
borderBottomWidth: 1,
}}>
<UselessTextInput
multiline
numberOfLines={4}
onChangeText={text => onChangeText(text)}
value={value}
/>
</View>
);
}
export default UselessTextInputMultiline;
ملاحظة: يمتلك المكوّن TextInput
إطارًا سفليًا، وتوجد حاشية بارتفاع معيّن بين الإطار و العنصر نفسه، ولا يمكن تعديل ارتفاعها، لحل هذه المشكلة يمكن إتباع إحدى الطريقتين التاليتين:
- عدم تحديد إرتفاع معيّن للمكون
TextInput
، وفي هذه الحالة سيتولى نظام التشغيل أمر عرض الإطار السفلي في مكانه الصحيح. - إخفاء الإطار عن طريق إعطاء الخاصية
underlineColorAndroid
القيمةtransparent
.
ملاحظة: لاحظ أنَّ تحديد النص داخل المكون TextInput
على الأجهزة التي تعمل على نظام أندرويد قد يسبِّب تغيير قيمة الخاصية windowSoftInputMode
إلى adjustResize
، مما يؤثر على عرض العناصر ذات الموضع المطلق position: absolute
عندما تكون لوحة المفاتيح مفتوحة، ويمكن حلّ هذه المشكلة عن طريق تحديد قيمة الخاصية windowSoftInputMode
في ملف AndroidMainfest.xml
(انظر توثيق MDN)، أو التحكم في هذه الخاصية عن طريق شيفرات أصلية (Native code).
مرجع الخاصيات
allowFontScaling
تُحدِّد ما إذا كان يجب تغيير حجم الخطوط لتناسب إعدادات حجم النص الخاصة بإمكانية الوصول (Accessibility settings)، القيمة الافتراضية هي true
.
النوع | مطلوب |
---|---|
قيمة منطقية (bool) | لا |
autoCapitalize
تُستخدم لتفعيل تكبير الأحرف تلقائيًا، وهي غير مدعومة في بعض أنواع لوحات المفاتيح، مثل: name-phone-pad
.
القيمة | الوصف |
---|---|
character
|
تكبير جميع الأحرف. |
words
|
تكبير الحرف الأول من كلّ كلمة. |
sentences
|
تكبير الحرف الأول من كلّ جملة (القيمة الإفتراضية). |
none
|
تعطيل التكبير التلقائي للأحرف. |
النوع | مطلوب |
---|---|
('none', 'sentences', 'words', 'characters')
|
لا |
autoCompleteType
تقدِّم أنظمة التشغيل والبرامج المختلفة خاصية الإكمال التلقائي، إذ يُدخل المستخدم جزءًا من الكلمة التي يريد البحث عنها فيعطيه النظام أو البرنامج بعض الاقتراحات لإكمال الكلمة التي أدخلها تلقائيًا وذلك بالاستناد إلى مجموعة من السلسلة النصية المخزّنة مسبقًا في النظام.
تأخذ الخاصية autoCompleteType
إحدى القيم التالية:
off
username
password
email
name
tel
street-address
postal-code
cc-number
cc-csc
cc-exp
cc-exp-month
cc-exp-year
النوع | مطلوب | نظام التشغيل |
---|---|---|
('off', 'username', 'password', 'email', 'name', 'tel', 'street-address', 'postal-code', 'cc-number', 'cc-csc', 'cc-exp', 'cc-exp-month', 'cc-exp-year')
|
لا | أندرويد |
autoCorrect
تُستخدم لتفعيل أو تعطيل التصحيح التلقائي للكلمات، والقيمة الافتراضية هي true
.
النوع | مطلوب |
---|---|
قيمة منطقية (bool) | لا |
autoFocus
تسمح لنا هذه الخاصية بنقل التركيز (focus) تلقائيًا إلى العنصر عند تحميل الصفحة (componentDidMount
)، والقيمة الافتراضية هي false
.
النوع | مطلوب |
---|---|
قيمة منطقية (bool) | لا |
blurOnSubmit
تسمح هذه الخاصية بنقل التركيز بعيدًا عن العنصر، القيمة الافتراضية لها هي true
لحقول الإدخال ذات السطر الواحد، والقيمة false
للحقول ذات الأسطر المتعددة. إعطاء الخاصية القيمة true
للحقول ذات الأسطر المتعددة سينقل التركيز بعيدًا عن العنصر عن الضغط على زرّ الإدخال (Enter) بدلًا عن الانتقال لسطر جديد.
النوع | مطلوب |
---|---|
قيمة منطقية (bool) | لا |
carretHidden
تُخفي هذه الخاصية مؤشر الإدخال إذا كانت قيمتها true
، والقيمة الإفتراضية لها هي false
.
النوع | مطلوب |
---|---|
قيمة منطقية (bool) | لا |
clearButtonMode
تُحدِّد متى سيظهر زرّ المسح (clear) بجانب حقل الإدخال TextInput
، والقيمة الافتراضية هي never
.
النوع | مطلوب | نظام التشغيل |
---|---|---|
('never', 'while-editing', 'unless-editing', 'always')
|
لا | iOS |
clearTextOnFocus
إذا أُعطيت هذه الخاصية القيمة true
، يُفرَّغ حقل الإدخال عن الضغط عليه.
النوع | مطلوب | نظام التشغيل |
---|---|---|
قيمة منطقية (bool) | لا | iOS |
contextMenuHidden
تُستخدم لإظهار أو إخفاء قائمة السياق (context menu).
النوع | مطلوب |
---|---|
قيمة منطقية (bool) | لا |
dataDetectorTypes
تُحدّد أنواع البيانات المُدخلة التي ستُحوَّل إلى روابط يمكن الضغط عليها، ولا يمكن استخدام هذه الخاصية إلَّا مع الخاصيتين multiline=true
وeditable=false
. ما قد تأخذ قيمةً واحدةً أو مصفوفة قيم.
القيم المُتاحة:
'phoneNumber'
'link'
'address'
'calenderEvent'
'none'
'all'
النوع | مطلوب | نظام التشغيل |
---|---|---|
('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all'), ,array of enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all') | لا | iOS |
defaultValue
تعطي قيمةص إبتدائيةً للمكوّن TextInpu
، وتتغيَّر هذه القيمة تلقائيًا عندما يبدأ المستخدم في الكتابة.
النوع | مطلوب |
---|---|
سلسلة نصية (string) | لا |
disableFullscreenUI
إذا كانت قيمة هذه الخاصية false
- وهي القيمة الإفتراضية - يعرض نظام التشغيل حقل الإدخال في ملء الشاشة، أمّا إذا أعطيت القيمة true
فسيُعَطَّل هذا السلوك ويُعرض حقل الإدخال في الحالة الطبيعية.
النوع | مطلوب | نظام التشغيل |
---|---|---|
قيمة منطقية (bool) | لا | أندرويد |
editable
تمنع تعديل النص داخل حقل الإدخال TextInput
إذا كانت قيمتها false
، والقيمة الافتراضية هي true
.
النوع | مطلوب |
---|---|
قيمة منطقية (bool) | لا |
enablesReturnKeyAutomatically
عند إعطاء هذه الخاصية القيمة true
، تُعطِّل لوحة المفاتيح زرّ الإدخال عندما يكون حقل الإدخال TextInput
فارغًا، وتعيد تشغيله تلقائيًا عند وجود أيّ نص داخله، والقيمة الافتراضية هي false
.
importantForAutofill
تُحدّد ما إذا كانت الحقول ستُضاف إلى هيكلة العرض بغرض الملء التلقائي (autofill). القيمة الافتراضية هي auto
. وقد تأخذ إحدى القيم التالية:
القيمة | الوصف |
---|---|
auto
|
تترك نظام التشغيل يُحدِّد ما إذا كان سيتم ملء الحقل تلقائيًا. |
no
|
تُعطل الملء التلقائي للحقول. |
noExcludeDescendants
|
تُعطل الملء التلقائي للحقول الأبناء للعنصر الحالي. |
yes
|
تُفعِّل الملء التلقائي للحقول. |
yesExcludeDescendants
|
تُفعِّل الملء التلقائي للحقول الأبناء للعنصر الحالي. |
النوع | مطلوب | نظام التشغيل |
---|---|---|
('auto', 'no', 'noExcludeDescendants', 'yes', 'yesExcludeDescendants')
|
لا | أندرويد |
inlineImageLeft
تعرض الصورة باتجاه اليسار. ينبغي أن تكون الصورة داخل الملف /android/app/src/main/res/drawable
، وتُستعمل كالآتي:
<TextInput inlineImageLeft='search_icon' />
النوع | مطلوب | نظام التشغيل |
---|---|---|
سلسلة نصية (string) | لا | أندرويد |
inlineImagePadding
تُحدد حجم الحاشية بين الصورة والنص الموجود داخل حقل الإدخال TextInput
.
النوع | مطلوب | نظام التشغيل |
---|---|---|
عدد (number) | لا | أندرويد |
inputAccessoryViewID
مُعَرِّف اختياري يستخدم لربط المكون InputAccessoryView
مع حقل الإدخال TextInput
. يُعرض المكون InputAccessiryView
فوق لوحة المفاتيح عندما يُحدَّد المكون TextInput
.
النوع | مطلوب | نظام التشغيل |
---|---|---|
سلسلة نصية (string) | لا | iOS |
keyboardAppearance
تُحدد لون لوحة المفاتيح.
نوع | مطلوب | نظام التشغيل |
---|---|---|
('default', 'light', 'dark')
|
لا | iOS |
keyboardType
تُستخدم لتحديد نوع لوحة المفاتيح المستخدمة للإدخال.
القيم العامة للخاصية (تعمل على نظام أندرويد و iOS)
default
number-pad
decimal-pad
numeric
email-address
phone-pad
قيم تعمل فقط على نظام iOS
ascii-capable
numbers-and-punctuation
url
name-phone-pad
twitter
web-search
قيم تعمل فقط على نظام أندرويد
visible-password
النوع | مطلوب |
---|---|
('default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter', 'web-search', 'visible-password')
|
لا |
maxFontSizeMultiplier
تُحدِّد أقصى تكبير ممكن للخط عندما تكون الخاصية allowFontScaling
مُفعَّلة. وقد تأخذ القيم الآتية:
القيمة | الوصف |
---|---|
null أو undefined
|
ترث القيمة من العنصر الأب، أو تأخذ القيمة الإفتراضية (صفر) في حال عدم وجود قيمة للخاصية في العنصر الأب. |
0
|
لا توجد قيمة كُبرى. |
>=1
|
تعطي الخاصية maxFontSizeMultiplier القيمة المُحددة.
|
النوع | مطلوب |
---|---|
عدد (number) | لا |
maxLength
تُحدد أكبر عدد من الحروف يمكن إدخاله في الحقل TextInput
.
النوع | مطلوب |
---|---|
عدد (number) | لا |
multiline
تحدد ما إذا كان حقل الإدخال سطر واحد (وعندها تكون قيمتها false
) أو عدة أسطر (القيمة true
)، وتنبغي ملاحظتك لمحاذاة النص داخل عنصر الإدخال متعدد الأسطر إلى الأعلى على أجهزة iOS، وفي الوسط في أجهزة أندرويد، لذلك يجب استخدام الخاصية textAlignVertical
للحصول على سلوك مشابه في النظامين.
النوع | مطلوب |
---|---|
قيمة منطقية (bool) | لا |
الخاصية numberOfLines
تُحدد عدد الأسطر للعنصر TextInput
.
النوع | مطلوب | نظام التشغيل |
---|---|---|
عدد (number) | لا | أندرويد |
onBlue
دالة تُستدعى عندما يُبعد التركيز عن العنصر.
النوع | مطلوب |
---|---|
دالة (function) | لا |
onChange
دالة تُستدعَى عندما يتغير النص الموجود داخل العنصر TextInput
. وتُستدعى عن طريق {nativeEvent: {eventCount, target, text}}
.
النوع | مطلوب |
---|---|
دالة (function) | لا |
onChangeText
دالة تستدعَى عندما يتغير النص الموجود داخل العنصر TextInput
، ويُرسل النص الذي استُبدِل مثل معامل للدالة.
النوع | مطلوب |
---|---|
دالة (function) | لا |
onEndEditing
دالة تُستدعَى عند الإنتهاء من عملية الإدخال.
النوع | مطلوب |
---|---|
دالة (function) | لا |
onFocus
دالة تُستدعَى عند التركيز على العنصر وذلك بالضغط عليه.
النوع | مطلوب |
---|---|
دالة (function) | لا |
onKeyPress
دالة تُستدعَى عند الضغط على أيّ زرّ على لوحة المفاتيح.
النوع | مطلوب |
---|---|
دالة (function) | لا |
onLayout
دالة تُستدعَى مع الحدث onMount
.
النوع | مطلوب |
---|---|
دالة (function) | لا |
onScroll
دالة تُستدعَى عند التمرير (scroll) في الاتجاهات الأربعة، تُرسل إحداثيات الموضع الحالي مثل معاملات للدالة.
النوع | مطلوب |
---|---|
دالة (function) | لا |
الخاصية onSelectionChange
دالة تُستدعَى عند تغيير النص المُحدّد، وتتطلب هذه الخاصية أن تكون الخاصية multiline=true
موجودة.
النوع | مطلوب |
---|---|
دالة (function) | لا |
onSubmitEditing
دالة تُستدعَى عن الضغط على زرّ الإدخال (submit).
النوع | مطلوب |
---|---|
دالة (function) | لا |
ملاحظة: لا تعمل هذه الدالة على نظام iOS
عندما يكون نوع لوحة المفاتيح phone-pad
.
placeholder
تُحدِّد جملة أو سلسلة نصية تعمل مثل نص بديل يظهر عندما يكون عنصر الإدخال TextInput
فارغًا.
النوع | مطلوب |
---|---|
سلسلة نصية (string) | لا |
placeholderTextColor
تُحدِّد لون النص النائب (نص يُعرض بدلًا عن النص المُدخل عندما يكون العنصر فارغًا).
النوع | مطلوب |
---|---|
لون | لا |
returnKeyType
تُحدِّد كيفية عمل زرّ الإدخال.
القيم العامة للخاصية (تعمل على نظام أندرويد و iOS)
done
go
next
search
send
قِيَم تعمل على نظام أندرويد فقط
none
previous
قِيَم تعمل على نظام iOS فقط
default
emergency-call
google
join
route
yahoo
النوع | مطلوب |
---|---|
('done', 'go', 'next', 'search', 'send', 'none', 'previous', 'default', 'emergency-call', 'google', 'join', 'route', 'yahoo')
|
لا |
الخاصية returnKeyLabel
تُستعمل مثل بديل للخاصية returnKeyType
على أجهزة أندرويد.
نوع | مطلوب | نظام التشغيل |
---|---|---|
سلسلة نصية (string) | لا | أندرويد |
الخاصية rejectResponderTermination
ملاحظة: تعمل هذه الخاصية على نظام iOS فقط.
تسمح للعنصر TextInput
بتمرير حدث اللمس (touch event) للعنصر الأب عند إعطائها القيمة true
، مما يسمح لبعض العناصر مثل SwipeableListView
أن تُصبح قابلةً للتمرير من داخل العنصر TextInput
.
نوع | مطلوب | نظام التشغيل |
---|---|---|
قيمة منطقية (bool) | لا | iOS |
الخاصية scrollEnable
تسمح بتشغيل أو تعطيل التمرير في حقول الإدخال متعدّدة الأسطر. القيمة الإفتراضية لها هي true
.
نوع | مطلوب | نظام التشغيل |
---|---|---|
قيمة منطقية (bool) | لا | iOS |
الخاصية secureTextEntry
تُستخدم لحجب النص المُدخل وذلك عن طريق استبداله بنقاط أو العلامة (*). ولا تعمل هذه الخاصية مع حقول الإدخال متعدِّدة الأسطر.
النوع | مطلوب |
---|---|
قيمة منطقية (bool) | لا |
الخاصية selection
تُحدد موضع البداية والنهاية للنص المُحدد داخل العنصر TextInput
.
النوع | مطلوب |
---|---|
{start: number,end: number} | لا |
الخاصية selectionColor
تُحدِّد لون التظليل ومؤشر الإدخال.
النوع | مطلوب |
---|---|
لون | لا |
الخاصية selectTextOnFocus
تُحدِّد النص الموجود داخل العنصر TextInput
تلقائيًا عن الضغط عليه.
النوع | مطلوب |
---|---|
قيمة منطقية (bool) | لا |
الخاصية showSoftInputOnFocus
تمنع ظهور لوحة المفاتيح عند التركيز على العنصر TextInput
وذلك عندما تكون قيمتها false
، والقيمة الافتراضية هي true
.
النوع | مطلوب | نظام التشغيل |
---|---|---|
قيمة منطقية (bool) | لا | أندرويد |
الخاصية spellCheck
تستعمل لتشغيل أو تعطيل التدقيق الإملائي، وفي حال عدم تحديد قيمة لها فسترث قيمتها من الخاصية autoCorrect
.
النوع | مطلوب | نظام التشغيل |
---|---|---|
قيمة منطقية (bool) | لا | iOS |
الخاصية textAlign
تُستخدم لتحديد محاذاة النص داخل العنصر TextInput
. وتأخذ القيم:
left
center
right
النوع | مطلوب |
---|---|
('left', 'center', 'right')
|
لا |
الخاصية textContentType
تُعطي النظام معلومات متعلقة بدلالات النصوص المتوقَّع إدخالها من المستخدم.
في الإصدار 11 من نظام iOS وما بعده يمكن تحديد القيمة username
أو password
للخاصية textContentType
لتفعيل الملء التلقائي لبيانات الدخول (login).
في الإصدار 12 من نظام iOS وما بعده تُستخدم القيمة newPassword
للدلالة على كلمة مرور جديدة يُتوقَع إدخالها من المستخدم وتُحفظ في الجهاز.
تُستخدم القيمة oneTimeCode
للدلالة على إمكانية ملء الحقل تلقائيًا برمز يُرسل عن طريق رسالة نصية SMS.
لتعطيل الملء التلقائي تُستخدَم القيمة none
للخاصية textContentType
.
القيم المتاحة
none
URL
addressCity
addressCityAndState
addressState
countryName
creditCardNumber
emailAddress
familyName
fullStreetAddress
givenName
jobTitle
location
middleName
name
namePrefix
nameSuffix
nickname
organizationName
postalCode
streetAddressLine1
streetAddressLine2
sublocality
telephoneNumber
username
password
newPassword
oneTimeCode
النوع | مطلوب | نظام التشغيل |
---|---|---|
('none', 'URL', 'addressCity', 'addressCityAndState', 'addressState', 'countryName', 'creditCardNumber', 'emailAddress', 'familyName', 'fullStreetAddress', 'givenName', 'jobTitle', 'location', 'middleName', 'name', 'namePrefix', 'nameSuffix', 'nickname', 'organizationName', 'postalCode', 'streetAddressLine1', 'streetAddressLine2', 'sublocality', 'telephoneNumber', 'username', 'password')
|
لا | iOS |
الخاصية passwordRules
تُستعمل لإضافة شروط ينبغي تحقيقها حتى يكون النص المُدخل صالحًا.
النوع | مطلوب | نظام التشغيل |
---|---|---|
سلسلة نصية (string) | لا | iOS |
انظر قائمة الشروط
الخاصية style
تُستخدم لتطبيق أنماط معيّنة لتغيير شكل ومظهر حقل الإدخال TextInput
.
النوع | مطلوب |
---|---|
نص | لا |
انظر قائمة الأنماط.
الخاصية textBreakStrategy
تُستخدم لتحديد نقاط الفصل في النصوص (النقاط التي يتم عندها الانتقال لسطر جديد). ويمكن أخذ القيم التالية:
simple
highQuality
balanced
النوع | مطلوب | نظام التشغيل |
---|---|---|
سلسلة نصية (string) | لا | أندرويد |
الخاصية underlineColorAndroid
تُحدِّد لون الإطار السفلي للعنصر TextInput
.
النوع | مطلوب | نظام التشغيل |
---|---|---|
لون | لا | أندرويد |
الخاصية value
تُستخدم لتحديد قيمة إفتراضية للعنصر TextInput
.
النوع | مطلوب |
---|---|
سلسلة نصية (string) | لا |
ملاحظة: يجب التعامل مع هذه الخاصية بحذر، فاستعمالها بطريقة خاطئة قد يتسبب في منع المستخدم من تغيير القيمة الإفتراضية للحقل وغيرها من المشاكل الأخرى.
مرجع الدوال
الدالة .focus()
focus();
تُستخدم لتحويل التركيز للعنصر الذي تُستدعى فيه.
الدالة .blur()
blue();
تُستخدم لنقل التركيز بعيدًا عن العنصر الذي تُستدعى فيه.
الدالة clear()
clear();
تُستخدم لمسح محتوى العنصر TextInput
.
الدالة isFocused()
isFocused();
تُرجع القيمة true
إذا كان العنصر الذي استُدعيت فيه الدالة في وضع التركيز (focsed) وfalse
فيما عدا ذلك.