ReactTraining/history v4 类库源码注解（

类型一览

路径

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 不支持。

参考资料

• Location - Web APIs | MDN
• The history interface