Skip to content

Commit 55fe11c

Browse files
rubennorterubennorte
committed
Docs for new DOM APIs
1 parent 5a01a22 commit 55fe11c

File tree

5 files changed

+313
-0
lines changed

5 files changed

+313
-0
lines changed

‎docs/document-nodes.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
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 ext=js&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)

‎docs/element-nodes.md‎

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