Skip to content

Commit 91a4371

Browse files
sgnyMoOx
sgny
authored and
MoOx
committed
Add documentation for Linking API (#519)
1 parent 71d3467 commit 91a4371

1 file changed

Lines changed: 165 additions & 26 deletions

File tree

‎reason-react-native/src/apis/Linking.md‎

Lines changed: 165 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,189 @@
11
---
22
id: apis/Linking
33
title: Linking
4-
wip: true
4+
officialDoc: https://facebook.github.io/react-native/docs/linking.html
55
---
66

7+
Only for projects supporting Native Code. Requires the project to have been
8+
created using `react-native init` or ejected afterwards if created using
9+
`expo init` or `create-react-native-app`.
10+
11+
## Methods
12+
13+
### `openURL`
14+
15+
To attempt opening a URL. URL should be specified as `string`, and the method
16+
returns `unit` wrapped in a promise. Promise is resolved if the user approves
17+
the request (through the _open dialog_) or the link is opened automatically. If
18+
the user rejects the request or there are no registered applications supporting
19+
the URL, the promise is rejected. It is recommended to use the `canOpenURL`
20+
method beforehand, to verify that the URL can indeed be opened.
21+
722
```reason
8-
type extra;
23+
openURL: string => Js.Promise.t(unit)
24+
```
925

10-
[@bs.obj] external extra: (~key: string, ~value: 'a) => extra = "";
26+
### `canOpenURL`
1127

12-
[@bs.scope "Linking"] [@bs.module "react-native"]
13-
external openURL: string => Js.Promise.t(unit) = "";
28+
To determine whether a URL can be opened by registered applications. URL should
29+
be specified as `string`, and the method returns `bool` wrapped in a promise.
30+
The promise will be rejected if it is impossible to check if the URL can be
31+
opened on Android or for iOS 9 and later, an appropriate entry does not exist
32+
for the `LSApplicationQueriesSchemes` key in `Info.plist`.
1433

15-
[@bs.scope "Linking"] [@bs.module "react-native"]
16-
external canOpenURL: string => Js.Promise.t(bool) = "";
34+
```reason
35+
canOpenURL: string => Js.Promise.t(bool)
36+
```
37+
38+
### `getInitialURL`
39+
40+
Returns a nullable string wrapped in a promise. If the app was launched to open
41+
a link, that link will be returned as a `Js.Null(string)` value, otherwise
42+
`Js.null` will be returned.
1743

18-
[@bs.scope "Linking"] [@bs.module "react-native"]
19-
external getInitialURL: unit => Js.Promise.t(Js.Null.t(string)) = "";
44+
```reason
45+
getInitialURL: unit => Js.Promise.t(Js.Null.t(string))
2046
```
2147

22-
As of React Native 0.60
48+
### `openSettings`
49+
50+
_As of React Native 0.60_
51+
52+
Attempts to open the Settings app and display custom settings for the app, if
53+
any. This method returns an unspecified object (type `any`) wrapped in a
54+
promise.
55+
2356
```reason
24-
[@bs.scope "Linking"] [@bs.module "react-native"]
25-
external openSettings: unit => Js.Promise.t('a) = "";
57+
openSettings: unit => Js.Promise.t('a)
2658
```
2759

28-
As of React Native 0.59.8
60+
### `sendIntent`
61+
62+
_As of React Native 0.59.8_
63+
2964
```reason
30-
[@bs.scope "Linking"] [@bs.module "react-native"]
31-
external sendIntent: string => unit = "";
65+
sendIntent: string => unit
3266
```
3367

34-
As of React Native 0.59.8
68+
To use `Intent` actions on Android for sending text to other apps. This method
69+
returns `unit`.
70+
71+
### `sendIntentWithExtras`
72+
73+
_As of React Native 0.59.8_
74+
75+
To use `Intent` actions on Android for sending text and data (to be provided as
76+
an array of type `extra` objects) to other apps. This method returns `unit`.
77+
3578
```reason
36-
[@bs.scope "Linking"] [@bs.module "react-native"]
37-
external sendIntentWithExtras: (string, array(extra)) => unit = "sendIntent";
79+
sendIntentWithExtras: (string, array(extra)) => unit
3880
```
3981

40-
[@bs.scope "Linking"] [@bs.module "react-native"]
41-
external addEventListener:
42-
([@bs.string] [ | `url], {. "url": string} => unit) => unit =
43-
"";
82+
where the type `extra` can be created with the `extra` constructor
83+
84+
```reason
85+
extra: (~key: string, ~value: 'a) => extra
86+
```
87+
88+
### `addEventListener`
89+
90+
To specify a handler for the specified event type. Only the "url" event is
91+
supported, which should be specified using the polymorphic variant `` `url ``.
92+
The handler should be of type `{. "url": string} => unit`. The URL can be
93+
obtained from the returned object using the `##url` accessor. This method
94+
returns `unit`.
95+
96+
```reason
97+
addEventListener: ([ `url], {. "url": string} => unit) => unit
98+
```
99+
100+
### `removeEventListener`
101+
102+
To remove a handler for the specified event type. Only the "url" event is
103+
supported, which should be specified using the polymorphic variant `` `url ``.
104+
The handler should be of type `{. "url": string} => unit`. This method returns
105+
`unit`.
106+
107+
```reason
108+
removeEventListener([ `url], {. "url": string} => unit) => unit
109+
```
110+
111+
### Example
112+
113+
```reason
114+
open ReactNative;
115+
116+
let windowHeight = Dimensions.get(`window)##height;
117+
let windowWidth = Dimensions.get(`window)##width;
118+
119+
let containerStyle =
120+
Style.(
121+
style(
122+
~width=windowWidth->pt,
123+
~height=windowHeight->pt,
124+
~justifyContent=`center,
125+
~alignItems=`center,
126+
(),
127+
)
128+
);
129+
130+
type state = {url: option(string)};
131+
132+
type action =
133+
| SetURL(option(string));
134+
135+
[@react.component]
136+
let make = () => {
137+
let (state, dispatch) =
138+
React.useReducer(
139+
(state, action) =>
140+
switch (action) {
141+
| SetURL(v) => {url: v}
142+
},
143+
{url: None},
144+
);
145+
146+
let handler = s => {
147+
s##url->Js.Console.warn;
148+
};
149+
150+
let handlePromise = url =>
151+
Js.Promise.(
152+
Linking.openURL(url)
153+
|> then_(() => resolve(dispatch(SetURL(Some(url)))))
154+
|> catch(err => resolve(err->Js.Console.warn))
155+
|> ignore
156+
);
157+
158+
// Listener will only receive URLs which your app is
159+
// registered to handle
160+
// https:// resource below will not be captured here
161+
React.useEffect0(() => {
162+
Linking.addEventListener(`url, handler);
163+
Some(() => Linking.removeEventListener(`url, handler));
164+
});
44165
45-
[@bs.scope "Linking"] [@bs.module "react-native"]
46-
external removeEventListener:
47-
([@bs.string] [ | `url], {. "url": string} => unit) => unit =
48-
"";
166+
<View style=containerStyle>
167+
<Text>
168+
{{Belt.Option.getWithDefault(state.url, "No URL requested")}
169+
->React.string}
170+
</Text>
171+
<Button
172+
onPress={_ =>
173+
handlePromise(
174+
"https://github.com/reasonml-community/bs-react-native/",
175+
)
176+
}
177+
title="Open Repo"
178+
/>
179+
// This will only work if you have registered myapp:// as
180+
// custom URL scheme for your app
181+
// Otherwise this will throw an error on the Yellow Box
182+
<Button
183+
onPress={_ => handlePromise("myapp://screen")}
184+
title="Internal URL"
185+
/>
186+
</View>;
187+
};
49188
50189
```

0 commit comments

Comments
 (0)