Browse Source

Added first draft of docs folder and documentation

Jamon Holmgren 5 years ago
parent
commit
0ce93a963a
4 changed files with 561 additions and 4 deletions
  1. 4
    4
      README.md
  2. 59
    0
      docs/Getting-Started.md
  3. 5
    0
      docs/Guide.md
  4. 493
    0
      docs/Reference.md

+ 4
- 4
README.md View File

@@ -10,7 +10,7 @@
10 10
 * [x] Android
11 11
 * [ ] Windows 10 (coming soon)
12 12
 
13
-## Installation
13
+## Getting Started
14 14
 
15 15
 *Note: this is currently a work-in-progress and not yet published to NPM.*
16 16
 
@@ -19,6 +19,8 @@ $ npm install --save https://github.com/react-native-community/react-native-webv
19 19
 $ react-native link react-native-webview
20 20
 ```
21 21
 
22
+Read our [Getting Started Guide](./docs/Getting-Started.md) for more.
23
+
22 24
 ## Usage
23 25
 
24 26
 Import the `WebView` component from `react-native-webview` and use it like so:
@@ -41,9 +43,7 @@ class MyWebComponent extends Component {
41 43
 }
42 44
 ```
43 45
 
44
-Additional properties are supported and will be added here; for now, refer to the previous React Native WebView documentation for more.
45
-
46
-[https://facebook.github.io/react-native/docs/webview](https://facebook.github.io/react-native/docs/webview)
46
+For more, read the [API Reference](./docs/Reference.md) and [Guide](./docs/Guide.md).
47 47
 
48 48
 ## Migrate from React Native core WebView to React Native WebView
49 49
 

+ 59
- 0
docs/Getting-Started.md View File

@@ -0,0 +1,59 @@
1
+# React Native WebView Getting Started Guide
2
+
3
+Here's how to get started quickly with the React Native WebView.
4
+
5
+#### 1. Add react-native-webview to your dependencies
6
+
7
+```
8
+$ npm install --save https://github.com/react-native-community/react-native-webview
9
+```
10
+
11
+#### 2. Link native dependencies
12
+
13
+React Native modules that include native Objective-C, Swift, Java, or Kotlin code have to be "linked" so that the compiler knows to include them in the app.
14
+
15
+Thankfully, there's a way to do this from the terminal with one command:
16
+
17
+```
18
+$ react-native link react-native-webview
19
+```
20
+
21
+_NOTE: If you ever need to uninstall React Native WebView, run `react-native unlink react-native-webview` to unlink it._
22
+
23
+#### 3. Import the webview into your component
24
+
25
+```js
26
+import React, { Component } from 'react';
27
+import { WebView } from 'react-native-webview';
28
+
29
+class MyWeb extends Component {
30
+  render() {
31
+    return (
32
+      <WebView
33
+        source={{uri: 'https://infinite.red'}}
34
+        style={{marginTop: 20}}
35
+      />
36
+    );
37
+  }
38
+}
39
+```
40
+
41
+Minimal example with inline HTML:
42
+
43
+```js
44
+import React, { Component } from 'react';
45
+import { WebView } from 'react-native-webview';
46
+
47
+class MyInlineWeb extends Component {
48
+  render() {
49
+    return (
50
+      <WebView
51
+        originWhitelist={['*']}
52
+        source={{ html: '<h1>Hello world</h1>' }}
53
+      />
54
+    );
55
+  }
56
+}
57
+```
58
+
59
+Next, check out the [API Reference](Reference.md) or [In-Depth Guide](Guide.md).

+ 5
- 0
docs/Guide.md View File

@@ -0,0 +1,5 @@
1
+# React Native WebView Guide
2
+
3
+This document walks you through the most common use cases for React Native WebView. It doesn't cover [the full API](Reference.md), but after reading it you should have a good sense for how the WebView works and common patterns for using the WebView.
4
+
5
+_Coming soon!_

+ 493
- 0
docs/Reference.md View File

@@ -0,0 +1,493 @@
1
+# React Native WebView API Reference
2
+
3
+This document lays out the current public properties and methods for the React Native WebView.
4
+
5
+> **Security Warning:** Currently, `onMessage` and `postMessage` do not allow specifying an origin. This can lead to cross-site scripting attacks if an unexpected document is loaded within a `WebView` instance. Please refer to the MDN documentation for [`Window.postMessage()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) for more details on the security implications of this.
6
+
7
+## Props Index
8
+
9
+- [`source`](Reference.md#source)
10
+- [`automaticallyAdjustContentInsets`](Reference.md#automaticallyadjustcontentinsets)
11
+- [`injectJavaScript`](Reference.md#injectjavascript)
12
+- [`injectedJavaScript`](Reference.md#injectedjavascript)
13
+- [`mediaPlaybackRequiresUserAction`](Reference.md#mediaplaybackrequiresuseraction)
14
+- [`nativeConfig`](Reference.md#nativeconfig)
15
+- [`onError`](Reference.md#onerror)
16
+- [`onLoad`](Reference.md#onload)
17
+- [`onLoadEnd`](Reference.md#onloadend)
18
+- [`onLoadStart`](Reference.md#onloadstart)
19
+- [`onMessage`](Reference.md#onmessage)
20
+- [`onNavigationStateChange`](Reference.md#onnavigationstatechange)
21
+- [`originWhitelist`](Reference.md#originwhitelist)
22
+- [`renderError`](Reference.md#rendererror)
23
+- [`renderLoading`](Reference.md#renderloading)
24
+- [`scalesPageToFit`](Reference.md#scalespagetofit)
25
+- [`onShouldStartLoadWithRequest`](Reference.md#onshouldstartloadwithrequest)
26
+- [`startInLoadingState`](Reference.md#startinloadingstate)
27
+- [`style`](Reference.md#style)
28
+- [`decelerationRate`](Reference.md#decelerationrate)
29
+- [`domStorageEnabled`](Reference.md#domstorageenabled)
30
+- [`javaScriptEnabled`](Reference.md#javascriptenabled)
31
+- [`mixedContentMode`](Reference.md#mixedcontentmode)
32
+- [`thirdPartyCookiesEnabled`](Reference.md#thirdpartycookiesenabled)
33
+- [`userAgent`](Reference.md#useragent)
34
+- [`allowsInlineMediaPlayback`](Reference.md#allowsinlinemediaplayback)
35
+- [`bounces`](Reference.md#bounces)
36
+- [`contentInset`](Reference.md#contentinset)
37
+- [`dataDetectorTypes`](Reference.md#datadetectortypes)
38
+- [`scrollEnabled`](Reference.md#scrollenabled)
39
+- [`geolocationEnabled`](Reference.md#geolocationenabled)
40
+- [`allowUniversalAccessFromFileURLs`](Reference.md#allowUniversalAccessFromFileURLs)
41
+- [`useWebKit`](Reference.md#usewebkit)
42
+- [`url`](Reference.md#url)
43
+- [`html`](Reference.md#html)
44
+
45
+## Methods Index
46
+
47
+* [`extraNativeComponentConfig`](Reference.md#extranativecomponentconfig)
48
+* [`goForward`](Reference.md#goforward)
49
+* [`goBack`](Reference.md#goback)
50
+* [`reload`](Reference.md#reload)
51
+* [`stopLoading`](Reference.md#stoploading)
52
+
53
+---
54
+
55
+# Reference
56
+
57
+## Props
58
+
59
+### `source`
60
+
61
+Loads static HTML or a URI (with optional headers) in the WebView. Note that static HTML will require setting [`originWhitelist`](Reference.md#originwhitelist) to `["*"]`.
62
+
63
+The object passed to `source` can have either of the following shapes:
64
+
65
+**Load uri**
66
+
67
+* `uri` (string) - The URI to load in the `WebView`. Can be a local or remote file.
68
+* `method` (string) - The HTTP Method to use. Defaults to GET if not specified. On Android, the only supported methods are GET and POST.
69
+* `headers` (object) - Additional HTTP headers to send with the request. On Android, this can only be used with GET requests.
70
+* `body` (string) - The HTTP body to send with the request. This must be a valid UTF-8 string, and will be sent exactly as specified, with no additional encoding (e.g. URL-escaping or base64) applied. On Android, this can only be used with POST requests.
71
+
72
+**Static HTML**
73
+
74
+* `html` (string) - A static HTML page to display in the WebView.
75
+* `baseUrl` (string) - The base URL to be used for any relative links in the HTML.
76
+
77
+| Type   | Required |
78
+| ------ | -------- |
79
+| object | No       |
80
+
81
+---
82
+
83
+### `automaticallyAdjustContentInsets`
84
+
85
+Controls whether to adjust the content inset for web views that are placed behind a navigation bar, tab bar, or toolbar. The default value is `true`.
86
+
87
+| Type | Required |
88
+| ---- | -------- |
89
+| bool | No       |
90
+
91
+---
92
+
93
+### `injectJavaScript`
94
+
95
+Function that accepts a string that will be passed to the WebView and executed immediately as JavaScript.
96
+
97
+| Type     | Required |
98
+| -------- | -------- |
99
+| function | No       |
100
+
101
+---
102
+
103
+### `injectedJavaScript`
104
+
105
+Set this to provide JavaScript that will be injected into the web page when the view loads.
106
+
107
+| Type   | Required |
108
+| ------ | -------- |
109
+| string | No       |
110
+
111
+---
112
+
113
+### `mediaPlaybackRequiresUserAction`
114
+
115
+Boolean that determines whether HTML5 audio and video requires the user to tap them before they start playing. The default value is `true`.
116
+
117
+| Type | Required |
118
+| ---- | -------- |
119
+| bool | No       |
120
+
121
+---
122
+
123
+### `nativeConfig`
124
+
125
+Override the native component used to render the WebView. Enables a custom native WebView which uses the same JavaScript as the original WebView.
126
+
127
+The `nativeConfig` prop expects an object with the following keys:
128
+
129
+* `component` (any)
130
+* `props` (object)
131
+* `viewManager` (object)
132
+
133
+| Type   | Required |
134
+| ------ | -------- |
135
+| object | No       |
136
+
137
+---
138
+
139
+### `onError`
140
+
141
+Function that is invoked when the `WebView` load fails.
142
+
143
+| Type     | Required |
144
+| -------- | -------- |
145
+| function | No       |
146
+
147
+---
148
+
149
+### `onLoad`
150
+
151
+Function that is invoked when the `WebView` has finished loading.
152
+
153
+| Type     | Required |
154
+| -------- | -------- |
155
+| function | No       |
156
+
157
+---
158
+
159
+### `onLoadEnd`
160
+
161
+Function that is invoked when the `WebView` load succeeds or fails.
162
+
163
+| Type     | Required |
164
+| -------- | -------- |
165
+| function | No       |
166
+
167
+---
168
+
169
+### `onLoadStart`
170
+
171
+Function that is invoked when the `WebView` starts loading.
172
+
173
+| Type     | Required |
174
+| -------- | -------- |
175
+| function | No       |
176
+
177
+---
178
+
179
+### `onMessage`
180
+
181
+A function that is invoked when the webview calls `window.postMessage`. Setting this property will inject a `postMessage` global into your webview, but will still call pre-existing values of `postMessage`.
182
+
183
+`window.postMessage` accepts one argument, `data`, which will be available on the event object, `event.nativeEvent.data`. `data` must be a string.
184
+
185
+| Type     | Required |
186
+| -------- | -------- |
187
+| function | No       |
188
+
189
+---
190
+
191
+### `onNavigationStateChange`
192
+
193
+Function that is invoked when the `WebView` loading starts or ends.
194
+
195
+| Type     | Required |
196
+| -------- | -------- |
197
+| function | No       |
198
+
199
+---
200
+
201
+### `originWhitelist`
202
+
203
+List of origin strings to allow being navigated to. The strings allow wildcards and get matched against _just_ the origin (not the full URL). If the user taps to navigate to a new page but the new page is not in this whitelist, the URL will be handled by the OS. The default whitelisted origins are "http://*" and "https://*".
204
+
205
+| Type             | Required |
206
+| ---------------- | -------- |
207
+| array of strings | No       |
208
+
209
+---
210
+
211
+### `renderError`
212
+
213
+Function that returns a view to show if there's an error.
214
+
215
+| Type     | Required |
216
+| -------- | -------- |
217
+| function | No       |
218
+
219
+---
220
+
221
+### `renderLoading`
222
+
223
+Function that returns a loading indicator. The startInLoadingState prop must be set to true in order to use this prop.
224
+
225
+| Type     | Required |
226
+| -------- | -------- |
227
+| function | No       |
228
+
229
+---
230
+
231
+### `scalesPageToFit`
232
+
233
+Boolean that controls whether the web content is scaled to fit the view and enables the user to change the scale. The default value is `true`.
234
+
235
+On iOS, when [`useWebKit=true`](Reference.md#usewebkit), this prop will not work.
236
+
237
+| Type | Required |
238
+| ---- | -------- |
239
+| bool | No       |
240
+
241
+---
242
+
243
+### `onShouldStartLoadWithRequest`
244
+
245
+Function that allows custom handling of any web view requests. Return `true` from the function to continue loading the request and `false` to stop loading.
246
+
247
+| Type     | Required | Platform |
248
+| -------- | -------- | -------- |
249
+| function | No       | iOS      |
250
+
251
+---
252
+
253
+### `startInLoadingState`
254
+
255
+Boolean value that forces the `WebView` to show the loading view on the first load. This prop must be set to `true` in order for the `renderLoading` prop to work.
256
+
257
+| Type | Required |
258
+| ---- | -------- |
259
+| bool | No       |
260
+
261
+---
262
+
263
+### `decelerationRate`
264
+
265
+A floating-point number that determines how quickly the scroll view decelerates after the user lifts their finger. You may also use the string shortcuts `"normal"` and `"fast"` which match the underlying iOS settings for `UIScrollViewDecelerationRateNormal` and `UIScrollViewDecelerationRateFast` respectively:
266
+
267
+* normal: 0.998
268
+* fast: 0.99 (the default for iOS web view)
269
+
270
+| Type   | Required | Platform |
271
+| ------ | -------- | -------- |
272
+| number | No       | iOS      |
273
+
274
+---
275
+
276
+### `domStorageEnabled`
277
+
278
+Boolean value to control whether DOM Storage is enabled. Used only in Android.
279
+
280
+| Type | Required | Platform |
281
+| ---- | -------- | -------- |
282
+| bool | No       | Android  |
283
+
284
+---
285
+
286
+### `javaScriptEnabled`
287
+
288
+Boolean value to enable JavaScript in the `WebView`. Used on Android only as JavaScript is enabled by default on iOS. The default value is `true`.
289
+
290
+| Type | Required | Platform |
291
+| ---- | -------- | -------- |
292
+| bool | No       | Android  |
293
+
294
+---
295
+
296
+### `mixedContentMode`
297
+
298
+Specifies the mixed content mode. i.e WebView will allow a secure origin to load content from any other origin.
299
+
300
+Possible values for `mixedContentMode` are:
301
+
302
+* `never` (default) - WebView will not allow a secure origin to load content from an insecure origin.
303
+* `always` - WebView will allow a secure origin to load content from any other origin, even if that origin is insecure.
304
+* `compatibility` - WebView will attempt to be compatible with the approach of a modern web browser with regard to mixed content.
305
+
306
+| Type   | Required | Platform |
307
+| ------ | -------- | -------- |
308
+| string | No       | Android  |
309
+
310
+---
311
+
312
+### `thirdPartyCookiesEnabled`
313
+
314
+Boolean value to enable third party cookies in the `WebView`. Used on Android Lollipop and above only as third party cookies are enabled by default on Android Kitkat and below and on iOS. The default value is `true`.
315
+
316
+| Type | Required | Platform |
317
+| ---- | -------- | -------- |
318
+| bool | No       | Android  |
319
+
320
+---
321
+
322
+### `userAgent`
323
+
324
+Sets the user-agent for the `WebView`.
325
+
326
+| Type   | Required | Platform |
327
+| ------ | -------- | -------- |
328
+| string | No       | Android  |
329
+
330
+---
331
+
332
+### `allowsInlineMediaPlayback`
333
+
334
+Boolean that determines whether HTML5 videos play inline or use the native full-screen controller. The default value is `false`.
335
+
336
+> **NOTE**
337
+>
338
+> In order for video to play inline, not only does this property need to be set to `true`, but the video element in the HTML document must also include the `webkit-playsinline` attribute.
339
+
340
+| Type | Required | Platform |
341
+| ---- | -------- | -------- |
342
+| bool | No       | iOS      |
343
+
344
+---
345
+
346
+### `bounces`
347
+
348
+Boolean value that determines whether the web view bounces when it reaches the edge of the content. The default value is `true`.
349
+
350
+| Type | Required | Platform |
351
+| ---- | -------- | -------- |
352
+| bool | No       | iOS      |
353
+
354
+---
355
+
356
+### `contentInset`
357
+
358
+The amount by which the web view content is inset from the edges of the scroll view. Defaults to {top: 0, left: 0, bottom: 0, right: 0}.
359
+
360
+| Type                                                               | Required | Platform |
361
+| ------------------------------------------------------------------ | -------- | -------- |
362
+| object: {top: number, left: number, bottom: number, right: number} | No       | iOS      |
363
+
364
+---
365
+
366
+### `dataDetectorTypes`
367
+
368
+Determines the types of data converted to clickable URLs in the web view's content. By default only phone numbers are detected.
369
+
370
+You can provide one type or an array of many types.
371
+
372
+Possible values for `dataDetectorTypes` are:
373
+
374
+* `phoneNumber`
375
+* `link`
376
+* `address`
377
+* `calendarEvent`
378
+* `none`
379
+* `all`
380
+
381
+With the [new WebKit](Reference.md#usewebkit) implementation, we have three new values:
382
+
383
+* `trackingNumber`
384
+* `flightNumber`
385
+* `lookupSuggestion`
386
+
387
+| Type             | Required | Platform |
388
+| ---------------- | -------- | -------- |
389
+| string, or array | No       | iOS      |
390
+
391
+---
392
+
393
+### `scrollEnabled`
394
+
395
+Boolean value that determines whether scrolling is enabled in the `WebView`. The default value is `true`.
396
+
397
+| Type | Required | Platform |
398
+| ---- | -------- | -------- |
399
+| bool | No       | iOS      |
400
+
401
+---
402
+
403
+### `geolocationEnabled`
404
+
405
+Set whether Geolocation is enabled in the `WebView`. The default value is `false`. Used only in Android.
406
+
407
+| Type | Required | Platform |
408
+| ---- | -------- | -------- |
409
+| bool | No       | Android  |
410
+
411
+---
412
+
413
+### `allowUniversalAccessFromFileURLs`
414
+
415
+Boolean that sets whether JavaScript running in the context of a file scheme URL should be allowed to access content from any origin. Including accessing content from other file scheme URLs. The default value is `false`.
416
+
417
+| Type | Required | Platform |
418
+| ---- | -------- | -------- |
419
+| bool | No       | Android  |
420
+
421
+---
422
+
423
+### `useWebKit`
424
+
425
+If true, use WKWebView instead of UIWebView.
426
+
427
+| Type    | Required | Platform |
428
+| ------- | -------- | -------- |
429
+| boolean | No       | iOS      |
430
+
431
+---
432
+
433
+### `url`
434
+
435
+**Deprecated.** Use the `source` prop instead.
436
+
437
+| Type   | Required |
438
+| ------ | -------- |
439
+| string | No       |
440
+
441
+---
442
+
443
+### `html`
444
+
445
+**Deprecated.** Use the `source` prop instead.
446
+
447
+| Type   | Required |
448
+| ------ | -------- |
449
+| string | No       |
450
+
451
+## Methods
452
+
453
+### `extraNativeComponentConfig()`
454
+
455
+```javascript
456
+static extraNativeComponentConfig()
457
+```
458
+
459
+### `goForward()`
460
+
461
+```javascript
462
+goForward();
463
+```
464
+
465
+Go forward one page in the web view's history.
466
+
467
+### `goBack()`
468
+
469
+```javascript
470
+goBack();
471
+```
472
+
473
+Go back one page in the web view's history.
474
+
475
+### `reload()`
476
+
477
+```javascript
478
+reload();
479
+```
480
+
481
+Reloads the current page.
482
+
483
+### `stopLoading()`
484
+
485
+```javascript
486
+stopLoading();
487
+```
488
+
489
+Stop loading the current page.
490
+
491
+## Other Docs
492
+
493
+Also check out our [Getting Started Guide](Getting-Started.md) and [In-Depth Guide](Guide.md).