diff --git a/docs/text.md b/docs/text.md index 4f1437d275d..85e40993465 100644 --- a/docs/text.md +++ b/docs/text.md @@ -188,28 +188,38 @@ We believe that this more constrained way to style text will yield better apps: ### Props -- [`selectable`](text.md#selectable) - [`accessibilityHint`](text.md#accessibilityhint) - [`accessibilityLabel`](text.md#accessibilitylabel) +- [`accessibilityRole`](text.md#accessibilityrole) +- [`accessibilityState`](text.md#accessibilitystate) - [`accessible`](text.md#accessible) +- [`adjustsFontSizeToFit`](text.md#adjustsfontsizetofit) +- [`allowFontScaling`](text.md#allowfontscaling) +- [`dataDetectorType`](text.md#datadetectortype) +- [`disabled`](text.md#disabled) - [`ellipsizeMode`](text.md#ellipsizemode) +- [`maxFontSizeMultiplier`](text.md#maxfontsizemultiplier) +- [`minimumFontScale`](text.md#minimumfontscale) - [`nativeID`](text.md#nativeid) - [`numberOfLines`](text.md#numberoflines) - [`onLayout`](text.md#onlayout) - [`onLongPress`](text.md#onlongpress) +- [`onMoveShouldSetResponder`](text.md#onmoveshouldsetresponder) - [`onPress`](text.md#onpress) +- [`onResponderGrant`](text.md#onrespondergrant) +- [`onResponderMove`](text.md#onrespondermove) +- [`onResponderRelease`](text.md#onresponderrelease) +- [`onResponderTerminate`](text.md#onresponderterminate) +- [`onResponderTerminationRequest`](text.md#onresponderterminationrequest) +- [`onStartShouldSetResponder`](text.md#onstartshouldsetresponder) +- [`onTextLayout`](text.md#ontextlayout) - [`pressRetentionOffset`](text.md#pressretentionoffset) -- [`allowFontScaling`](text.md#allowfontscaling) -- [`maxFontSizeMultiplier`](text.md#maxfontsizemultiplier) +- [`selectable`](text.md#selectable) +- [`selectionColor`](text.md#selectioncolor) - [`style`](text.md#style) +- [`suppressHighlighting`](text.md#suppresshighlighting) - [`testID`](text.md#testid) -- [`disabled`](text.md#disabled) -- [`selectionColor`](text.md#selectioncolor) - [`textBreakStrategy`](text.md#textbreakstrategy) -- [`adjustsFontSizeToFit`](text.md#adjustsfontsizetofit) -- [`minimumFontScale`](text.md#minimumfontscale) -- [`suppressHighlighting`](text.md#suppresshighlighting) -- [`dataDetectorType`](text.md#datadetectortype) --- @@ -217,16 +227,6 @@ We believe that this more constrained way to style text will yield better apps: ## Props -### `selectable` - -Lets the user select text, to use the native copy and paste functionality. - -| Type | Required | -| ---- | -------- | -| bool | No | - ---- - ### `accessibilityHint` An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not obvious from the accessibility label. @@ -247,6 +247,51 @@ Overrides the text that's read by the screen reader when the user interacts with --- +### `accessibilityRole` + +Tells the screen reader to treat the currently focused on element as having a specific role. + +Possible values for `AccessibilityRole` is one of: + +- `'none'` - The element has no role. +- `'button'` - The element should be treated as a button. +- `'link'` - The element should be treated as a link. +- `'header'` - The element is a header that divides content into sections. +- `'search'` - The element should be treated as a search field. +- `'image'` - The element should be treated as an image. +- `'key'` - The element should be treated like a keyboard key. +- `'text'` - The element should be treated as text. +- `'summary'` - The element provides app summary information. +- `'imagebutton'` - The element has the role of both an image and also a button. +- `'adjustable'` - The element allows adjustment over a range of values. + +On iOS, these roles map to corresponding Accessibility Traits. Image button has the same functionality as if the trait was set to both 'image' and 'button'. See the [Accessibility guide](accessibility.md#accessibilitytraits-ios) for more information. + +On Android, these roles have similar functionality on TalkBack as adding Accessibility Traits does on Voiceover in iOS + +| Type | Required | +| ----------------- | -------- | +| AccessibilityRole | No | + +--- + +### `accessibilityState` + +Tells the screen reader to treat the currently focused on element as being in a specific state. + +You can provide one state, no state, or multiple states. The states must be passed in through an object. Ex: `{selected: true, disabled: true}`. + +Possible values for `AccessibilityState` are: + +- `'selected'` - The element is in a selected state. +- `'disabled'` - The element is in a disabled state. + +| Type | Required | +| ------ | -------- | +| object | No | + +--- + ### `accessible` When set to `true`, indicates that the view is an accessibility element. The default value for a `Text` element is `true`. @@ -259,6 +304,56 @@ See the [Accessibility guide](accessibility.md#accessible-ios-android) for more --- +### `adjustsFontSizeToFit` + +Specifies whether fonts should be scaled down automatically to fit given style constraints. + +| Type | Required | Platform | +| ---- | -------- | -------- | +| bool | No | iOS | + +--- + +### `allowFontScaling` + +Specifies whether fonts should scale to respect Text Size accessibility settings. The default is `true`. + +| Type | Required | +| ---- | -------- | +| bool | No | + +--- + +### `dataDetectorType` + +Determines the types of data converted to clickable URLs in the text element. By default no data types are detected. + +You can provide only one type. + +Possible values for `dataDetectorType` are: + +- `'phoneNumber'` +- `'link'` +- `'email'` +- `'none'` +- `'all'` + +| Type | Required | Platform | +| --------------------------------------------------- | -------- | -------- | +| enum('phoneNumber', 'link', 'email', 'none', 'all') | No | Android | + +--- + +### `disabled` + +Specifies the disabled state of the text view for testing purposes + +| Type | Required | Platform | +| ---- | -------- | -------- | +| bool | No | Android | + +--- + ### `ellipsizeMode` When `numberOfLines` is set, this prop defines how text will be truncated. `numberOfLines` must be set in conjunction with this prop. @@ -278,6 +373,30 @@ The default is `tail`. --- +### `maxFontSizeMultiplier` + +Specifies largest possible scale a font can reach when `allowFontScaling` is enabled. Possible values: + +- `null/undefined` (default): inherit from the parent node or the global default (0) +- `0`: no max, ignore parent/global default +- `>= 1`: sets the `maxFontSizeMultiplier` of this node to this value + +| Type | Required | +| ------ | -------- | +| number | No | + +--- + +### `minimumFontScale` + +Specifies smallest possible scale a font can reach when adjustsFontSizeToFit is enabled. (values 0.01-1.0). + +| Type | Required | Platform | +| ------ | -------- | -------- | +| number | No | iOS | + +--- + ### `nativeID` Used to locate this view from native code. @@ -324,6 +443,18 @@ e.g., `onLongPress={this.increaseSize}>` --- +### `onMoveShouldSetResponder` + +Does this view want to "claim" touch responsiveness? This is called for every touch move on the `View` when it is not the responder. + +`View.props.onMoveShouldSetResponder: (event) => [true | false]`, where `event` is a synthetic touch event as described above. + +| Type | Required | +| -------- | -------- | +| function | No | + +--- + ### `onPress` This function is called on press. @@ -336,6 +467,82 @@ e.g., `onPress={() => console.log('1st')}` --- +### `onResponderGrant` + +The View is now responding for touch events. This is the time to highlight and show the user what is happening. + +`View.props.onResponderGrant: (event) => {}`, where `event` is a synthetic touch event as described above. + +| Type | Required | +| -------- | -------- | +| function | No | + +--- + +### `onResponderMove` + +The user is moving their finger. + +`View.props.onResponderMove: (event) => {}`, where `event` is a synthetic touch event as described above. + +| Type | Required | +| -------- | -------- | +| function | No | + +--- + +### `onResponderRelease` + +Fired at the end of the touch. + +`View.props.onResponderRelease: (event) => {}`, where `event` is a synthetic touch event as described above. + +| Type | Required | +| -------- | -------- | +| function | No | + +--- + +### `onResponderTerminate` + +The responder has been taken from the `View`. Might be taken by other views after a call to `onResponderTerminationRequest`, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS) + +`View.props.onResponderTerminate: (event) => {}`, where `event` is a synthetic touch event as described above. + +| Type | Required | +| -------- | -------- | +| function | No | + +--- + +### `onResponderTerminationRequest` + +Some other `View` wants to become responder and is asking this `View` to release its responder. Returning `true` allows its release. + +`View.props.onResponderTerminationRequest: (event) => {}`, where `event` is a synthetic touch event as described above. + +| Type | Required | +| -------- | -------- | +| function | No | + +--- + +### `onStartShouldSetResponderCapture` + +If a parent `View` wants to prevent a child `View` from becoming responder on a touch start, it should have this handler which returns `true`. + +`View.props.onStartShouldSetResponderCapture: (event) => [true | false]`, where `event` is a synthetic touch event as described above. + +| Type | Required | +| -------- | -------- | +| function | No | + +--- + +### `onTextLayout` + +TODO. + ### `pressRetentionOffset` When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations. @@ -346,9 +553,9 @@ When the scroll view is disabled, this defines how far your touch may move off o --- -### `allowFontScaling` +### `selectable` -Specifies whether fonts should scale to respect Text Size accessibility settings. The default is `true`. +Lets the user select text, to use the native copy and paste functionality. | Type | Required | | ---- | -------- | @@ -356,17 +563,13 @@ Specifies whether fonts should scale to respect Text Size accessibility settings --- -### `maxFontSizeMultiplier` - -Specifies largest possible scale a font can reach when `allowFontScaling` is enabled. Possible values: +### `selectionColor` -- `null/undefined` (default): inherit from the parent node or the global default (0) -- `0`: no max, ignore parent/global default -- `>= 1`: sets the `maxFontSizeMultiplier` of this node to this value +The highlight color of the text. -| Type | Required | -| ------ | -------- | -| number | No | +| Type | Required | Platform | +| ------------------ | -------- | -------- | +| [color](colors.md) | No | Android | --- @@ -430,33 +633,23 @@ Specifies largest possible scale a font can reach when `allowFontScaling` is ena --- -### `testID` - -Used to locate this view in end-to-end tests. - -| Type | Required | -| ------ | -------- | -| string | No | - ---- - -### `disabled` +### `suppressHighlighting` -Specifies the disabled state of the text view for testing purposes +When `true`, no visual change is made when text is pressed down. By default, a gray oval highlights the text on press down. | Type | Required | Platform | | ---- | -------- | -------- | -| bool | No | Android | +| bool | No | iOS | --- -### `selectionColor` +### `testID` -The highlight color of the text. +Used to locate this view in end-to-end tests. -| Type | Required | Platform | -| ------------------ | -------- | -------- | -| [color](colors.md) | No | Android | +| Type | Required | +| ------ | -------- | +| string | No | --- @@ -468,56 +661,6 @@ Set text break strategy on Android API Level 23+, possible values are `simple`, | ----------------------------------------- | -------- | -------- | | enum('simple', 'highQuality', 'balanced') | No | Android | ---- - -### `adjustsFontSizeToFit` - -Specifies whether font should be scaled down automatically to fit given style constraints. - -| Type | Required | Platform | -| ---- | -------- | -------- | -| bool | No | iOS | - ---- - -### `minimumFontScale` - -Specifies smallest possible scale a font can reach when adjustsFontSizeToFit is enabled. (values 0.01-1.0). - -| Type | Required | Platform | -| ------ | -------- | -------- | -| number | No | iOS | - ---- - -### `suppressHighlighting` - -When `true`, no visual change is made when text is pressed down. By default, a gray oval highlights the text on press down. - -| Type | Required | Platform | -| ---- | -------- | -------- | -| bool | No | iOS | - # Known issues - [react-native#22811](https://github.com/facebook/react-native/issues/22811): Nested Text elements do not support `numberOfLines` attribute - -### `dataDetectorType` - -Determines the types of data converted to clickable URLs in the text element. By default no data types are detected. - -You can provide only one type. - -Possible values for `dataDetectorType` are: - -- `'phoneNumber'` -- `'link'` -- `'email'` -- `'none'` -- `'all'` - -| Type | Required | Platform | -| --------------------------------------------------- | -------- | -------- | -| enum('phoneNumber', 'link', 'email', 'none', 'all') | No | Android | - ----