TextInput

一個基礎元件，用於透過鍵盤將文字輸入到應用程式中。Props 為多項功能提供可配置性，例如自動校正、自動大寫、佔位符文字，以及不同的鍵盤類型，例如數字鍵盤。

最基本的使用案例是放置一個 TextInput 並訂閱 onChangeText 事件以讀取使用者輸入。還有其他事件可以訂閱，例如 onSubmitEditing 和 onFocus。一個最小的範例

透過原生元素公開的兩個方法是 .focus() 和 .blur()，它們將以程式設計方式聚焦或模糊化 TextInput。

請注意，某些 props 僅在 multiline={true/false} 的情況下可用。此外，如果 multiline=true，則僅適用於元素一側的邊框樣式（例如，borderBottomColor、borderLeftWidth 等）將不會被套用。若要達到相同的效果，您可以將 TextInput 包裹在 View 中

TextInput 預設在其視圖底部有一個邊框。此邊框的 padding 由系統提供的背景圖片設定，且無法變更。避免此問題的解決方案是不明確設定高度，在這種情況下，系統會負責在正確位置顯示邊框，或者透過將 underlineColorAndroid 設定為 transparent 來不顯示邊框。

請注意，在 Android 上，在輸入中執行文字選取可能會將應用程式的 activity windowSoftInputMode 參數變更為 adjustResize。這可能會導致在鍵盤處於活動狀態時，位置為 'absolute' 的元件出現問題。若要避免此行為，請在 AndroidManifest.xml 中指定 windowSoftInputMode ( https://developer.android.com/guide/topics/manifest/activity-element.html ) 或使用原生程式碼以程式設計方式控制此參數。

---

參考

Props

View Props

繼承 View Props。

---

allowFontScaling

指定字體是否應縮放以符合「文字大小」輔助功能設定。預設值為 true。

類型
bool

---

autoCapitalize

告知 TextInput 自動將某些字元大寫。某些鍵盤類型（例如 name-phone-pad）不支援此屬性。

• characters：所有字元。
• words：每個字詞的首字母。
• sentences：每個句子的首字母（預設）。
• none：不要自動將任何內容大寫。

類型
enum('none', 'sentences', 'words', 'characters')

---

autoComplete

指定系統的自動完成提示，以便它可以提供自動填寫。在 Android 上，系統將始終嘗試使用啟發法來識別內容類型以提供自動填寫。若要停用自動完成，請將 autoComplete 設定為 off。

以下值適用於跨平台

• additional-name
• address-line1
• address-line2
• birthdate-day (iOS 17+)
• birthdate-full (iOS 17+)
• birthdate-month (iOS 17+)
• birthdate-year (iOS 17+)
• cc-csc (iOS 17+)
• cc-exp (iOS 17+)
• cc-exp-day (iOS 17+)
• cc-exp-month (iOS 17+)
• cc-exp-year (iOS 17+)
• cc-number
• country
• current-password
• email
• family-name
• given-name
• honorific-prefix
• honorific-suffix
• name
• new-password
• off
• one-time-code
• postal-code
• street-address
• tel
• username

iOS

以下值僅適用於 iOS

• cc-family-name (iOS 17+)
• cc-given-name (iOS 17+)
• cc-middle-name (iOS 17+)
• cc-name (iOS 17+)
• cc-type (iOS 17+)
• nickname
• organization
• organization-title
• url

Android

以下值僅適用於 Android

• gender
• name-family
• name-given
• name-middle
• name-middle-initial
• name-prefix
• name-suffix
• password
• password-new
• postal-address
• postal-address-country
• postal-address-extended
• postal-address-extended-postal-code
• postal-address-locality
• postal-address-region
• sms-otp
• tel-country-code
• tel-device
• tel-national
• username-new

類型

enum('additional-name', 'address-line1', 'address-line2', 'birthdate-day', 'birthdate-full', 'birthdate-month', 'birthdate-year', 'cc-csc', 'cc-exp', 'cc-exp-day', 'cc-exp-month', 'cc-exp-year', 'cc-number', 'country', 'current-password', 'email', 'family-name', 'given-name', 'honorific-prefix', 'honorific-suffix', 'name', 'new-password', 'off', 'one-time-code', 'postal-code', 'street-address', 'tel', 'username', 'cc-family-name', 'cc-given-name', 'cc-middle-name', 'cc-name', 'cc-type', 'nickname', 'organization', 'organization-title', 'url', 'gender', 'name-family', 'name-given', 'name-middle', 'name-middle-initial', 'name-prefix', 'name-suffix', 'password', 'password-new', 'postal-address', 'postal-address-country', 'postal-address-extended', 'postal-address-extended-postal-code', 'postal-address-locality', 'postal-address-region', 'sms-otp', 'tel-country-code', 'tel-device', 'tel-national', 'username-new')

---

autoCorrect

若為 false，則停用自動校正。預設值為 true。

類型
bool

---

autoFocus

若為 true，則聚焦輸入框。預設值為 false。

類型
bool

---

blurOnSubmit

已棄用。 請注意，submitBehavior 現在取代了 blurOnSubmit，並將覆寫 blurOnSubmit 定義的任何行為。請參閱 submitBehavior

若為 true，則文字欄位在提交時會模糊化。單行欄位的預設值為 true，多行欄位的預設值為 false。請注意，對於多行欄位，將 blurOnSubmit 設定為 true 表示按下 return 鍵將會模糊化欄位並觸發 onSubmitEditing 事件，而不是在欄位中插入換行符號。

類型
bool

---

caretHidden

若為 true，則會隱藏游標。預設值為 false。

類型
bool

---

clearButtonMode

iOS

清除按鈕應在文字檢視右側出現的時間。此屬性僅適用於單行 TextInput 元件。預設值為 never。

類型
enum('never', 'while-editing', 'unless-editing', 'always')

---

clearTextOnFocus

iOS

若為 true，則在編輯開始時自動清除文字欄位。

類型
bool

---

contextMenuHidden

若為 true，則會隱藏上下文選單。預設值為 false。

類型
bool

---

dataDetectorTypes

iOS

決定文字輸入中轉換為可點擊 URL 的資料類型。僅在 multiline={true} 和 editable={false} 時有效。預設情況下，不會偵測到任何資料類型。

您可以提供一種類型或多種類型的陣列。

dataDetectorTypes 的可能值為

• 'phoneNumber'
• 'link'
• 'address'
• 'calendarEvent'
• 'none'
• 'all'

類型
enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all'), ,enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all') 的陣列

---

defaultValue

提供一個初始值，該值將在使用者開始輸入時變更。對於您不想處理監聽事件和更新 value prop 以保持受控狀態同步的使用案例很有用。

類型
string

---

cursorColor

Android

提供時，它將設定元件中游標（或「插入符號」）的顏色。與 selectionColor 的行為不同，游標顏色將獨立於文字選取框的顏色設定。

類型
color

---

disableFullscreenUI

Android

當 false 時，如果文字輸入周圍有少量可用空間（例如手機上的橫向方向），則作業系統可能會選擇讓使用者在全螢幕文字輸入模式下編輯文字。當 true 時，此功能會停用，使用者將始終直接在文字輸入框內編輯文字。預設為 false。

類型
bool

---

editable

若為 false，則文字不可編輯。預設值為 true。

類型
bool

---

enablesReturnKeyAutomatically

iOS

若為 true，則鍵盤會在沒有文字時停用 return 鍵，並在有文字時自動啟用它。預設值為 false。

類型
bool

---

enterKeyHint

決定應向 return 鍵顯示的文字。優先於 returnKeyType prop。

以下值適用於跨平台

• enter
• done
• next
• search
• send

僅限 Android

以下值僅適用於 Android

• previous

類型
enum('enter', 'done', 'next', 'previous', 'search', 'send')

---

importantForAutofill

Android

告知作業系統，您的應用程式中的個別欄位是否應包含在 Android API Level 26+ 的自動填寫目的的視圖結構中。可能的值為 auto、no、noExcludeDescendants、yes 和 yesExcludeDescendants。預設值為 auto。

• auto：讓 Android 系統使用其啟發法來判斷視圖對於自動填寫是否重要。
• no：此視圖對於自動填寫並不重要。
• noExcludeDescendants：此視圖及其子項對於自動填寫並不重要。
• yes：此視圖對於自動填寫很重要。
• yesExcludeDescendants：此視圖對於自動填寫很重要，但其子項對於自動填寫並不重要。

類型
enum('auto', 'no', 'noExcludeDescendants', 'yes', 'yesExcludeDescendants')

---

inlineImageLeft

Android

如果已定義，則提供的影像資源將在左側呈現。影像資源必須位於 /android/app/src/main/res/drawable 中，並像這樣引用

<TextInput
 inlineImageLeft='search_icon'
/>

類型
string

---

inlineImagePadding

Android

內嵌影像（如果有的話）與文字輸入本身之間的 padding。

類型
number

---

inputAccessoryViewID

iOS

一個可選的識別碼，將自訂的 InputAccessoryView 連結到此文字輸入框。當此文字輸入框聚焦時，InputAccessoryView 會在鍵盤上方呈現。

類型
string

---

inputMode

作用類似於 HTML 中的 inputmode 屬性，它決定要開啟哪個鍵盤，例如 numeric，並且優先於 keyboardType。

支援以下值

• none
• text
• decimal
• numeric
• tel
• search
• email
• url

類型
enum('decimal', 'email', 'none', 'numeric', 'search', 'tel', 'text', 'url')

---

keyboardAppearance

iOS

決定鍵盤的顏色。

類型
enum('default', 'light', 'dark')

---

keyboardType

決定要開啟哪個鍵盤，例如 numeric。

在此處查看所有類型的螢幕截圖 這裡。

以下值適用於跨平台

• default
• number-pad
• decimal-pad
• numeric
• email-address
• phone-pad
• url

僅限 iOS

以下值僅適用於 iOS

• ascii-capable
• numbers-and-punctuation
• name-phone-pad
• twitter
• web-search

僅限 Android

以下值僅適用於 Android

• visible-password

類型
enum('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)
• 0：無最大值，忽略父項/全域預設值
• >= 1：將此節點的 maxFontSizeMultiplier 設定為此值

類型
number

---

maxLength

限制可以輸入的最大字元數。使用此屬性而不是在 JS 中實作邏輯以避免閃爍。

類型
number

---

multiline

若為 true，則文字輸入框可以是多行的。預設值為 false。

注意

請務必注意，這會在 iOS 上將文字對齊到頂部，並在 Android 上將其置中。搭配設定為 top 的 textAlignVertical 使用，以在兩個平台上獲得相同的行為。

類型
bool

---

numberOfLines

Android

設定 TextInput 的行數。將其與設定為 true 的 multiline 一起使用，以便能夠填滿這些行。

類型
number

---

onBlur

當文字輸入框失去焦點時呼叫的回呼函數。

注意：如果您嘗試從 nativeEvent 存取 text 值，請記住您獲得的結果值可能是 undefined，這可能會導致意外錯誤。如果您嘗試尋找 TextInput 的最後一個值，您可以使用 onEndEditing 事件，該事件會在編輯完成時觸發。

類型
function

---

onChange

當文字輸入框的文字變更時呼叫的回呼函數。

類型
({nativeEvent: {eventCount, target, text}}) => void

---

onChangeText

當文字輸入框的文字變更時呼叫的回呼函數。變更後的文字會作為單一字串引數傳遞至回呼處理常式。

類型
function

---

onContentSizeChange

當文字輸入框的內容大小變更時呼叫的回呼函數。

僅針對多行文字輸入框呼叫。

類型
({nativeEvent: {contentSize: {width, height} }}) => void

---

onEndEditing

當文字輸入結束時呼叫的回呼函數。

類型
function

---

onPressIn

當觸控被觸發時呼叫的回呼函數。

類型
({nativeEvent: PressEvent}) => void

---

onPressOut

當觸控被釋放時呼叫的回呼函數。

類型
({nativeEvent: PressEvent}) => void

---

onFocus

當文字輸入框聚焦時呼叫的回呼函數。

類型
({nativeEvent: LayoutEvent}) => void

---

onKeyPress

當按下按鍵時呼叫的回呼函數。這將使用物件呼叫，其中 keyValue 對於各自的按鍵為 'Enter' 或 'Backspace'，否則為輸入的字元，包括空格 ' '。在 onChange 回呼之前觸發。注意：在 Android 上，僅處理軟體鍵盤的輸入，而不處理硬體鍵盤的輸入。

類型
({nativeEvent: {key: keyValue} }) => void

---

onLayout

在掛載時和版面配置變更時調用。

類型
({nativeEvent: LayoutEvent}) => void

---

onScroll

在內容滾動時調用。也可能包含來自 ScrollEvent 的其他屬性，但由於效能考量，Android 上未提供 contentSize。

類型
({nativeEvent: {contentOffset: {x, y} }}) => void

---

onSelectionChange

當文字輸入框選取範圍變更時呼叫的回呼函數。

類型
({nativeEvent: {selection: {start, end} }}) => void

---

onSubmitEditing

當按下文字輸入框的提交按鈕時呼叫的回呼函數。

類型
({nativeEvent: {text, eventCount, target}}) => void

請注意，當使用 keyboardType="phone-pad" 時，不會在 iOS 上呼叫此方法。

---

placeholder

在輸入文字之前將呈現的字串。

類型
string

---

placeholderTextColor

佔位符字串的文字顏色。

類型
color

---

readOnly

若為 true，則文字不可編輯。預設值為 false。

類型
bool

---

returnKeyLabel

Android

將 return 鍵設定為標籤。使用它來代替 returnKeyType。

類型
string

---

returnKeyType

決定 return 鍵應有的外觀。在 Android 上，您也可以使用 returnKeyLabel。

跨平台

以下值適用於跨平台

• done
• go
• next
• search
• send

僅限 Android

以下值僅適用於 Android

• none
• previous

僅限 iOS

以下值僅適用於 iOS

• default
• emergency-call
• google
• join
• route
• yahoo

類型
enum('done', 'go', 'next', 'search', 'send', 'none', 'previous', 'default', 'emergency-call', 'google', 'join', 'route', 'yahoo')

rejectResponderTermination

iOS

若為 true，則允許 TextInput 將觸控事件傳遞給父元件。這允許諸如 SwipeableListView 之類的元件可以從 iOS 上的 TextInput 滑動，就像 Android 上的預設情況一樣。若為 false，則 TextInput 始終要求處理輸入（除非停用）。預設值為 true。

類型
bool

---

rows

Android

設定 TextInput 的行數。將其與設定為 true 的 multiline 一起使用，以便能夠填滿這些行。

類型
number

---

scrollEnabled

iOS

若為 false，則會停用文字檢視的滾動。預設值為 true。僅適用於 multiline={true}。

類型
bool

---

secureTextEntry

若為 true，則文字輸入框會遮蔽輸入的文字，以便密碼等敏感文字保持安全。預設值為 false。不適用於 multiline={true}。

類型
bool

---

selection

文字輸入框選取範圍的開始和結束位置。將 start 和 end 設定為相同的值以定位游標。

類型
object: {start: number,end: number}

---

selectionColor

文字輸入框的醒目提示、選取控制點和游標顏色。

類型
color

---

selectionHandleColor

Android

設定選取控制點的顏色。與 selectionColor 不同，它允許獨立於選取範圍的顏色自訂選取控制點顏色。

類型
color

---

selectTextOnFocus

若為 true，則所有文字將在聚焦時自動選取。

類型
bool

---

showSoftInputOnFocus

當 false 時，它將阻止在欄位聚焦時顯示軟體鍵盤。預設值為 true。

類型
bool

---

spellCheck

iOS

若為 false，則停用拼字檢查樣式（即紅色底線）。預設值繼承自 autoCorrect。

類型
bool

---

submitBehavior

當按下 return 鍵時，

對於單行輸入框

• 'newline' 預設為 'blurAndSubmit'
• undefined 預設為 'blurAndSubmit'

對於多行輸入框

• 'newline' 新增換行符號
• undefined 預設為 'newline'

對於單行和多行輸入框

• 'submit' 將僅傳送提交事件，而不會模糊化輸入框
• 'blurAndSubmit' 將同時模糊化輸入框並傳送提交事件

類型
enum('submit', 'blurAndSubmit', 'newline')

---

textAlign

將輸入文字對齊到輸入欄位的左側、中心或右側。

textAlign 的可能值為

• left
• center
• right

類型
enum('left', 'center', 'right')

---

textContentType

iOS

提供鍵盤和系統關於使用者輸入內容的預期語義含義的資訊。

注意

autoComplete，提供相同的功能，並且適用於所有平台。您可以針對不同的平台行為使用 Platform.select。

避免同時使用 textContentType 和 autoComplete。為了向後相容性，當同時設定這兩個屬性時，textContentType 優先。

您可以將 textContentType 設定為 username 或 password，以啟用從裝置鑰匙鏈自動填寫登入詳細資訊。

newPassword 可用於指示使用者可能想要儲存在鑰匙鏈中的新密碼輸入，而 oneTimeCode 可用於指示欄位可以由 SMS 中收到的程式碼自動填寫。

若要停用自動填寫，請將 textContentType 設定為 none。

textContentType 的可能值為

• none
• addressCity
• addressCityAndState
• addressState
• birthdate (iOS 17+)
• birthdateDay (iOS 17+)
• birthdateMonth (iOS 17+)
• birthdateYear (iOS 17+)
• countryName
• creditCardExpiration (iOS 17+)
• creditCardExpirationMonth (iOS 17+)
• creditCardExpirationYear (iOS 17+)
• creditCardFamilyName (iOS 17+)
• creditCardGivenName (iOS 17+)
• creditCardMiddleName (iOS 17+)
• creditCardName (iOS 17+)
• creditCardNumber
• creditCardSecurityCode (iOS 17+)
• creditCardType (iOS 17+)
• emailAddress
• familyName
• fullStreetAddress
• givenName
• jobTitle
• location
• middleName
• name
• namePrefix
• nameSuffix
• newPassword
• nickname
• oneTimeCode
• organizationName
• password
• postalCode
• streetAddressLine1
• streetAddressLine2
• sublocality
• telephoneNumber
• URL
• username

類型

enum('none', 'addressCity', 'addressCityAndState', 'addressState', 'birthdate', 'birthdateDay', 'birthdateMonth', 'birthdateYear', 'countryName', 'creditCardExpiration', 'creditCardExpirationMonth', 'creditCardExpirationYear', 'creditCardFamilyName', 'creditCardGivenName', 'creditCardMiddleName', 'creditCardName', 'creditCardNumber', 'creditCardSecurityCode', 'creditCardType', 'emailAddress', 'familyName', 'fullStreetAddress', 'givenName', 'jobTitle', 'location', 'middleName', 'name', 'namePrefix', 'nameSuffix', 'newPassword', 'nickname', 'oneTimeCode', 'organizationName', 'password', 'postalCode', 'streetAddressLine1', 'streetAddressLine2', 'sublocality', 'telephoneNumber', 'URL', 'username')

---

passwordRules

iOS

當在 iOS 上將 textContentType 用作 newPassword 時，我們可以讓作業系統知道密碼的最低要求，以便它可以產生一個符合要求的密碼。為了為 PasswordRules 建立有效的字串，請參閱 Apple 文件。

如果密碼產生對話方塊未出現，請確保

• 已啟用自動填寫：設定 → 密碼與帳號 → 切換「開啟」自動填寫密碼，
• 已使用 iCloud 鑰匙鏈：設定 → Apple ID → iCloud → 鑰匙鏈 → 切換「開啟」iCloud 鑰匙鏈。

類型
string

---

style

請注意，並非所有文字樣式都受支援，不受支援的不完整清單包括

• borderLeftWidth
• borderTopWidth
• borderRightWidth
• borderBottomWidth
• borderTopLeftRadius
• borderTopRightRadius
• borderBottomRightRadius
• borderBottomLeftRadius

樣式

類型
Text

---

textBreakStrategy

Android

在 Android API Level 23+ 上設定文字換行策略，可能的值為 simple、highQuality、balanced。預設值為 highQuality。

類型
enum('simple', 'highQuality', 'balanced')

---

underlineColorAndroid

Android

TextInput 底線的顏色。

類型
color

---

value

要顯示為文字輸入框的值。TextInput 是一個受控元件，這表示如果提供此值 prop，則原生值將強制與此值 prop 相符。對於大多數用途來說，這效果很好，但在某些情況下，這可能會導致閃爍 - 一個常見原因是透過保持值不變來防止編輯。除了設定相同的值之外，還可以設定 editable={false}，或設定/更新 maxLength 以防止不必要的編輯而不閃爍。

類型
string

---

lineBreakStrategyIOS

iOS

在 iOS 14+ 上設定換行策略。可能的值為 none、standard、hangul-word 和 push-out。

類型	預設
enum('none', 'standard', 'hangul-word', 'push-out')	'none'

---

disableKeyboardShortcuts

iOS

若為 true，則會停用鍵盤快速鍵（復原/重做和複製按鈕）。預設值為 false。

類型
bool

方法

.focus()

tsx

focus();

使原生輸入請求聚焦。

.blur()

tsx

blur();

使原生輸入失去焦點。

clear()

tsx

clear();

從 TextInput 中移除所有文字。

---

isFocused()

tsx

isFocused(): boolean;

如果輸入目前已聚焦，則傳回 true；否則傳回 false。

已知問題

• react-native#19096: 不支援 Android 的 onKeyPreIme。
• react-native#19366: 在透過返回按鈕關閉 Android 鍵盤後呼叫 .focus() 不會再次彈出鍵盤。
• react-native#26799: 當 keyboardType="email-address" 或 keyboardType="phone-pad" 時，不支援 Android 的 secureTextEntry。