history-stack-manager

简介

原本的浏览器不支持直接查看和操作历史记录栈， 而该模块实现了当前window的浏览器记录栈的映射管理控制与功能拓展。

注意

模块被故意设置为仅支持当前window产生的历史记录管理，
如果有iframe也要管理，可以重新使用createHistoryManager创建一个用于专门管理iframe产生的历史记录

安装

使用 npm:

$ npm install history-stack-manager

使用 yarn:

$ yarn add history-stack-manager

使用 pnpm:

$ pnpm add history-stack-manager

---

快速上手

导入创建函数

import {createHistoryManager} from 'history-stack-manager';

创建一个history管理器

const history = createHistoryManager()
// 你也可以指定一个即将被接管window对象,比如iframe的window
// const history = createHistoryManager(window)
console.log(history)

Type类型定义

export type HistoryOptions = {
  /** 该管理器历史记录类型标识 */
  type: '__HISTORY_DATA__' | string
  /** 非必要，浏览器的历史原因，传入空字符串就行了 */
  title: string
  /** 要持久化记录的state */
  state: any
  /** 要添加记录的对应url */
  url: string
  /** 要添加记录的滚动位置  */
  scrollY: number
  /** 当前记录的唯一id  */
  id: number
}

Event API

Support New Window Event

HistoryEvent

• url string; 当前页面地址
• state string; 当前state
• title string; 标题
• manager HistoryManagerImpl 虚拟管理器，同History API

使用方式:

// 监听window.history.pushState操作
window.addEventListener("historyPushState",()=>{})
// 监听window.history.replaceState操作
window.addEventListener("historyReplaceState",()=>{})

Virtual History Manager Event API

back event
使用方式:

// 监听浏览器后退
historyManaget.$on('back',(state)=>{})

forward event
使用方式:

// 监听浏览器前进
historyManaget.$on('forward',(state)=>{})

popstate event
使用方式:

//同浏览器popstate事件触发条件基本一致
historyManaget.$on('popstate',(state)=>{})

History API

back

• desc 后退
• type Function
• args empty
• return void
  返回上一个页面，和原本浏览器内置管理器操作无任何差别

history.back()   // 后退

forward

• desc 前进
• type Function
• args empty
• return void
  前往下一个页面，和原本浏览器内置管理器操作无任何差别

history.forward()   // 前进

go

• desc 前往当前页指定偏移记录
• type Function
• args [offset: number]
• return void
  前往相对当前页指定偏移历史记录位置，和原本浏览器内置管理器操作无任何差别

history.go(-1)  // 相当于history.back()  

pushState

• desc 添加一条历史记录
• type Function
• args [state: any, title:string, url:string]
• return void
  针对浏览器内置管理器替换记录，和原本浏览器内置管理器操作无任何差别

history.pushState({state:'data'},'','url') 

replaceState

• desc 替换一条历史记录
• type Function
• args [state: any, title:string, url:string]
• return void
  针对浏览器内置管理器添加记录，和原本浏览器内置管理器操作无任何差别

history.replaceState({state:'data'},'','url') 

---

length

• desc 当前内置管理器真实历史记录的条数
• type number

scrollRestoration

• desc 是否保持上次滚动位置
• type 'auto' | 'manual'

state

• desc pushState 或 replaceState 添加进的state
• type any

stack

• desc 映射当前window历史记录的后的栈数组
• type Array<HistoryOptions>

point

• desc 当前页面在历史记录中的游标位置，最低0，最高49，和stack数组的最大值有关，默认支持记录50条
• type number

len

• desc 当前虚拟管理器记录的历史记录条数
• type number

history

• desc 当前虚拟管理器正在操控的历史记录
• type HistoryOptions

$on

• desc 事件监听
• type Function

const cb = (state)=>{}
historyManager.$on('back',cb)

$off

• desc 事件关闭
• type Function

historyManager.$off('back',cb)

$emit

• desc 手动发射事件
• type Function

historyManager.$emit('back',{a:123}})

$clear

• desc 清除所有事件
• type Function

historyManager.$clear()

---

高级操作函数(不建议在不了解的情况在使用，正常基本不会用到)

replace

• desc 手动替换一条虚拟管理器的历史记录
• type Function
• args [history:HistoryOptions]
• return void
  针对虚拟管理器替换记录，对内置管理器毫无影响，会破坏虚拟映射，不建议在不了解的情况使用

const item = history.createHistory({state:'data'},'','url')
history.replace(item)

push

• desc 手动添加一条虚拟管理器的历史记录
• type Function
• args [history:HistoryOptions]
• return void
  针对虚拟管理器添加记录，对内置管理器毫无影响，会破坏虚拟映射，，不建议在不了解的情况使用

const item = history.createHistory({state:'data'},'','url')
history.push(item)

index

• desc 直接跳转到id值对应历史记录
• type Function
• args [id:number]
• return void
  直接跳转到id值对应历史记录，目的主要时修改id，不建议在不了解的情况使用

const item = history.stack[10]
history.index(item.id) 

createHistory

• desc 创建一个虚拟管理器专用的历史记录
• type Function
• args [state: any, title:string, url:string]
• return void 创建一个虚拟管理器专用的历史记录，该history可以通过push函数或者replace函数加入虚拟管理器

const item = history.createHistory({state:'data'},'','url')
history.push(item)

---

解释：

1. 内置管理器: 平常使用的window.history对象
2. 虚拟管理器: 该模块创建的history对象，模块可以直接当成离线的内置管理器使用， 同时提供了拓展，支持记录当前window页面产生的所有历史记录，提供stack属性作为映射 支持监听浏览器的前进后退操作

原理：

简称: 可识别记录 => 可被该虚拟管理器识别的history
实现了监听记录当前window中所有产生的历史记录，支持映射历史记录栈和浏览器的后退和前进事件
1.在首次进入页面的时候记录并替换成可识别记录
2.通过监听popstate，在此基础上的所有的记录操作符合浏览器内置规则，在事件回调里面通过规则判断是否前往了新的url 如果有则在合适时候将其state替换成可识别记录，并在每次历史记录操作的时候同步到sessionStorage中(详见syncHistory文件)
3.通过拦截pushState和replaceState的window.history操作，因为该操作不会触发popstate需要单独处理，拦截后也在合适时机替换成可识别记录