From d5918ff018d4b80421e20dbf605029fc8e06feab Mon Sep 17 00:00:00 2001 From: Bartosz Kaszubowski Date: Thu, 10 Sep 2020 18:26:54 +0200 Subject: [PATCH] update Text page, add types, add LayoutEvent object page --- docs/image.md | 8 +- docs/layoutevent.md | 72 ++++++ docs/text.md | 370 ++++++++++++++++--------------- docs/textinput.md | 8 +- docs/touchablewithoutfeedback.md | 10 +- docs/view.md | 10 +- website/i18n/en.json | 3 + website/sidebars.json | 8 +- 8 files changed, 289 insertions(+), 200 deletions(-) create mode 100644 docs/layoutevent.md diff --git a/docs/image.md b/docs/image.md index 9482e37b90b..c4115bd4a7b 100644 --- a/docs/image.md +++ b/docs/image.md @@ -341,11 +341,11 @@ Invoked on load error with `{nativeEvent: {error}}`. ### `onLayout` -Invoked on mount and layout changes with `{nativeEvent: {layout: {x, y, width, height}}}`. +Invoked on mount and on layout changes. -| Type | Required | -| -------- | -------- | -| function | No | +| Type | Required | +| ------------------------------------ | -------- | +| ([LayoutEvent](layoutevent)) => void | No | --- diff --git a/docs/layoutevent.md b/docs/layoutevent.md new file mode 100644 index 00000000000..b0fda8501db --- /dev/null +++ b/docs/layoutevent.md @@ -0,0 +1,72 @@ +--- +id: layoutevent +title: LayoutEvent Object Type +--- + +`LayoutEvent` object is returned in the callback as a result of component layout change, for example `onLayout` in [View](view) component. + +## Example + +```js +{ + layout: { + width: 520, + height: 70.5, + x: 0, + y: 42.5 + }, + target: 1127 +} +``` + +## Keys and values + +### `height` + +Height of the component after the layout changes. + +| Type | Optional | +| ------ | -------- | +| number | No | + +### `width` + +Width of the component after the layout changes. + +| Type | Optional | +| ------ | -------- | +| number | No | + +### `x` + +Component X coordinate inside the parent component. + +| Type | Optional | +| ------ | -------- | +| number | No | + +### `y` + +Component Y coordinate inside the parent component. + +| Type | Optional | +| ------ | -------- | +| number | No | + +### `target` + +The node id of the element receiving the PressEvent. + +| Type | Optional | +| --------------------------- | -------- | +| number, `null`, `undefined` | No | + +## Used by + +- [`Image`](image) +- [`Pressable`](pressable) +- [`ScrollView`](scrollview) +- [`Text`](text) +- [`TextInput`](textinput) +- [`TouchableWithoutFeedback`](touchablewithoutfeedback) +- [`View`](view) diff --git a/docs/text.md b/docs/text.md index 8286d814dfd..3925a69d41b 100644 --- a/docs/text.md +++ b/docs/text.md @@ -26,14 +26,14 @@ In the following example, the nested title and body text will inherit the `fontF import React, { useState } from "react"; import { Text, StyleSheet } from "react-native"; -const onPressTitle = () => { - console.log("title pressed"); -}; - const TextInANest = () => { - const titleText = useState("Bird's Nest"); + const [titleText, setTitleText] = useState("Bird's Nest"); const bodyText = useState("This is not really a bird nest."); + const onPressTitle = () => { + setTitleText("Bird's Nest [pressed]"); + }; + return ( @@ -57,7 +57,6 @@ const styles = StyleSheet.create({ }); export default TextInANest; - ``` @@ -75,10 +74,17 @@ class TextInANest extends Component { }; } + onPressTitle = () => { + this.setState({ titleText: "Bird's Nest [pressed]" }); + }; + render() { return ( - + {this.state.titleText} {"\n"} {"\n"} @@ -256,9 +262,9 @@ We believe that this more constrained way to style text will yield better apps: An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label. -| Type | Required | -| ------ | -------- | -| string | No | +| Type | +| ------ | +| string | --- @@ -266,9 +272,9 @@ An accessibility hint helps users understand what will happen when they perform Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the `Text` nodes separated by space. -| Type | Required | -| ------ | -------- | -| string | No | +| Type | +| ------ | +| string | --- @@ -276,27 +282,13 @@ Overrides the text that's read by the screen reader when the user interacts with 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 | +| Type | +| ---------------------------------------------------- | +| [AccessibilityRole](accessibility#accessibilityrole) | --- @@ -306,76 +298,73 @@ Tells the screen reader to treat the currently focused on element as being in a 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 | +| Type | +| ------------------------------------------------------ | +| [AccessibilityState](accessibility#accessibilitystate) | --- ### `accessible` -When set to `true`, indicates that the view is an accessibility element. The default value for a `Text` element is `true`. +When set to `true`, indicates that the view is an accessibility element. -See the [Accessibility guide](accessibility.md#accessible-ios-android) for more information. +See the [Accessibility guide](accessibility#accessible-ios-android) for more information. -| Type | Required | -| ---- | -------- | -| bool | No | +| Type | Default | +| ------- | ------- | +| boolean | `true` | --- -### `adjustsFontSizeToFit` +### `adjustsFontSizeToFit`
iOS
Specifies whether fonts should be scaled down automatically to fit given style constraints. -| Type | Required | Platform | -| ---- | -------- | -------- | -| bool | No | iOS | +| Type | Default | +| ------- | ------- | +| boolean | `false` | --- ### `allowFontScaling` -Specifies whether fonts should scale to respect Text Size accessibility settings. The default is `true`. +Specifies whether fonts should scale to respect Text Size accessibility settings. -| Type | Required | -| ---- | -------- | -| bool | No | +| Type | Default | +| ------- | ------- | +| boolean | `true` | --- -### `dataDetectorType` +### `android_hyphenationFrequency`
Android
-Determines the types of data converted to clickable URLs in the text element. By default no data types are detected. +Sets the frequency of automatic hyphenation to use when determining word breaks on Android API Level 23+. -You can provide only one type. +| Type | Default | +| ------------------------------------------------ | -------- | +| enum(`'none'`, `'full'`, `'balanced'`, `'high'`) | `'none'` | -Possible values for `dataDetectorType` are: +--- -- `'phoneNumber'` -- `'link'` -- `'email'` -- `'none'` -- `'all'` +### `dataDetectorType`
Android
-| Type | Required | Platform | -| --------------------------------------------------- | -------- | -------- | -| enum('phoneNumber', 'link', 'email', 'none', 'all') | No | Android | +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. + +| Type | Default | +| ------------------------------------------------------------- | -------- | +| enum(`'phoneNumber'`, `'link'`, `'email'`, `'none'`, `'all'`) | `'none'` | --- -### `disabled` +### `disabled`
Android
-Specifies the disabled state of the text view for testing purposes +Specifies the disabled state of the text view for testing purposes. -| Type | Required | Platform | -| ---- | -------- | -------- | -| bool | No | Android | +| Type | Default | +| ---- | ------- | +| bool | `false` | --- @@ -390,11 +379,9 @@ This can be one of the following values: - `tail` - The line is displayed so that the beginning fits in the container and the missing text at the end of the line is indicated by an ellipsis glyph. e.g., "abcd..." - `clip` - Lines are not drawn past the edge of the text container. -The default is `tail`. - -| Type | Required | -| -------------------------------------- | -------- | -| enum('head', 'middle', 'tail', 'clip') | No | +| Type | Default | +| ---------------------------------------------- | ------- | +| enum(`'head'`, `'middle'`, `'tail'`, `'clip'`) | `tail` | --- @@ -402,23 +389,23 @@ The default is `tail`. 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) +- `null/undefined`: 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 | +| Type | Default | +| ------ | ----------- | +| number | `undefined` | --- -### `minimumFontScale` +### `minimumFontScale`
iOS
-Specifies smallest possible scale a font can reach when adjustsFontSizeToFit is enabled. (values 0.01-1.0). +Specifies smallest possible scale a font can reach when `adjustsFontSizeToFit` is enabled. (values 0.01-1.0). -| Type | Required | Platform | -| ------ | -------- | -------- | -| number | No | iOS | +| Type | +| ------ | +| number | --- @@ -426,33 +413,31 @@ Specifies smallest possible scale a font can reach when adjustsFontSizeToFit is Used to locate this view from native code. -| Type | Required | -| ------ | -------- | -| string | No | +| Type | +| ------ | +| string | --- ### `numberOfLines` -Used to truncate the text with an ellipsis after computing the text layout, including line wrapping, such that the total number of lines does not exceed this number. +Used to truncate the text with an ellipsis after computing the text layout, including line wrapping, such that the total number of lines does not exceed this number. Setting this property to `0` will result in unsetiing this value, which means that no lines restriction will be applied. This prop is commonly used with `ellipsizeMode`. -| Type | Required | -| ------ | -------- | -| number | No | +| Type | Default | +| ------ | ------- | +| number | `0` | --- ### `onLayout` -Invoked on mount and layout changes with +Invoked on mount and on layout changes. -`{nativeEvent: {layout: {x, y, width, height}}}` - -| Type | Required | -| -------- | -------- | -| function | No | +| Type | +| ------------------------------------ | +| ([LayoutEvent](layoutevent)) => void | --- @@ -460,11 +445,9 @@ Invoked on mount and layout changes with This function is called on long press. -e.g., `onLongPress={this.increaseSize}>` - -| Type | Required | -| -------- | -------- | -| function | No | +| Type | +| ---------------------------------- | +| ([PressEvent](pressevent)) => void | --- @@ -472,23 +455,19 @@ e.g., `onLongPress={this.increaseSize}>` 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 [PressEvent](pressevent). - -| Type | Required | -| -------- | -------- | -| function | No | +| Type | +| ------------------------------------- | +| ([PressEvent](pressevent)) => boolean | --- ### `onPress` -This function is called on press. The first function argument is an event in form of [PressEvent](pressevent). - -e.g., `onPress={() => console.log('1st')}` +This function is called on press. -| Type | Required | -| -------- | -------- | -| function | No | +| Type | +| ---------------------------------- | +| ([PressEvent](pressevent)) => void | --- @@ -496,11 +475,9 @@ e.g., `onPress={() => console.log('1st')}` 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 [PressEvent](pressevent). - -| Type | Required | -| -------- | -------- | -| function | No | +| Type | +| ---------------------------------- | +| ([PressEvent](pressevent)) => void | --- @@ -508,11 +485,9 @@ The View is now responding for touch events. This is the time to highlight and s The user is moving their finger. -`View.props.onResponderMove: (event) => {}`, where `event` is a [PressEvent](pressevent). - -| Type | Required | -| -------- | -------- | -| function | No | +| Type | +| ---------------------------------- | +| ([PressEvent](pressevent)) => void | --- @@ -520,11 +495,9 @@ The user is moving their finger. Fired at the end of the touch. -`View.props.onResponderRelease: (event) => {}`, where `event` is a [PressEvent](pressevent). - -| Type | Required | -| -------- | -------- | -| function | No | +| Type | +| ---------------------------------- | +| ([PressEvent](pressevent)) => void | --- @@ -532,11 +505,9 @@ Fired at the end of the touch. 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 [PressEvent](pressevent). - -| Type | Required | -| -------- | -------- | -| function | No | +| Type | +| ---------------------------------- | +| ([PressEvent](pressevent)) => void | --- @@ -544,11 +515,9 @@ The responder has been taken from the `View`. Might be taken by other views afte 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 [PressEvent](pressevent). - -| Type | Required | -| -------- | -------- | -| function | No | +| Type | +| ------------------------------------- | +| ([PressEvent](pressevent)) => boolean | --- @@ -556,24 +525,19 @@ Some other `View` wants to become responder and is asking this `View` to release 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 [PressEvent](pressevent). - -| Type | Required | -| -------- | -------- | -| function | No | +| Type | +| ------------------------------------- | +| ([PressEvent](pressevent)) => boolean | --- ### `onTextLayout` -Invoked on Text layout - -| Type | Required | -| ------------------------------------------- | -------- | -| function: (event: TextLayoutEvent) => mixed | No | +Invoked on Text layout change. -- TextLayoutEvent - SyntheticEvent object that contains a key called `lines` with a value which is an array containing objects with the following properties - - { x: number, y: number, width: number, height: number, ascender: number, capHeight: number, descender: number, text: string, xHeight: number,} +| Type | +| ---------------------------------------------------- | +| ([`TextLayoutEvent`](text#textlayoutevent)) => mixed | --- @@ -581,9 +545,9 @@ Invoked on Text layout 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. -| Type | Required | -| ---------------------- | -------- | -| [Rect](rect) or number | No | +| Type | +| -------------------- | +| [Rect](rect), number | --- @@ -591,37 +555,37 @@ When the scroll view is disabled, this defines how far your touch may move off o Lets the user select text, to use the native copy and paste functionality. -| Type | Required | -| ---- | -------- | -| bool | No | +| Type | Default | +| ------- | ------- | +| boolean | `false` | --- -### `selectionColor` +### `selectionColor`
Android
The highlight color of the text. -| Type | Required | Platform | -| ------------------ | -------- | -------- | -| [color](colors.md) | No | Android | +| Type | +| --------------- | +| [color](colors) | --- ### `style` -| Type | Required | -| -------------------------------------------------------------------------------- | -------- | -| [Text Style Props](text-style-props.md), [View Style Props](view-style-props.md) | No | +| Type | +| -------------------------------------------------------------------------- | +| [Text Style Props](text-style-props), [View Style Props](view-style-props) | --- -### `suppressHighlighting` +### `suppressHighlighting`
iOS
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 | +| Type | Default | +| ------- | ------- | +| boolean | `false` | --- @@ -629,29 +593,77 @@ When `true`, no visual change is made when text is pressed down. By default, a g Used to locate this view in end-to-end tests. -| Type | Required | -| ------ | -------- | -| string | No | +| Type | +| ------ | +| string | --- -### `textBreakStrategy` +### `textBreakStrategy`
Android
-Set text break strategy on Android API Level 23+, possible values are `simple`, `highQuality`, `balanced` The default value is `highQuality`. +Set text break strategy on Android API Level 23+, possible values are `simple`, `highQuality`, `balanced`. -| Type | Required | Platform | -| ----------------------------------------- | -------- | -------- | -| enum('simple', 'highQuality', 'balanced') | No | Android | +| Type | Default | +| ----------------------------------------------- | ------------- | +| enum(`'simple'`, `'highQuality'`, `'balanced'`) | `highQuality` | ---- +## Type Definitions + +### TextLayout + +`TextLayout` object is a part of [`TextLayoutEvent`](text#textlayoutevent) callback and contains the measurement data for `Text` line. -### `android_hyphenationFrequency` +#### Example + +```js +{ + capHeight: 10.496, + ascender: 14.624, + descender: 4, + width: 28.224, + height: 18.624, + xHeight: 6.048, + x: 0, + y: 0 +} +``` + +#### Properties + +| Name | Type | Optional | Description | +| --------- | ------ | -------- | ------------------------------------------------------------------- | +| ascender | number | No | The line ascender height after the text layout changes. | +| capHeight | number | No | Height of capital letter above the baseline. | +| descender | number | No | The line descender height after the text layout changes. | +| height | number | No | Height of the line after the text layout changes. | +| width | number | No | Width of the line after the text layout changes. | +| x | number | No | Line X coordinate inside the Text component. | +| xHeight | number | No | Distance between the baseline and median of the line (corpus size). | +| y | number | No | Line Y coordinate inside the Text component. | + +### TextLayoutEvent + +`TextLayoutEvent` object is returned in the callback as a result of component layout change. It contains a key called `lines` with a value which is an array containing [`TextLayout`](text#textlayout) object corresponeded to every rendered text line. + +#### Example + +```js +{ + lines: [ + TextLayout, + TextLayout + // ... + ]; + target: 1127; +} +``` -Sets the frequency of automatic hyphenation to use when determining word breaks on Android API Level 23+, possible values are `none`, `full`, `balanced`, `high`, `normal`. The default value is `none`. +#### Properties -| Type | Required | Platform | -| ---------------------------------------- | -------- | -------- | -| enum('none', 'full', 'balanced', 'high') | No | Android | +| Name | Type | Optional | Description | +| ------ | --------------------------------------- | -------- | ----------------------------------------------------- | +| lines | array of [TextLayout](text#textlayout)s | No | Provides the TextLayout data for every rendered line. | +| target | number | No | The node id of the element. | # Known issues diff --git a/docs/textinput.md b/docs/textinput.md index 69bdf4535c0..98fc3a747a9 100644 --- a/docs/textinput.md +++ b/docs/textinput.md @@ -505,9 +505,9 @@ Callback that is called when a touch is released. Callback that is called when the text input is focused. This is called with `{ nativeEvent: { target } }`. -| Type | Required | -| -------- | -------- | -| function | No | +| Type | Required | +| ------------------------------------ | -------- | +| ([LayoutEvent](layoutevent)) => void | No | --- @@ -523,7 +523,7 @@ Callback that is called when a key is pressed. This will be called with `{ nativ ### `onLayout` -Invoked on mount and layout changes with `{ nativeEvent: {layout: {x, y, width, height}, target } }`. +Invoked on mount and on layout changes. | Type | Required | | -------- | -------- | diff --git a/docs/touchablewithoutfeedback.md b/docs/touchablewithoutfeedback.md index 7df5754dc56..9be24a5f81e 100644 --- a/docs/touchablewithoutfeedback.md +++ b/docs/touchablewithoutfeedback.md @@ -279,13 +279,11 @@ Invoked when the item receives focus. ### `onLayout` -Invoked on mount and layout changes with +Invoked on mount and on layout changes. -`{nativeEvent: {layout: {x, y, width, height}}}` - -| Type | Required | -| -------- | -------- | -| function | No | +| Type | Required | +| ------------------------------------ | -------- | +| ([LayoutEvent](layoutevent)) => void | No | --- diff --git a/docs/view.md b/docs/view.md index c82317c7d8e..cf1fe16d0ae 100644 --- a/docs/view.md +++ b/docs/view.md @@ -345,15 +345,13 @@ Used to locate this view from native classes. ### `onLayout` -Invoked on mount and layout changes with: - -`{nativeEvent: { layout: {x, y, width, height}}}` +Invoked on mount and on layout changes. This event is fired immediately once the layout has been calculated, but the new layout may not yet be reflected on the screen at the time the event is received, especially if a layout animation is in progress. -| Type | Required | -| -------- | -------- | -| function | No | +| Type | Required | +| ------------------------------------ | -------- | +| ([LayoutEvent](layoutevent)) => void | No | --- diff --git a/website/i18n/en.json b/website/i18n/en.json index be53588bf2b..692c4c84a74 100644 --- a/website/i18n/en.json +++ b/website/i18n/en.json @@ -194,6 +194,9 @@ "layoutanimation": { "title": "LayoutAnimation" }, + "layoutevent": { + "title": "LayoutEvent Object Type" + }, "libraries": { "title": "Using Libraries" }, diff --git a/website/sidebars.json b/website/sidebars.json index 589ef7998f4..64f7a6a6499 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -147,6 +147,12 @@ "text-style-props", "view-style-props" ], - "Object Types": ["pressevent", "react-node", "rect", "viewtoken"] + "Object Types": [ + "layoutevent", + "pressevent", + "react-node", + "rect", + "viewtoken" + ] } }