此组件提供基本的文本输入功能。
它可以在两种模式之一中使用。在第一种模式下,文本输入的内容是静态的,由 value
属性指定。任何尝试修改值的操作都将导致 onChangeText
被调用,这允许拥有组件使用更新的 value
重新渲染。在第二种模式下,value
未指定,并且只要文本输入保持挂载状态,就允许修改其值。在此模式下,调用者可以指定一个可选的 defaultValue
属性来指定初始值。
除了通用辅助功能属性之外,还支持以下属性。
// Text to be used by screen readers
accessibilityLabel: boolean = false;
// It is hard or impossible to tell by a reference to an instance of a component
// from where this component has been instantiated. You can assign this property
// and check instance.props.accessibilityId. For example accessibilityId is used
// in View's FocusArbitrator callback.
accessibilityId: string = undefined;
// Should fonts be scaled according to system setting?
allowFontScaling: boolean = true; // Android and iOS only
// Auto-capitalization mode
autoCapitalize: 'none' | 'sentences' | 'words' | 'characters';
// Should auto-correction be applied to contents?
autoCorrect: boolean = true;
// Should be focused when the component is mounted, see also View's arbitrateFocus
// property.
// WARNING: autoFocus=true means that this TextInput's requestFocus() method will be
// called, however calling requestFocus() might have no effect (for example the
// input is disabled), the application has to handle this either while setting this
// property or in the View's FocusArbitrator callback.
autoFocus: boolean = false;
// Should focus be lost after submitting?
blurOnSubmit: boolean = false;
// iOS and Windows only property for controlling when the clear button
// should appear on the right side of the text view. Default behavior
// dependends on platform: equivalent to 'never' on iOS, and 'always'
// on Windows.
clearButtonMode: 'never' | 'while-editing' | 'unless-editing' | 'always';
// Initial value that will change when the user starts typing
defaultValue: string = undefined;
// Disable full screen editor mode?
disableFullscreenUI: boolean = false; // Android-specific
// Can text be edited by the user?
editable: boolean = true;
// iOS-only prop for controlling the keyboard appearance
keyboardAppearance: 'default' | 'light' | 'dark';
// On-screen keyboard type to display
keyboardType: 'default' | 'numeric' | 'email-address' | 'number-pad';
// Maximum character count
maxLength: number = undefined;
// Should the control support multiple lines of text?
multiline: boolean = false;
// Called when the control loses focus
onBlur: () => void = undefined;
// Called when the text value changes
onChangeText: (newValue: string) => void = undefined;
// Called when the control obtains focus
onFocus: () => void = undefined;
// Called on a key event
onKeyPress: (e: KeyboardEvent) => void = undefined;
// Called when text is pasted into the control (not currently
// supported on iOS or Android)
onPaste: (e: ClipboardEvent) => void = undefined;
// Called when the selection scrolls due to overflow
onScroll: (newScrollLeft: number, newScrollTop: number) => void = undefined;
// Called when the selection range or insertion point location changes
onSelectionChange: (start: number, end: number) => void = undefined;
// Called when the text input submit button is pressed; invalid if
// multiline is true
onSubmitEditing: () => void = undefined;
// Placeholder text to dislpay when input is empty
placeholder: string = undefined;
// Color of placeholder text
placeholderTextColor: color = '#ccc';
// iOS and android prop for controlling return key type
returnKeyType: 'done' | 'go' | 'next' | 'search' | 'send';
// Obscure the text input (for passwords)?
secureTextEntry: boolean = false;
// Should spell checking be applied to contents?
spellCheck: boolean = [value of autoCorrect];
// See below for supported styles
style: TextInputStyleRuleSet | TextInputStyleRuleSet[] = [];
// ID that can be used to identify the instantiated element for testing purposes.
testId: string = undefined;
// Text for a tooltip
title: string = undefined;
// If defined, the control value is forced to match this value;
// if undefined, control value can be modified by the user
value: string = undefined;
// Forces the control to give up focus
blur(): void;
// Gives the control focus. For mobile, use setAccessibilityFocus()
// for setting screen reader focus
focus(): void;
// The preferable way to focus the component. When requestFocus() is called,
// the actual focus() will be deferred, and if requestFocus() has been
// called for several components, only one of those components will actually
// get a focus() call. By default, last component for which requestFocus() is
// called will get a focus() call, but you can specify arbitrateFocus property
// of a parent View and provide the callback to decide which one of that View's
// descendants should be focused. This is useful for the accessibility: when
// consecutive focus() calls happen one after another, the next one interrupts
// the screen reader announcement for the previous one and the user gets
// confused. autoFocus property of focusable components also uses requestFocus().
requestFocus(): void;
// Gives the control accessibility-only focus
// E.g. screen reader focus is needed, but popping up of native
// keyboard is undesirable
setAccessibilityFocus(): void;
// Does control currently have focus?
isFocused(): boolean;
// Extends selection to include all contents
selectAll(): void;
// Selects a range of text
selectRange(start: number, end: number): void;
// Returns the current selection range
getSelectionRange(): { start: number, end: number };
// Sets the current value
setValue(value: string): void;