From 79e6dbaab536164263fbf90cc0047dcd8ec39f1d Mon Sep 17 00:00:00 2001 From: Nicolas Gallagher Date: Fri, 9 Jun 2017 14:49:15 -0700 Subject: [PATCH] Move 'NativeMethods' docs to direct manipulation guide --- README.md | 1 - docs/apis/NativeMethods.md | 42 ------------------- docs/guides/direct-manipulation.md | 65 ++++++++++++++++++++++++------ 3 files changed, 53 insertions(+), 55 deletions(-) delete mode 100644 docs/apis/NativeMethods.md diff --git a/README.md b/README.md index ba236889..2ff94578 100644 --- a/README.md +++ b/README.md @@ -68,7 +68,6 @@ Exported modules: * [`Clipboard`](docs/apis/Clipboard.md) * [`Dimensions`](docs/apis/Dimensions.md) * [`I18nManager`](docs/apis/I18nManager.md) - * [`NativeMethods`](docs/apis/NativeMethods.md) * [`NetInfo`](docs/apis/NetInfo.md) * [`PanResponder`](http://facebook.github.io/react-native/releases/0.20/docs/panresponder.html#content) (mirrors React Native) * [`PixelRatio`](docs/apis/PixelRatio.md) diff --git a/docs/apis/NativeMethods.md b/docs/apis/NativeMethods.md deleted file mode 100644 index b878c85f..00000000 --- a/docs/apis/NativeMethods.md +++ /dev/null @@ -1,42 +0,0 @@ -# NativeMethods - -React Native for Web provides several methods to directly access the underlying -DOM node. This can be useful in cases when you want to focus a view or measure -its on-screen dimensions, for example. - -The methods described are available on most of the default components provided -by React Native for Web. Note, however, that they are *not* available on the -composite components that you define in your own app. For more information, see -[Direct Manipulation](../guides/direct-manipulation.md). - -## Methods - -**blur**() - -Removes focus from an input or view. This is the opposite of `focus()`. - -**focus**() - -Requests focus for the given input or view. The exact behavior triggered will -depend the type of view. - -**measure**(callback: (x, y, width, height, pageX, pageY) => void) - -For a given view, `measure` determines the offset relative to the parent view, -width, height, and the offset relative to the viewport. Returns the values via -an async callback. - -Note that these measurements are not available until after the rendering has -been completed. - -**measureLayout**(relativeToNativeNode: DOMNode, onSuccess: (x, y, width, height) => void) - -Like `measure`, but measures the view relative to another view, specified as -`relativeToNativeNode`. This means that the returned `x`, `y` are relative to -the origin `x`, `y` of the ancestor view. - -**setNativeProps**(nativeProps: Object) - -This function sends props straight to the underlying DOM node. See the [direct -manipulation](../guides/direct-manipulation.md) guide for cases where -`setNativeProps` should be used. diff --git a/docs/guides/direct-manipulation.md b/docs/guides/direct-manipulation.md index d2778dea..5bd8696b 100644 --- a/docs/guides/direct-manipulation.md +++ b/docs/guides/direct-manipulation.md @@ -1,27 +1,68 @@ # Direct manipulation -It is sometimes necessary to make changes directly to a component without using -state/props to trigger a re-render of the entire subtree – in the browser, this -is done by directly modifying a DOM node. `setNativeProps` is the React Native -equivalent to setting properties directly on a DOM node. Use direct -manipulation when frequent re-rendering creates a performance bottleneck. Direct -manipulation will not be a tool that you reach for frequently. +React Native for Web provides several methods to directly access the underlying +DOM node. This can be useful when you need to make changes directly to a +component without using state/props to trigger a re-render of the entire +subtree, or when you want to focus a view or measure its on-screen dimensions. -## `setNativeProps` and `shouldComponentUpdate` +The methods described are available on most of the default components provided +by React Native for Web. Note, however, that they are *not* available on the +composite components that you define in your own app. + +## Instance methods + +**blur**() + +Removes focus from an input or view. This is the opposite of `focus()`. + +**focus**() + +Requests focus for the given input or view. The exact behavior triggered will +depend the type of view. + +**measure**(callback: (x, y, width, height, pageX, pageY) => void) + +For a given view, `measure` determines the offset relative to the parent view, +width, height, and the offset relative to the viewport. Returns the values via +an async callback. + +Note that these measurements are not available until after the rendering has +been completed. + +**measureLayout**(relativeToNativeNode: DOMNode, onSuccess: (x, y, width, height) => void) + +Like `measure`, but measures the view relative to another view, specified as +`relativeToNativeNode`. This means that the returned `x`, `y` are relative to +the origin `x`, `y` of the ancestor view. + +**setNativeProps**(nativeProps: Object) + +This function sends props straight to the underlying DOM node. See the [direct +manipulation](../guides/direct-manipulation.md) guide for cases where +`setNativeProps` should be used. + +## About `setNativeProps` + +`setNativeProps` is the React Native equivalent to setting properties directly +on a DOM node. Use direct manipulation when frequent re-rendering creates a +performance bottleneck. Direct manipulation will not be a tool that you reach +for frequently. + +### `setNativeProps` and `shouldComponentUpdate` `setNativeProps` is imperative and stores state in the native layer (DOM, UIView, etc.) and not within your React components, which makes your code more difficult to reason about. Before you use it, try to solve your problem with `setState` and `shouldComponentUpdate`. -## Avoiding conflicts with the render function +### Avoiding conflicts with the render function If you update a property that is also managed by the render function, you might end up with some unpredictable and confusing bugs because anytime the component re-renders and that property changes, whatever value was previously set from `setNativeProps` will be completely ignored and overridden. -## Why use `setNativeProps` on Web? +### Why use `setNativeProps` on Web? Using `setNativeProps` in web-specific code is required when making changes to `className` or `style`, as these properties are controlled by React Native for @@ -35,7 +76,7 @@ setOpacityTo(value) { } ``` -## Composite components and `setNativeProps` +### Composite components and `setNativeProps` Composite components are not backed by a DOM node, so you cannot call `setNativeProps` on them. Consider this example: @@ -63,7 +104,7 @@ prop on it and have that work - you would need to pass the style prop down to a child, unless you are wrapping a native component. Similarly, we are going to forward `setNativeProps` to a native-backed child component. -## Forward `setNativeProps` to a child +### Forward `setNativeProps` to a child All we need to do is provide a `setNativeProps` method on our component that calls `setNativeProps` on the appropriate child with the given arguments. @@ -86,7 +127,7 @@ class MyButton extends React.Component { You can now use `MyButton` inside of `TouchableOpacity`! -## `setNativeProps` to clear `TextInput` value +### `setNativeProps` to clear `TextInput` value Another very common use case of `setNativeProps` is to clear the value of a `TextInput`. For example, the following code demonstrates clearing the input