ReactTraining/history v4 类库源码注解（

2018-08-26 本文已影响70人 Levid_GC

类型一览

路径

Pathname

路径名。

type Pathname = string;

Search

查询。

type Search = string;

Hash

哈希。

type Hash = string;

Path

路径。

type Path: string;

路径是由路径名，查询，哈希三部分共同组成。

地址

Href

超链接。

type Href = string;

LocationState

地址状态。

type LocationState = any;

LocationKey

地址键。

type LocationKey = string;

LocationDescriptorObject

地址描述器对象。

interface LocationDescriptorObject<S = LocationState> {
  pathname?: Pathname;
  search?: Search;
  hash?: Hash;
  state?: S;
  key?: LocationKey;
}

LocationDescriptor

地址描述器。

type LocationDescriptor<S = LocationState> = Path | LocationDescriptorObject<S>;

地址描述器类型实例用于构造下面的地址类型实例。它是一个联合类型，可是路径也可是路径描述器对象。

Location

地址。

interface Location<S = LocationState> {
  pathname: Pathname;
  search: Search;
  hash: Hash;
  state: S;
  key?: LocationKey;
}

Window 和 Document 接口类型下面都有一个 location 属性，这个属性的类型是 Location，但是这个 Location 类型与上面列出的地址类型有很多共同点，但是它对浏览器地址栏中的 URL 进行了完整的抽象。比如，它还提供了协议类型、主机名、端口等等信息。但是我们这里的地址类型侧重于 URL 的路径部分，并额外提供了状态和键属性，所以要注意区别。

历史

Action

行为。

type Action = 'PUSH' | 'POP' | 'REPLACE';

行为是针对历史堆栈的，分为压入，弹出和替换。

History

历史。

interface History {
  length: number;
  action: Action;
  location: Location;
  push(path: Path, state?: LocationState): void;
  push(location: LocationDescriptorObject): void;
  replace(path: Path, state?: LocationState): void;
  replace(location: LocationDescriptorObject): void;
  go(n: number): void;
  goBack(): void;
  goForward(): void;
  block(prompt?: boolean | string | TransitionPromptHook): UnregisterCallback;
  listen(listener: LocationListener): UnregisterCallback;
  createHref(location: LocationDescriptorObject): Href;
}

History 接口类型是对 HTML5 history api 的封装，并在之上提供了额外的功能。

转换

TransitionHook

转换钩子。

type TransitionHook = (location: Location, callback: (result: any) => void) => any;

TransitionPromptHook

转换提示钩子。

type TransitionPromptHook = (location: Location, action: Action) => string | false | void;

函数功能

PathUtils

addLeadingSlash：添加路径前置斜杠

function addLeadingSlash(path: Path): Path

stripLeadingSlash：删除路径前置斜杠

function stripLeadingSlash(path: Path): Path

hasBasename：路径中是否含有基路径

function hasBasename(path: Path, prefix: string): boolean

stripBasename：删除路径中的基路径

function stripBasename(path: Path, prefix: string): Path

stripTrailingSlash：删除路径后置斜杠

function stripTrailingSlash(path: Path): Path

parsePath：将路径转化为 Location 类型

function parsePath(path: Path): Location

说明：此方法只解析路径中的路径名、查询字符串和 hash。

示例：

input: '/pathname?query=string#hash=value'
output: { 
  pathname: '/pathname',
  search: '?query=string',
  hash: '#hash=value'
}

createPath：将 LocationDescriptorObject 类型对象转换为 Path 字符串
```
function createPath(location: LocationDescriptorObject): Path
```
说明：此方法只根据地址对象中的路径名，查询字符串和 hash 数据拼装路径字符串。

LocationUtils

createLocation：创建地址

function createLocation(
  path: LocationDescriptor, 
  state?: LocationState, 
  key?: LocationKey, 
  currentLocation?: Location
): Location

locationsAreEqual：判断两个地址对象是否相等

function locationsAreEqual(lv: LocationDescriptor, rv: LocationDescriptor): boolean

DOMUtils

canUseDOM：判断是否可以使用 DOM
```
const canUseDOM: boolean
```
isExtraneousPopstateEvent：判断 popstate 事件是否为无关的 WebKit 事件
```
const isExtraneousPopstateEvent(event): boolean
```
说明：iOS 上的 Chrome 浏览器会触发此类事件。

getConfirmation：获取消息的确认信息，并使用 callback 函数执行回调

function getConfirmation(message: string, callback: (result: boolean) => void): void

supportsHistory：判断是否能够使用 HTML5 historty 接口
```
function supportsHistory(): boolean
```
supportsGoWithoutReloadUsingHash：判断是否支持在使用 hash 的时候，调用 history 对象的 go 接口不会导致整个页面的刷新
```
function supportsGoWithoutReloadUsingHash(): boolean
```
说明：Firefox 不支持。
supportsPopStateOnHashChange：路径 hash 值发生变更的时候是否会触发 popstate 事件
```
function supportsPopStateOnHashChange(): boolean
```
说明：IE10/11 不支持。