Skip to content

Commit 322cb1e

Browse files
rubennorterubennorte
committed
Docs for new DOM APIs
1 parent 5a01a22 commit 322cb1e

5 files changed

Lines changed: 309 additions & 0 deletions

File tree

‎docs/document-nodes.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
id: document-nodes
3+
title: Document nodes
4+
---
5+
6+
Document nodes represent a complete native view tree. Apps using native navigation would provide a separate document node for each screen. Apps not using native navigation would generally provide a single document for the whole app (similar to single-page apps on Web).
7+
8+
```SnackPlayer name=Document%20instance%20example
9+
import * as React from 'react';
10+
import {Text, View} from 'react-native';
11+
12+
function countNodes(node) {
13+
let count = 1;
14+
for (const child of node.childNodes) {
15+
count += countNodes(child);
16+
}
17+
return count;
18+
}
19+
20+
export default function AccessingDocument() {
21+
const [nodeCount, setNodeCount] = React.useState(0);
22+
23+
return (
24+
<View ref={instance => {
25+
if (instance != null) {
26+
// or instance.getRootNode()
27+
const document = instance.ownerDocument;
28+
setNodeCount(countNodes(document));
29+
}
30+
}}>
31+
<Text>Number of nodes in tree: {nodeCount}</Text>
32+
</View>
33+
);
34+
}
35+
```
36+
37+
---
38+
39+
## Reference
40+
41+
### Web-compatible API
42+
43+
From [`Document`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement):
44+
45+
- Properties
46+
- [`childElementCount`](https://developer.mozilla.org/en-US/docs/Web/API/Document/childElementCount)
47+
- [`children`](https://developer.mozilla.org/en-US/docs/Web/API/Document/children)
48+
- [`documentElement`](https://developer.mozilla.org/en-US/docs/Web/API/Document/documentElement)
49+
- [`firstElementChild`](https://developer.mozilla.org/en-US/docs/Web/API/Document/firstElementChild)
50+
- [`lastElementChild`](https://developer.mozilla.org/en-US/docs/Web/API/Document/lastElementChild)
51+
- Methods
52+
- [`getElementById`](https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementById)
53+
54+
From [`Node`](https://developer.mozilla.org/en-US/docs/Web/API/Node):
55+
56+
- Properties
57+
- [`childNodes`](https://developer.mozilla.org/en-US/docs/Web/API/Node/childNodes)
58+
- [`firstChild`](https://developer.mozilla.org/en-US/docs/Web/API/Node/firstChild)
59+
- [`isConnected`](https://developer.mozilla.org/en-US/docs/Web/API/Node/isConnected)
60+
- [`lastChild`](https://developer.mozilla.org/en-US/docs/Web/API/Node/lastChild)
61+
- [`nextSibling`](https://developer.mozilla.org/en-US/docs/Web/API/Node/nextSibling)
62+
- [`nodeName`](https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeName)
63+
- [`nodeType`](https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeType)
64+
- [`nodeValue`](https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeValue)
65+
- [`ownerDocument`](https://developer.mozilla.org/en-US/docs/Web/API/Node/ownerDocument)
66+
- [`parentElement`](https://developer.mozilla.org/en-US/docs/Web/API/Node/parentElement)
67+
- [`parentNode`](https://developer.mozilla.org/en-US/docs/Web/API/Node/parentNode)
68+
- [`previousSibling`](https://developer.mozilla.org/en-US/docs/Web/API/Node/previousSibling)
69+
- [`textContent`](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent)
70+
- Methods
71+
- [`compareDocumentPosition`](https://developer.mozilla.org/en-US/docs/Web/API/Node/compareDocumentPosition)
72+
- [`contains`](https://developer.mozilla.org/en-US/docs/Web/API/Node/contains)
73+
- [`getRootNode`](https://developer.mozilla.org/en-US/docs/Web/API/Node/getRootNode)
74+
- [`hasChildNodes`](https://developer.mozilla.org/en-US/docs/Web/API/Node/hasChildNodes)
75+
76+
### Legacy API
77+
78+
- [`measure`](/docs/next/legacy/direct-manipulation#measurecallback)
79+
- [`measureInWindow`](/docs/next/legacy/direct-manipulation#measureinwindowcallback)
80+
- [`measureLayout`](/docs/next/legacy/direct-manipulation#measurelayoutrelativetonativecomponentref-onsuccess-onfail)
81+
- [`setNativeProps`](/docs/next/legacy/direct-manipulation#setnativeprops-with-touchableopacity)

‎docs/element-nodes.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
id: element-nodes
3+
title: Element nodes
4+
---
5+
6+
Element nodes represent native components in the native view tree (similar to [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) nodes on Web).
7+
8+
They are provided by all native components, and by many built-in components, via refs:
9+
10+
```SnackPlayer name=Element%20instances%20example
11+
import * as React from 'react';
12+
import {View, SafeAreaView, StyleSheet, Text} from 'react-native';
13+
14+
const ViewWithRefs = () => {
15+
const [viewInfo, setViewInfo] = React.useState('');
16+
17+
return (
18+
<SafeAreaView style={styles.container}>
19+
<View style={styles.content} ref={instance => {
20+
// `instance` is an object implementing the interface described here,
21+
// or `null` when the component is unmounted.
22+
if (instance != null) {
23+
const rect = JSON.stringify(instance.getBoundingClientRect());
24+
setViewInfo(`Bounding rect is: ${rect}.\nText content is: ${instance.textContent}`);
25+
}
26+
}}>
27+
<Text>Hello world!</Text>
28+
</View>
29+
<Text>{viewInfo}</Text>
30+
</SafeAreaView>
31+
);
32+
};
33+
34+
const styles = StyleSheet.create({
35+
container: {
36+
flex: 1,
37+
},
38+
content: {
39+
padding: 10,
40+
backgroundColor: 'gray',
41+
}
42+
});
43+
44+
export default ViewWithRefs;
45+
```
46+
47+
Note that some built-in components are just a container for other components (including native components). For example, `ScrollView` internally renders a native scroll view and a native view, which are accessible through the ref is provides using methods like `getNativeScrollRef()` and `getInnerViewRef()`.
48+
49+
---
50+
51+
## Reference
52+
53+
### Web-compatible API
54+
55+
From [`HTMLElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement):
56+
57+
- Properties
58+
- [`offsetHeight`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetHeight)
59+
- [`offsetLeft`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetLeft)
60+
- [`offsetParent`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetParent)
61+
- [`offsetTop`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetTop)
62+
- [`offsetWidth`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetWidth)
63+
- Methods
64+
- [`blur`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/blur).
65+
- This method was also [available](/docs/next/legacy/direct-manipulation#blur) in the legacy architecture.
66+
- [`focus`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus).
67+
- This method was also [available](/docs/next/legacy/direct-manipulation#focus) in the legacy architecture.
68+
- The `options` parameter is not supported.
69+
70+
From [`Element`](https://developer.mozilla.org/en-US/docs/Web/API/Element):
71+
72+
- Properties
73+
- [`childElementCount`](https://developer.mozilla.org/en-US/docs/Web/API/Element/childElementCount)
74+
- [`children`](https://developer.mozilla.org/en-US/docs/Web/API/Element/children)
75+
- [`clientHeight`](https://developer.mozilla.org/en-US/docs/Web/API/Element/clientHeight)
76+
- [`clientLeft`](https://developer.mozilla.org/en-US/docs/Web/API/Element/clientLeft)
77+
- [`clientTop`](https://developer.mozilla.org/en-US/docs/Web/API/Element/clientTop)
78+
- [`clientWidth`](https://developer.mozilla.org/en-US/docs/Web/API/Element/clientWidth)
79+
- [`firstElementChild`](https://developer.mozilla.org/en-US/docs/Web/API/Element/firstElementChild)
80+
- [`id`](https://developer.mozilla.org/en-US/docs/Web/API/Element/id)
81+
- Returns the value of the `id` or `nativeID` props.
82+
- [`lastElementChild`](https://developer.mozilla.org/en-US/docs/Web/API/Element/lastElementChild)
83+
- [`nextElementSibling`](https://developer.mozilla.org/en-US/docs/Web/API/Element/nextElementSibling)
84+
- [`nodeName`](https://developer.mozilla.org/en-US/docs/Web/API/Element/nodeName)
85+
- [`nodeType`](https://developer.mozilla.org/en-US/docs/Web/API/Element/nodeType)
86+
- [`nodeValue`](https://developer.mozilla.org/en-US/docs/Web/API/Element/nodeValue)
87+
- [`previousElementSibling`](https://developer.mozilla.org/en-US/docs/Web/API/Element/previousElementSibling)
88+
- [`scrollHeight`](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollHeight)
89+
- [`scrollLeft`](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollLeft)
90+
- For built-in components, only `ScrollView` instances can return a value other than zero.
91+
- [`scrollTop`](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollTop)
92+
- For built-in components, only `ScrollView` instances can return a value other than zero.
93+
- [`scrollWidth`](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollWidth)
94+
- [`tagName`](https://developer.mozilla.org/en-US/docs/Web/API/Element/tagName)
95+
- Returns a normalized native component name prefixed with `RN:`, like `RN:View`.
96+
- [`textContent`](https://developer.mozilla.org/en-US/docs/Web/API/Element/textContent)
97+
- Methods
98+
- [`getBoundingClientRect`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect)
99+
- [`hasPointerCapture`](https://developer.mozilla.org/en-US/docs/Web/API/Element/hasPointerCapture)
100+
- [`setPointerCapture`](https://developer.mozilla.org/en-US/docs/Web/API/Element/setPointerCapture)
101+
- [`releasePointerCapture`](https://developer.mozilla.org/en-US/docs/Web/API/Element/releasePointerCapture)
102+
103+
From [`Node`](https://developer.mozilla.org/en-US/docs/Web/API/Node):
104+
105+
- Properties
106+
- [`childNodes`](https://developer.mozilla.org/en-US/docs/Web/API/Node/childNodes)
107+
- [`firstChild`](https://developer.mozilla.org/en-US/docs/Web/API/Node/firstChild)
108+
- [`isConnected`](https://developer.mozilla.org/en-US/docs/Web/API/Node/isConnected)
109+
- [`lastChild`](https://developer.mozilla.org/en-US/docs/Web/API/Node/lastChild)
110+
- [`nextSibling`](https://developer.mozilla.org/en-US/docs/Web/API/Node/nextSibling)
111+
- [`nodeName`](https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeName)
112+
- [`nodeType`](https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeType)
113+
- [`nodeValue`](https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeValue)
114+
- [`ownerDocument`](https://developer.mozilla.org/en-US/docs/Web/API/Node/ownerDocument)
115+
- Will return the [document instance](/docs/next/document-instances) where this component was rendered.
116+
- [`parentElement`](https://developer.mozilla.org/en-US/docs/Web/API/Node/parentElement)
117+
- [`parentNode`](https://developer.mozilla.org/en-US/docs/Web/API/Node/parentNode)
118+
- [`previousSibling`](https://developer.mozilla.org/en-US/docs/Web/API/Node/previousSibling)
119+
- [`textContent`](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent)
120+
- Methods
121+
- [`compareDocumentPosition`](https://developer.mozilla.org/en-US/docs/Web/API/Node/compareDocumentPosition)
122+
- [`contains`](https://developer.mozilla.org/en-US/docs/Web/API/Node/contains)
123+
- [`getRootNode`](https://developer.mozilla.org/en-US/docs/Web/API/Node/getRootNode)
124+
- [`hasChildNodes`](https://developer.mozilla.org/en-US/docs/Web/API/Node/hasChildNodes)
125+
126+
### Legacy API
127+
128+
- [`measure`](/docs/next/legacy/direct-manipulation#measurecallback)
129+
- [`measureInWindow`](/docs/next/legacy/direct-manipulation#measureinwindowcallback)
130+
- [`measureLayout`](/docs/next/legacy/direct-manipulation#measurelayoutrelativetonativecomponentref-onsuccess-onfail)
131+
- [`setNativeProps`](/docs/next/legacy/direct-manipulation#setnativeprops-with-touchableopacity)

‎docs/nodes.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
id: nodes
3+
title: Nodes from refs
4+
---
5+
6+
React Native apps render a native view tree that represents the UI, similar to how React DOM does on Web (the DOM tree). React Native provides imperative access to this tree via [refs](https://react.dev/learn/manipulating-the-dom-with-refs), which are returned by all native components (including those rendered by built-in components like [`View`](/docs/next/view)).
7+
8+
React Native provides 3 types of nodes:
9+
10+
- [Elements](/docs/next/element-nodes): element nodes represent native components in the native view tree (similar to [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) nodes on Web). They are provided by all native components via refs.
11+
- [Text](/docs/next/text-nodes): text nodes represent raw text content on the tree (similar to [`Text`](https://developer.mozilla.org/en-US/docs/Web/API/Text) nodes on Web). They are not directly accessible via `refs`, but can be accessed using methods like [`childNodes`](https://developer.mozilla.org/en-US/docs/Web/API/Node/childNodes) on element refs.
12+
- [Documents](/docs/next/document-nodes): document nodes represent a complete native view tree (similar to [`Document`](https://developer.mozilla.org/en-US/docs/Web/API/Document) nodes on Web). Like text nodes, they can only be accessed through other nodes, using properties like [`ownerDocument`](https://developer.mozilla.org/en-US/docs/Web/API/Node/ownerDocument).
13+
14+
As on Web, these nodes can be used to traverse the rendered UI tree, access layout information or execute imperative operations like `focus`. **Unlike on Web, they do not allow mutation** (e.g.: [`node.appendChild`](https://developer.mozilla.org/en-US/docs/Web/API/Node/appendChild)), as the tree contents are fully managed by the React renderer.

‎docs/text-nodes.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
id: text-nodes
3+
title: Text nodes
4+
---
5+
6+
Text nodes represent raw text content on the tree (similar to [`Text`](https://developer.mozilla.org/en-US/docs/Web/API/Text) nodes on Web). They are not directly accessible via `refs`, but can be accessed using methods like [`childNodes`](https://developer.mozilla.org/en-US/docs/Web/API/Node/childNodes) on element refs.
7+
8+
```SnackPlayer name=Element%20instances%20example
9+
import * as React from 'react';
10+
import {View, SafeAreaView, StyleSheet, Text} from 'react-native';
11+
12+
const ViewWithRefs = () => {
13+
const [viewInfo, setViewInfo] = React.useState('');
14+
15+
return (
16+
<SafeAreaView style={styles.container}>
17+
<View style={styles.content} ref={instance => {
18+
// `instance` is an object implementing the interface described here,
19+
// or `null` when the component is unmounted.
20+
if (instance != null) {
21+
const rect = JSON.stringify(instance.getBoundingClientRect());
22+
setViewInfo(`Bounding rect is: ${rect}.\nText content is: ${instance.textContent}`);
23+
}
24+
}}>
25+
<Text>Hello world!</Text>
26+
</View>
27+
<Text>{viewInfo}</Text>
28+
</SafeAreaView>
29+
);
30+
};
31+
32+
const styles = StyleSheet.create({
33+
container: {
34+
flex: 1,
35+
},
36+
content: {
37+
padding: 10,
38+
backgroundColor: 'gray',
39+
}
40+
});
41+
42+
export default ViewWithRefs;
43+
```
44+
45+
---
46+
47+
## Reference
48+
49+
### Web-compatible API
50+
51+
From [`CharacterData`](https://developer.mozilla.org/en-US/docs/Web/API/CharacterData):
52+
53+
- Properties
54+
- [`data`](https://developer.mozilla.org/en-US/docs/Web/API/CharacterData/data)
55+
- [`length`](https://developer.mozilla.org/en-US/docs/Web/API/CharacterData/length)
56+
- [`nextElementSibling`](https://developer.mozilla.org/en-US/docs/Web/API/CharacterData/nextElementSibling)
57+
- [`previousElementSibling`](https://developer.mozilla.org/en-US/docs/Web/API/CharacterData/previousElementSibling)
58+
- Methods
59+
- [`substringData`](https://developer.mozilla.org/en-US/docs/Web/API/CharacterData/substringData)
60+
61+
From [`Node`](https://developer.mozilla.org/en-US/docs/Web/API/Node):
62+
63+
- Properties
64+
- [`childNodes`](https://developer.mozilla.org/en-US/docs/Web/API/Node/childNodes)
65+
- [`firstChild`](https://developer.mozilla.org/en-US/docs/Web/API/Node/firstChild)
66+
- [`isConnected`](https://developer.mozilla.org/en-US/docs/Web/API/Node/isConnected)
67+
- [`lastChild`](https://developer.mozilla.org/en-US/docs/Web/API/Node/lastChild)
68+
- [`nextSibling`](https://developer.mozilla.org/en-US/docs/Web/API/Node/nextSibling)
69+
- [`nodeName`](https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeName)
70+
- [`nodeType`](https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeType)
71+
- [`nodeValue`](https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeValue)
72+
- [`ownerDocument`](https://developer.mozilla.org/en-US/docs/Web/API/Node/ownerDocument)
73+
- Will return the [document instance](/docs/next/document-instances) where this component was rendered.
74+
- [`parentElement`](https://developer.mozilla.org/en-US/docs/Web/API/Node/parentElement)
75+
- [`parentNode`](https://developer.mozilla.org/en-US/docs/Web/API/Node/parentNode)
76+
- [`previousSibling`](https://developer.mozilla.org/en-US/docs/Web/API/Node/previousSibling)
77+
- [`textContent`](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent)
78+
- Methods
79+
- [`compareDocumentPosition`](https://developer.mozilla.org/en-US/docs/Web/API/Node/compareDocumentPosition)
80+
- [`contains`](https://developer.mozilla.org/en-US/docs/Web/API/Node/contains)
81+
- [`getRootNode`](https://developer.mozilla.org/en-US/docs/Web/API/Node/getRootNode)
82+
- [`hasChildNodes`](https://developer.mozilla.org/en-US/docs/Web/API/Node/hasChildNodes)

‎website/sidebars.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -277,6 +277,7 @@ export default {
277277
items: ['inputaccessoryview', 'safeareaview'],
278278
},
279279
],
280+
Refs: ['nodes', 'element-nodes', 'text-nodes', 'document-nodes'],
280281
Props: [
281282
'image-style-props',
282283
'layout-props',

0 commit comments

Comments
 (0)