spa-history
A HTML5 history library for single-page application.
Install
npm install spa-history
Constructor
PathHistory
const history = // path of base directory. defaults to '' // If you want the root path doesn't contain ending slash, // you can set the base without ending slash, like '/app' base: '/app/' /* beforeChange() will be called before location change. Arguments: to: A normalized location object. The location will be changed to. from: A normalized location object. The current location. action: String. What action triggered the history change. push: history.push() is called. replace: history.replace() is called. pop: user clicked the back or forward button, or history.go(), history.back(), history.forward() is called, or hash changed. init: "to" is the initial page, at this stage, "from" is null. dispatch: history.dispatch() is called. Returns: true | undefined: The navigation is confirmed. false: Prevent the navigation. null: Do nothing. path | location object: Redirect to this location. You can override the history manipulate action by providing the `action` property, values are: 'push', 'replace', 'dispatch'. Return value can be a Promise. */ { } /* afterChange() will be called after the location changed. Arguments: to: Location object. The location changed to. */ { } historystart
HashHistory
const history = { } { } historystart
HashHistory
has no base
option.
Location object
A location object is used for changing the current address.
It can be used in history.start(location)
, history.push(location)
, history.replace(location)
, history.dispatch(location)
, etc.
A string URL can be converted to a location object by history.normalize().
to
and from
parameter of beforeChange
and afterChange
hook are normalized location objects.
And a location object can be converted to a URL string by history.url().
path external query hash fullPath url state hidden appearPath
path
String
SPA Internal path, which has stripped the protocol, host, and base path.
external
Boolean
If path
is started with protocal, or external
is true
,
path
is treated as an external path, and will be converted to an internal path.
query
Object
| String
| Array
| URLSearchParams
| StringCaster<URLSearchParams>
query
accepts the same parameter types as URLSearchParams
constructor. Or it can be a StringCaster object that wraps a URLSearchParams
object.
hash
String
A string containing a #
followed by the fragment identifier of the URL.
If HashHistory
is used, the fragment identifier is followed by the second #
mark.
fullPath
String
. Read-only.
path + query string + hash
url
String
. Read-only.
An external relative URL which can be used as href
attribute of <a>
.
It is the same as history.url(location)
.
PathHistory
: base + path + query string + hashHashHistory
: # + path + query string + hash
state
Object
The state object is a JavaScript object which is associated with the history entry.
See state
parameter of history.pushState() for details.
hidden
Boolean
Indicate whether it is a hidden history entry. see history.push() for detail.
appearPath
String
If hidden
is true
and appearPath
is set, the location bar will show this address instead.
APIs
history.current
Location object
The current location. See location object.
history.start()
historystartURL string | location
Starts to handle the history.
In browser, if URL/location is not given, the default value is the current address.
history.normalize()
history
Converts a URL string or an unnormalized location object to a normalized object.
If URL/location.path is started with protocal, or location.external
is true
, location.path
is treated as an external path, and will be converted to an internal path.
// PathHistory with base '/foo/bar/'history/* -> { path: '/home', query: new StringCaster(new URLSearchParams('a=1')), hash: '#b', fullPath: '/home?a=1#b', url: '/foo/bar/home?a=1#b', state: {} }*/ // same result as abovehistory // same result as abovehistory // same result as abovehistory // HashHistoryhistory/* -> { path: '/home', query: new StringCaster(new URLSearchParams('a=1')), hash: '#b', fullPath: '/home?a=1#b', url: '#/home?a=1#b', state: {} }*/
history.url()
history
Converts a internal URL string or a location object to an external URL which can be used as href
of <a>
.
history // orhistory /* result: HashHistory: #/home?a=1#b PathHistory(with base: '/foo/bar/'): /foo/bar/home?a=1#b*/
history.push()
history
Pushs the location onto the history stack. beforeChange
will be called.
history history // PathHistory, complete URLhistory // HashHistory, complete URLhistory
You can push a location with state.
history
And you can push a hidden location, which will not change the value of browser's address bar.
the hidden location is stored in window.history.state
.
history
history.replace()
history
Replaces the current history entry with the provided URL/location.
history.dispatch()
history
Sets the current location to the provided URL/location without changing the history session.
That is, the location of browser's address bar won't change. beforeChange
will be called.
history.setState()
history
Sets state of the current location. The state will be merged into history.current.state
history.go()
history
Counterpart of window.history.go()
. Returns a promise which will be resolved when popstate
event fired.
silent
: If true
, beforeChange
won't be called.
state
: If set, the state object will be merged into the state object of the destination location.
history.back()
history
Same as history.go(-1, options)
.
history.forward()
history
Same as history.go(1, options)
.
history.captureLinkClickEvent()
history
Prevents the navigation when clicking the <a>
element in the container and the href
is an in-app address,
history.push()
will be called instead.
documentbody
Dependencies
You can use @babel/polyfill and dom4 to meet the requirements.
Or use the polyfill.io service: