forked from remix-run/history
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
54 additions
and
49 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,7 +2,6 @@ | |
|
|
||
| [build-badge]: https://img.shields.io/travis/ReactTraining/history/master.svg?style=flat-square | ||
| [build]: https://travis-ci.org/ReactTraining/history | ||
|
|
||
| [npm-badge]: https://img.shields.io/npm/v/history.svg?style=flat-square | ||
| [npm]: https://www.npmjs.org/package/history | ||
|
|
||
|
|
@@ -18,10 +17,10 @@ Then with a module bundler like [webpack](https://webpack.github.io/), use as yo | |
|
|
||
| ```js | ||
| // using ES6 modules | ||
| import createHistory from 'history/createBrowserHistory' | ||
| import createHistory from "history/createBrowserHistory" | ||
|
|
||
| // using CommonJS modules | ||
| var createHistory = require('history').createBrowserHistory | ||
| var createHistory = require("history").createBrowserHistory | ||
| ``` | ||
|
|
||
| The UMD build is also available on [unpkg](https://unpkg.com): | ||
|
|
@@ -36,16 +35,16 @@ You can find the library on `window.History`. | |
|
|
||
| `history` provides 3 different methods for creating a `history` object, depending on your environment. | ||
|
|
||
| - `createBrowserHistory` is for use in modern web browsers that support the [HTML5 history API](http://diveintohtml5.info/history.html) (see [cross-browser compatibility](http://caniuse.com/#feat=history)) | ||
| - `createMemoryHistory` is used as a reference implementation and may also be used in non-DOM environments, like [React Native](https://facebook.github.io/react-native/) or tests | ||
| - `createHashHistory` is for use in legacy web browsers | ||
| * `createBrowserHistory` is for use in modern web browsers that support the [HTML5 history API](http://diveintohtml5.info/history.html) (see [cross-browser compatibility](http://caniuse.com/#feat=history)) | ||
| * `createMemoryHistory` is used as a reference implementation and may also be used in non-DOM environments, like [React Native](https://facebook.github.io/react-native/) or tests | ||
| * `createHashHistory` is for use in legacy web browsers | ||
|
|
||
| Depending on the method you want to use to keep track of history, you'll `import` (or `require`) one of these methods directly from the package root (i.e. `history/createBrowserHistory`). The remainder of this document uses the term `createHistory` to refer to any of these implementations. | ||
|
|
||
| Basic usage looks like this: | ||
|
|
||
| ```js | ||
| import createHistory from 'history/createBrowserHistory' | ||
| import createHistory from "history/createBrowserHistory" | ||
|
|
||
| const history = createHistory() | ||
|
|
||
|
|
@@ -59,7 +58,7 @@ const unlisten = history.listen((location, action) => { | |
| }) | ||
|
|
||
| // Use push, replace, and go to navigate around. | ||
| history.push('/home', { some: 'state' }) | ||
| history.push("/home", { some: "state" }) | ||
|
|
||
| // To stop listening, call the function returned from listen(). | ||
| unlisten() | ||
|
|
@@ -69,25 +68,25 @@ The options that each `create` method takes, along with its default values, are: | |
|
|
||
| ```js | ||
| createBrowserHistory({ | ||
| basename: '', // The base URL of the app (see below) | ||
| forceRefresh: false, // Set true to force full page refreshes | ||
| keyLength: 6, // The length of location.key | ||
| basename: "", // The base URL of the app (see below) | ||
| forceRefresh: false, // Set true to force full page refreshes | ||
| keyLength: 6, // The length of location.key | ||
| // A function to use to confirm navigation with the user (see below) | ||
| getUserConfirmation: (message, callback) => callback(window.confirm(message)) | ||
| }) | ||
|
|
||
| createMemoryHistory({ | ||
| initialEntries: [ '/' ], // The initial URLs in the history stack | ||
| initialIndex: 0, // The starting index in the history stack | ||
| keyLength: 6, // The length of location.key | ||
| initialEntries: ["/"], // The initial URLs in the history stack | ||
| initialIndex: 0, // The starting index in the history stack | ||
| keyLength: 6, // The length of location.key | ||
| // A function to use to confirm navigation with the user. Required | ||
| // if you return string prompts from transition hooks (see below) | ||
| getUserConfirmation: null | ||
| }) | ||
|
|
||
| createHashHistory({ | ||
| basename: '', // The base URL of the app (see below) | ||
| hashType: 'slash', // The hash type to use (see below) | ||
| basename: "", // The base URL of the app (see below) | ||
| hashType: "slash", // The hash type to use (see below) | ||
| // A function to use to confirm navigation with the user (see below) | ||
| getUserConfirmation: (message, callback) => callback(window.confirm(message)) | ||
| }) | ||
|
|
@@ -97,9 +96,9 @@ createHashHistory({ | |
|
|
||
| Each `history` object has the following properties: | ||
|
|
||
| - `history.length` - The number of entries in the history stack | ||
| - `history.location` - The current location (see below) | ||
| - `history.action` - The current navigation action (see below) | ||
| * `history.length` - The number of entries in the history stack | ||
| * `history.location` - The current location (see below) | ||
| * `history.action` - The current navigation action (see below) | ||
|
|
||
| Additionally, `createMemoryHistory` provides `history.index` and `history.entries` properties that let you inspect the history stack. | ||
|
|
||
|
|
@@ -109,54 +108,56 @@ You can listen for changes to the current location using `history.listen`: | |
|
|
||
| ```js | ||
| history.listen((location, action) => { | ||
| console.log(`The current URL is ${location.pathname}${location.search}${location.hash}`) | ||
| console.log( | ||
| `The current URL is ${location.pathname}${location.search}${location.hash}` | ||
| ) | ||
| console.log(`The last navigation action was ${action}`) | ||
| }) | ||
| ``` | ||
|
|
||
| The `location` object implements a subset of [the `window.location` interface](https://developer.mozilla.org/en-US/docs/Web/API/Location), including: | ||
|
|
||
| - `location.pathname` - The path of the URL | ||
| - `location.search` - The URL query string | ||
| - `location.hash` - The URL hash fragment | ||
| * `location.pathname` - The path of the URL | ||
| * `location.search` - The URL query string | ||
| * `location.hash` - The URL hash fragment | ||
|
|
||
| Locations may also have the following properties: | ||
|
|
||
| - `location.state` - Some extra state for this location that does not reside in the URL (supported in `createBrowserHistory` and `createMemoryHistory`) | ||
| - `location.key` - A unique string representing this location (supported in `createBrowserHistory` and `createMemoryHistory`) | ||
| * `location.state` - Some extra state for this location that does not reside in the URL (supported in `createBrowserHistory` and `createMemoryHistory`) | ||
| * `location.key` - A unique string representing this location (supported in `createBrowserHistory` and `createMemoryHistory`) | ||
|
|
||
| The `action` is one of `PUSH`, `REPLACE`, or `POP` depending on how the user got to the current URL. | ||
|
|
||
| ### Navigation | ||
|
|
||
| `history` objects may be used to programmatically change the current location using the following methods: | ||
|
|
||
| - `history.push(path, [state])` | ||
| - `history.replace(path, [state])` | ||
| - `history.go(n)` | ||
| - `history.goBack()` | ||
| - `history.goForward()` | ||
| - `history.canGo(n)` (only in `createMemoryHistory`) | ||
| * `history.push(path, [state])` | ||
| * `history.replace(path, [state])` | ||
| * `history.go(n)` | ||
| * `history.goBack()` | ||
| * `history.goForward()` | ||
| * `history.canGo(n)` (only in `createMemoryHistory`) | ||
|
|
||
| When using `push` or `replace` you can either specify both the URL path and state as separate arguments or include everything in a single location-like object as the first argument. | ||
|
|
||
| 1. A URL path *or* | ||
| 1. A URL path _or_ | ||
| 2. A location-like object with `{ pathname, search, hash, state }` | ||
|
|
||
| ```js | ||
| // Push a new entry onto the history stack. | ||
| history.push('/home') | ||
| history.push("/home") | ||
|
|
||
| // Push a new entry onto the history stack with a query string | ||
| // and some state. Location state does not appear in the URL. | ||
| history.push('/home?the=query', { some: 'state' }) | ||
| history.push("/home?the=query", { some: "state" }) | ||
|
|
||
| // If you prefer, use a single location-like object to specify both | ||
| // the URL and state. This is equivalent to the example above. | ||
| history.push({ | ||
| pathname: '/home', | ||
| search: '?the=query', | ||
| state: { some: 'state' } | ||
| pathname: "/home", | ||
| search: "?the=query", | ||
| state: { some: "state" } | ||
| }) | ||
|
|
||
| // Go back to the previous history entry. The following | ||
|
|
@@ -174,7 +175,7 @@ history.goBack() | |
| ```js | ||
| // Register a simple prompt message that will be shown the | ||
| // user before they navigate away from the current page. | ||
| const unblock = history.block('Are you sure you want to leave this page?') | ||
| const unblock = history.block("Are you sure you want to leave this page?") | ||
|
|
||
| // Or use a function that returns the message when it's needed. | ||
| history.block((location, action) => { | ||
|
|
@@ -183,8 +184,7 @@ history.block((location, action) => { | |
|
|
||
| // A common use case is to prevent the user from leaving the | ||
| // page if there's a form they haven't submitted yet. | ||
| if (input.value !== '') | ||
| return 'Are you sure you want to leave this page?' | ||
| if (input.value !== "") return "Are you sure you want to leave this page?" | ||
| }) | ||
|
|
||
| // To stop blocking transitions, call the function returned from block(). | ||
|
|
@@ -213,14 +213,14 @@ If all the URLs in your app are relative to some other "base" URL, use the `base | |
|
|
||
| ```js | ||
| const history = createHistory({ | ||
| basename: '/the/base' | ||
| basename: "/the/base" | ||
| }) | ||
|
|
||
| history.listen(location => { | ||
| console.log(location.pathname) // /home | ||
| }) | ||
|
|
||
| history.push('/home') // URL is now /the/base/home | ||
| history.push("/home") // URL is now /the/base/home | ||
| ``` | ||
|
|
||
| **Note:** `basename` is not suppported in `createMemoryHistory`. | ||
|
|
@@ -239,27 +239,32 @@ const history = createBrowserHistory({ | |
|
|
||
| By default `createHashHistory` uses a leading slash in hash-based URLs. You can use the `hashType` option to use a different hash formatting. | ||
|
|
||
|
|
||
| ```js | ||
| const history = createHashHistory({ | ||
| hashType: 'slash' // the default | ||
| hashType: "slash" // the default | ||
| }) | ||
|
|
||
| history.push('/home') // window.location.hash is #/home | ||
| history.push("/home") // window.location.hash is #/home | ||
|
|
||
| const history = createHashHistory({ | ||
| hashType: 'noslash' // Omit the leading slash | ||
| hashType: "noslash" // Omit the leading slash | ||
| }) | ||
|
|
||
| history.push('/home') // window.location.hash is #home | ||
| history.push("/home") // window.location.hash is #home | ||
|
|
||
| const history = createHashHistory({ | ||
| hashType: 'hashbang' // Google's legacy AJAX URL format | ||
| hashType: "hashbang" // Google's legacy AJAX URL format | ||
| }) | ||
|
|
||
| history.push('/home') // window.location.hash is #!/home | ||
| history.push("/home") // window.location.hash is #!/home | ||
| ``` | ||
|
|
||
| ## About | ||
|
|
||
| `history` is developed and maintained by [React Training](https://reacttraining.com). If | ||
| you're interested in learning more about what React can do for your company, please | ||
| [get in touch](mailto:[email protected])! | ||
|
|
||
| ## Thanks | ||
|
|
||
| A big thank-you to [Dan Shaw](https://www.npmjs.com/~dshaw) for letting us use the `history` npm package name! Thanks Dan! | ||
|
|
||