@mantou/gem 1.7.8 → 1.7.10

package/src/elements/base/route.ts

@@ -1,28 +1,25 @@
 import { GemElement, html, TemplateResult } from '../../lib/element';
-import { property, connectStore, emitter, Emitter, boolattribute } from '../../lib/decorators';
-import { createStore, updateStore, Store } from '../../lib/store';
+import { property, emitter, Emitter, boolattribute } from '../../lib/decorators';
+import { createStore, updateStore, Store, connect } from '../../lib/store';
 import { titleStore, history, UpdateHistoryParams } from '../../lib/history';
-import { QueryString } from '../../lib/utils';
+import { addListener, QueryString } from '../../lib/utils';
 
-interface NamePosition {
-  [index: string]: number;
-}
+const UNNAMED_PARAM_PREFIX = '_';
 
+// '/test/:a' /^\/test\/(?<a>[^/]+)$/i
+// '/test/:a/b' /^\/test\/?<a>([^/]+)\/b$/i
+// '/test/*' /^\/test\/(?<_0>.*)$/i
+// '/test/:a/*' /^\/test\/(?<a>[^/]+)\/(?<_0>.*)$/i
+// '/test/*/:b /^\/test\/(?<_0>.*)\/(?<a>[^/]+)$/i
 class ParamsRegExp extends RegExp {
-  namePosition: NamePosition;
   constructor(pattern: string) {
-    const namePosition: NamePosition = {};
     let i = 0;
     super(
-      `^${pattern
-        .replace(/:([^/$]+)/g, (_m, name: string) => {
-          namePosition[name] = i++;
-          return `([^/]+)`;
-        })
-        .replace('*', '.*')}$`,
-      'i',
+      `^${pattern.replace(/((:[^/$]+)|(\*))/g, (_m, name: string) => {
+        if (name === '*') return `(?<${UNNAMED_PARAM_PREFIX}${i++}>.*)`;
+        return `(?<${name.slice(1)}>[^/]+)`;
+      })}$`,
     );
-    this.namePosition = namePosition;
   }
 }
 
@@ -35,12 +32,19 @@ declare global {
   }
 }
 
-// URLPattern 大小写敏感
-// 匹配成功时返回 params
-// `/a/b/:c/:d` `/a/b/1/2`
-// pattern 以 / 结尾时能匹配 2 中路径
-// `/a/b/:c/:d/` `/a/b/1/2`
-// `/a/b/:c/:d/` `/a/b/1/2/`
+/**
+ * - 大小写敏感
+ * - 匹配成功时返回 params
+ * - 以 `/` 结尾时能不带 `/` 结尾的路径
+ * - `*` 匹配到的 params 名称为数字
+ *
+ * @example
+ * ```js
+ * matchPath(`/a/b/:c/:d`,`/a/b/1/2`);
+ * matchPath(`/a/b/:c/:d`,`/a/b/1/2/`);
+ * matchPath(`/a/b/*`,`/a/b/1/2/`);
+ * ```
+ */
 export function matchPath(pattern: string, path: string) {
   if (window.URLPattern) {
     const urLPattern = new window.URLPattern({ pathname: pattern });
@@ -52,9 +56,9 @@ export function matchPath(pattern: string, path: string) {
   const matchResult = path.match(reg) || `${path}/`.match(reg);
   if (!matchResult) return null;
   const params: Params = {};
-  if (matchResult) {
-    Object.keys(reg.namePosition).forEach((name) => {
-      params[name] = matchResult[reg.namePosition[name] + 1];
+  if (matchResult.groups) {
+    Object.entries(matchResult.groups).forEach(([key, value]) => {
+      params[key.startsWith(UNNAMED_PARAM_PREFIX) ? key.slice(1) : key] = value;
     });
   }
   return params;
@@ -111,29 +115,44 @@ type State = {
   content?: TemplateResult;
 };
 
+export type RouteTrigger = {
+  store: Store<any>;
+  replace: (arg: { path: string }) => void;
+  getParams: () => { path: string; query?: string | QueryString; hash?: string };
+};
+
+const scrollPositionMap = new Map<string, number>();
+
 /**
  * @attr inert 暂停路由更新
  * @fires routechange
  * @fires error
  * @fires loading
  */
-@connectStore(history.store)
 export class GemRouteElement extends GemElement<State> {
   @boolattribute transition: boolean;
   @property routes?: RouteItem[] | RoutesObject;
   /**
-   * 不要多个 `<gem-route>` 共享，因为那样会导致后面的元素卸载前触发更新
+   * 路由更新后更新的 store，能从中读取到安全的路由数据
    *
    * @example
    * const locationStore = GemRouteElement.createLocationStore()
    * html`<gem-route .locationStore=${locationStore}>`
    */
-  @property locationStore?: Store<{ path: string; params: Params; query: QueryString; data?: any }>;
+  @property locationStore?: ReturnType<(typeof GemRouteElement)['createLocationStore']>;
   @property key?: any; // 除了 href 提供另外一种方式来更新，比如语言更新也需要刷新 <gem-route>
+  @emitter loading: Emitter<RouteItem | null>;
+  @emitter beforeroutechange: Emitter<RouteItem | null>;
   @emitter routechange: Emitter<RouteItem | null>; // path 改变或者 key 改变，包含初始渲染
-  @emitter loading: Emitter<RouteItem>;
   @emitter error: Emitter<any>;
 
+  /**自动让滚动容器恢复滚动位置 */
+  @property scrollContainer?: HTMLElement | (() => HTMLElement);
+  /**默认当有 `hash` 时不进行滚动 */
+  @property scrollIgnoreHash?: boolean;
+
+  @property trigger: RouteTrigger = history;
+
   /**当前使用的路由对象 */
   currentRoute: RouteItem | null;
   /**当前匹配的路由的 params */
@@ -141,9 +160,10 @@ export class GemRouteElement extends GemElement<State> {
 
   #lastLoader?: Promise<TemplateResult>;
 
+  /**不要多个 `<gem-route>` 共享，因为那样会导致后面的元素卸载前触发更新 */
   static createLocationStore = () => {
-    const { path, query, data } = history.getParams();
-    return createStore({ path, query, data, params: {} as Record<string, string> });
+    const { path, query, hash, data } = history.getParams();
+    return createStore({ path, query, hash, data, params: {} as Params });
   };
 
   static findRoute = (target: RouteItem[] | RoutesObject = [], path: string) => {
@@ -167,6 +187,10 @@ export class GemRouteElement extends GemElement<State> {
     return { route: defaultRoute };
   };
 
+  get #scrollContainer() {
+    return typeof this.scrollContainer === 'function' ? this.scrollContainer() : this.scrollContainer;
+  }
+
   constructor({ isLight, routes }: ConstructorOptions = {}) {
     super({ isLight });
     this.routes = routes;
@@ -177,38 +201,65 @@ export class GemRouteElement extends GemElement<State> {
   };
 
   #updateLocationStore = () => {
-    if (this.locationStore) {
-      const { path, query, data } = history.getParams();
-      updateStore(this.locationStore, {
-        path,
-        params: this.currentParams,
-        query,
-        data,
-      });
+    if (!this.locationStore) return;
+    const { path, query, hash, data } = history.getParams();
+    updateStore(this.locationStore, {
+      path,
+      params: this.currentParams,
+      query,
+      hash,
+      data,
+    });
+  };
+
+  #updateScrollContainerPosition = () => {
+    if (!this.#scrollContainer) return;
+    const scrollTop = scrollPositionMap.get(history.currentKey);
+    if (scrollTop) {
+      this.#scrollContainer.scroll(0, scrollTop);
+    } else if (this.scrollIgnoreHash || !history.getParams().hash) {
+      this.#scrollContainer.scroll(0, 0);
     }
   };
 
   #setContent = (route: RouteItem | null, params: Params, content?: TemplateResult) => {
+    this.beforeroutechange(route);
     this.#lastLoader = undefined;
     this.currentRoute = route;
     this.currentParams = params;
-    const changeContent = () => {
+    const changeContent = async () => {
       this.setState({ content });
-      this.routechange(this.currentRoute);
+      // 要确保新页面能读取到新路由数据
       this.#updateLocationStore();
+      // 等待页面渲染完成
+      await Promise.resolve();
+      this.#updateScrollContainerPosition();
+      this.routechange(this.currentRoute);
     };
     if (this.transition && 'startViewTransition' in document) {
-      (document as any).startViewTransition(() => {
-        changeContent();
-        // 等待路由渲染
-        return Promise.resolve();
-      });
+      (document as any).startViewTransition(() => changeContent());
     } else {
       changeContent();
     }
   };
 
   mounted() {
+    this.effect(
+      () => {
+        if (!this.#scrollContainer) return;
+        return addListener(history, 'beforechange', () =>
+          scrollPositionMap.set(history.currentKey, this.#scrollContainer!.scrollTop),
+        );
+      },
+      () => [this.scrollContainer],
+    );
+
+    this.effect(
+      // 触发 this.#update
+      () => connect(this.trigger.store, () => this.setState({})),
+      () => [this.trigger],
+    );
+
     this.effect(
       ([key, path], old) => {
         // 只有查询参数改变
@@ -216,40 +267,17 @@ export class GemRouteElement extends GemElement<State> {
           this.#updateLocationStore();
           return;
         }
-        const { route, params = {} } = GemRouteElement.findRoute(this.routes, path);
-        const { redirect, content, getContent } = route || {};
-        if (redirect) {
-          history.replace({ path: redirect });
-          return;
-        }
-        const title = route?.title;
-        if (title) updateStore(titleStore, { title });
-        const contentOrLoader = content || getContent?.(params);
-        if (contentOrLoader instanceof Promise) {
-          this.loading(route!);
-          this.#lastLoader = contentOrLoader;
-          const isSomeLoader = () => this.#lastLoader === contentOrLoader;
-          contentOrLoader
-            .then((content) => {
-              if (isSomeLoader()) this.#setContent(route, params, content);
-            })
-            .catch((err) => {
-              if (isSomeLoader()) this.error(err);
-            });
-          return;
-        }
-        this.#setContent(route, params, contentOrLoader);
+        this.update();
       },
       () => {
-        const { path } = history.getParams();
-        return [this.key, path, location.search];
+        const { path, query, hash } = this.trigger.getParams();
+        return [this.key, path, query, hash] as const;
       },
     );
   }
 
   shouldUpdate() {
-    if (this.inert) return false;
-    return true;
+    return this.inert ? false : true;
   }
 
   render() {
@@ -266,6 +294,35 @@ export class GemRouteElement extends GemElement<State> {
       ${content ?? html`<slot></slot>`}
     `;
   }
+
+  update = () => {
+    const { route, params = {} } = GemRouteElement.findRoute(this.routes, this.trigger.getParams().path);
+    const { redirect, content, getContent } = route || {};
+    if (redirect) {
+      this.trigger.replace({
+        path: createPath({ pattern: redirect }, { params }),
+      });
+      return;
+    }
+    if (this.trigger === history) {
+      updateStore(titleStore, { title: route?.title });
+    }
+    const contentOrLoader = content || getContent?.(params);
+    this.loading(route);
+    if (contentOrLoader instanceof Promise) {
+      this.#lastLoader = contentOrLoader;
+      const isSomeLoader = () => this.#lastLoader === contentOrLoader;
+      contentOrLoader
+        .then((content) => {
+          if (isSomeLoader()) this.#setContent(route, params, content);
+        })
+        .catch((err) => {
+          if (isSomeLoader()) this.error(err);
+        });
+      return;
+    }
+    this.#setContent(route, params, contentOrLoader);
+  };
 }
 
 export class GemLightRouteElement extends GemRouteElement {

package/src/elements/base/title.ts

@@ -17,18 +17,24 @@ import { GemElement, html } from '../../lib/element';
 import { attribute, boolattribute } from '../../lib/decorators';
 import { updateStore, connect } from '../../lib/store';
 import { titleStore } from '../../lib/history';
+import { addMicrotask } from '../../lib/utils';
 
 const defaultTitle = document.title;
 
+let documentTitle = '';
+const setTitle = () => (document.title = documentTitle);
+
 function setDocumentTitle(str?: string | null, prefix = '', suffix = '') {
   const title = titleStore.title || str;
   if (title && title !== defaultTitle) {
     GemTitleElement.title = title;
-    document.title = prefix + GemTitleElement.title + suffix;
+    documentTitle = prefix + GemTitleElement.title + suffix;
   } else {
     GemTitleElement.title = defaultTitle;
-    document.title = GemTitleElement.title;
+    documentTitle = GemTitleElement.title;
   }
+  // 避免重定向时的中间状态
+  addMicrotask(setTitle);
 }
 
 connect(titleStore, setDocumentTitle);
@@ -62,6 +68,7 @@ export class GemTitleElement extends GemElement {
     super();
     new MutationObserver(() => this.update()).observe(this, {
       characterData: true,
+      childList: true,
       subtree: true,
     });
   }

package/src/helper/i18n.ts

@@ -1,6 +1,9 @@
 import { createStore, updateStore, Store } from '../lib/store';
 import { html, TemplateResult } from '../lib/element';
 import { GemError } from '../lib/utils';
+import type { RouteTrigger } from '../elements/base/route';
+
+import { logger } from './logger';
 
 // Hello, $1
 // See $1<detail>
@@ -59,7 +62,7 @@ interface I18nOptions<T> {
   onChange?: (currentLanguage: string) => void;
 }
 
-export class I18n<T = Record<string, Msg>> {
+export class I18n<T = Record<string, Msg>> implements RouteTrigger {
   resources: Resources<T>;
   fallbackLanguage: string;
   currentLanguage: string;
@@ -71,6 +74,12 @@ export class I18n<T = Record<string, Msg>> {
 
   store: Store<any>;
 
+  replace = ({ path }: { path: string }) => {
+    this.setLanguage(path);
+  };
+
+  getParams = () => ({ path: this.currentLanguage });
+
   get #cacheCurrentKey() {
     return `${this.cachePrefix}:current`;
   }
@@ -164,8 +173,7 @@ export class I18n<T = Record<string, Msg>> {
     let pack: Partial<T>;
     const data = this.resources[lang];
     if (!data) {
-      // eslint-disable-next-line no-console
-      console.warn(`${this.cachePrefix}: not found \`${lang}\``);
+      logger.warn(`${this.cachePrefix}: not found \`${lang}\``);
       return this.resetLanguage();
     }
 
@@ -202,7 +210,7 @@ export class I18n<T = Record<string, Msg>> {
       pack = data;
     }
     this.resources[lang] = pack;
-    updateStore(this.store, {});
+    updateStore(this.store);
     if (lang !== this.currentLanguage) {
       this.#lang = lang;
     }

package/src/helper/logger.ts

@@ -0,0 +1,21 @@
+export class Logger {
+  _type: string;
+
+  constructor(type: string) {
+    this._type = type;
+  }
+
+  info = (...args: any[]) => {
+    console.log(`[${this._type}]:`, ...args);
+  };
+
+  warn = (...args: any[]) => {
+    console.warn(`[${this._type}]:`, ...args);
+  };
+
+  error = (...args: any[]) => {
+    console.error(`[${this._type}]:`, ...args);
+  };
+}
+
+export const logger = new Logger('GEM');

package/src/helper/ssr-shim.ts

@@ -2,7 +2,10 @@
 // @ts-nocheck
 if (typeof window === 'undefined') {
   const getAny = () => {
-    const anonymous = () => getAny();
+    // constructable
+    function anonymous() {
+      return getAny();
+    }
     Object.defineProperties(anonymous, {
       length: { writable: true },
       name: { writable: true },
@@ -16,14 +19,21 @@ if (typeof window === 'undefined') {
   };
   const any = getAny();
 
+  globalThis.window = globalThis;
+  globalThis.location = new URL('about:blank');
+  globalThis.HTMLElement = null;
+
   globalThis.document = any;
   globalThis.addEventListener = any;
   globalThis.history = any;
   globalThis.navigator = any;
   globalThis.customElements = any;
-  globalThis.HTMLElement = null;
-  globalThis.location = new URL('about:blank');
-  globalThis.window = globalThis;
+
+  // duoyun-ui
+  globalThis.CSSStyleSheet = any;
+  globalThis.Document = any;
+  globalThis.Element = any;
+  globalThis.MutationObserver = any;
 }
 
 export {};

package/src/lib/element.ts

@@ -13,6 +13,7 @@ import {
   kebabToCamelCase,
   PropProxyMap,
   removeItems,
+  addListener,
 } from './utils';
 import * as GemExports from './element';
 import * as VersionExports from './version';
@@ -75,12 +76,10 @@ const constructorSymbol = Symbol('constructor');
 const initSymbol = Symbol('init');
 const updateSymbol = Symbol('update');
 
-export interface GemElementOptions {
+export interface GemElementOptions extends Partial<ShadowRootInit> {
   isLight?: boolean;
   isAsync?: boolean;
-  // https://developer.mozilla.org/en-US/docs/Web/API/Element/attachShadow#options
-  delegatesFocus?: boolean;
-  slotAssignment?: 'named' | 'manual';
+  focusable?: boolean;
 }
 
 export abstract class GemElement<T = Record<string, unknown>> extends HTMLElement {
@@ -117,7 +116,7 @@ export abstract class GemElement<T = Record<string, unknown>> extends HTMLElemen
   #memoList?: EffectItem<any>[];
   #unmountCallback?: any;
 
-  constructor({ isAsync, isLight, delegatesFocus, slotAssignment }: GemElementOptions = {}) {
+  constructor(options: GemElementOptions = {}) {
     super();
 
     // 外部不可见，但允许类外面使用
@@ -130,8 +129,37 @@ export abstract class GemElement<T = Record<string, unknown>> extends HTMLElemen
       }
     });
 
-    this.#isAsync = isAsync;
-    this.#renderRoot = isLight ? this : this.attachShadow({ mode: 'open', delegatesFocus, slotAssignment });
+    this.#isAsync = options.isAsync;
+    this.#renderRoot = options.isLight
+      ? this
+      : this.attachShadow({
+          mode: options.mode || 'open',
+          delegatesFocus: options.delegatesFocus,
+          slotAssignment: options.slotAssignment,
+        });
+
+    // https://stackoverflow.com/questions/43836886/failed-to-construct-customelement-error-when-javascript-file-is-placed-in-head
+    // focusable 元素一般同时具备 disabled 属性
+    // 和原生元素行为保持一致，disabled 时不触发 click 事件
+    let hasInitTabIndex: boolean | undefined;
+    this.effect(
+      ([disabled = false]) => {
+        if (hasInitTabIndex === undefined) hasInitTabIndex = this.hasAttribute('tabindex');
+
+        this.internals.ariaDisabled = String(disabled);
+
+        if (options.focusable && !hasInitTabIndex) {
+          this.tabIndex = -Number(disabled);
+        }
+
+        if ((options.focusable || options.delegatesFocus) && disabled) {
+          return addListener(this, 'click', (e: Event) => e.isTrusted && e.stopImmediatePropagation(), {
+            capture: true,
+          });
+        }
+      },
+      () => [Reflect.get(this, 'disabled')],
+    );
 
     const { adoptedStyleSheets } = new.target;
     if (adoptedStyleSheets) {
@@ -248,7 +276,8 @@ export abstract class GemElement<T = Record<string, unknown>> extends HTMLElemen
 
   /**
    * @helper
-   * 在 `render` 前执行回调，和 `effect` 一样接受依赖数组参数，在 `constructor`/`willMount` 中使用;
+   * 在 `render` 前执行回调，不要在里面使用 `setState`
+   * 和 `effect` 一样接受依赖数组参数，在 `constructor`/`willMount` 中使用;
    * 第一次执行时 `oldDeps` 为空
    *
    * ```js
@@ -444,15 +473,17 @@ export abstract class GemElement<T = Record<string, unknown>> extends HTMLElemen
     this.#disconnectStore?.forEach((disconnect) => disconnect());
     execCallback(this.#unmountCallback);
     this.unmounted?.();
-    this.#effectList?.forEach(({ preCallback }) => execCallback(preCallback));
-    this.#effectList = this.#effectList?.filter(this.#filterEffect);
-    this.#memoList = this.#memoList?.filter(this.#filterEffect);
+    this.#effectList = this.#clearEffect(this.#effectList);
+    this.#memoList = this.#clearEffect(this.#memoList);
     return GemElement.#final;
   }
 
-  #filterEffect = (e: EffectItem<any>) => {
-    e.initialized = false;
-    return e.inConstructor;
+  #clearEffect = (list?: EffectItem<any>[]) => {
+    return list?.filter((e) => {
+      execCallback(e.preCallback);
+      e.initialized = false;
+      return e.inConstructor;
+    });
   };
 }
 
@@ -555,9 +586,7 @@ export function defineRef(target: GemElement, prop: string, ref: string) {
             return ref;
           },
           get element() {
-            const gemReflects = ([...ele.querySelectorAll('[data-gem-reflect]')] as GemReflectElement[]).map(
-              (e) => e.target,
-            );
+            const gemReflects = [...ele.querySelectorAll<GemReflectElement>('[data-gem-reflect]')].map((e) => e.target);
             for (const e of [ele, ...gemReflects]) {
               const result = e.querySelector(`[ref=${ref}]`);
               if (result) return result;

package/src/lib/history.ts

@@ -29,7 +29,7 @@ export interface UpdateHistoryParams {
   title?: string;
   path?: string; // 不包括 basePath，只有根目录储存末尾斜杠
   query?: string | QueryString; // 包含 `?`
-  hash?: string; // 包含 `#`
+  hash?: string; // 包含 `#`，不进行编码，方便比较
   // 以下为看不见的状态
   open?: () => void; // 按下前进键时执行
   close?: () => void; // 按下返回键时执行
@@ -38,7 +38,12 @@ export interface UpdateHistoryParams {
 }
 
 // 实际应用值
-type HistoryParams = UpdateHistoryParams & { title: string; path: string; query: QueryString; hash: string };
+type HistoryParams = Omit<UpdateHistoryParams, 'query'> & {
+  title: string;
+  path: string;
+  query: QueryString;
+  hash: string;
+};
 
 const paramsMap = new Map<string, HistoryParams>();
 
@@ -60,19 +65,26 @@ function getInternalPath(urlBarPath: string) {
   return urlBarPath.replace(new RegExp(`^${gemHistory.basePath}/`), '/');
 }
 
+function dispatchBeforeChangeEvent() {
+  gemHistory.dispatchEvent(new CustomEvent('beforechange'));
+}
+
 function normalizeParams(params: UpdateHistoryParams): HistoryParams {
-  const current = paramsMap.get(store.$key) || ({} as HistoryParams);
+  const current =
+    paramsMap.get(store.$key) ||
+    ({ path: getInternalPath(location.pathname), query: new QueryString() } as HistoryParams);
   // 没提供 path 使用当前 path
   const path = params.path ? absoluteLocation(current.path, params.path) : getInternalPath(location.pathname);
   // 没提供 query 又没有提供 path 时使用当前 search
-  const query = new QueryString(params.query || (params.path ? '' : location.search));
-  const pathChanged =
-    (params.path && params.path !== current.path) || (params.query && String(params.query) !== String(current.query));
+  const newQueryObject = new QueryString(params.query ?? (params.path ? '' : location.search));
+  const queryChanged = String(newQueryObject) !== String(current.query);
+  const query = queryChanged ? newQueryObject : current.query;
+  const urlChanged = path !== current.path || queryChanged;
   // 没提供 title 又没有改变 URL 时使用当前 document.title
-  const title = params.title || (pathChanged ? '' : document.title);
+  const title = params.title || (urlChanged ? '' : document.title);
   const statusChanged = params.close || params.data || params.open || params.shouldClose;
-  // 没提供 hash 又没有改变 URL 又不是状态更新时使用当前 hash
-  const hash = params.hash || (!pathChanged && statusChanged ? decodeURIComponent(location.hash) : '');
+  // 没提供 hash 又没有改变 URL 仅仅是状态更新时使用当前 hash
+  const hash = decodeURIComponent(params.hash ?? (!urlChanged && statusChanged ? location.hash : ''));
   return { ...params, title, path, query, hash };
 }
 
@@ -89,6 +101,7 @@ function updateHistory(p: UpdateHistoryParams, native: typeof nativeHistory.push
     ...data,
   };
   paramsMap.set(state.$key, params);
+  dispatchBeforeChangeEvent();
   cleanObject(store);
   updateHistoryStore(state);
   const url = getUrlBarPath(path) + new QueryString(query) + hash;
@@ -108,6 +121,7 @@ function updateHistoryByNative(data: any, title: string, originUrl: string, nati
   const { pathname, search, hash } = new URL(originUrl, location.origin + location.pathname);
   const params = normalizeParams({ path: pathname, query: new QueryString(search), hash, title, data });
   paramsMap.set(state.$key, params);
+  dispatchBeforeChangeEvent();
   cleanObject(store);
   updateHistoryStore(state);
   const url = getUrlBarPath(pathname) + params.query + hash;
@@ -121,10 +135,13 @@ const [gemBasePathStore, updateBasePathStore] = useStore({
   basePath: '',
 });
 
-class GemHistory {
+class GemHistory extends EventTarget {
   get store() {
     return store;
   }
+  get currentKey() {
+    return store.$key;
+  }
   get basePath() {
     return gemBasePathStore.basePath;
   }
@@ -190,7 +207,7 @@ if (!window._GEMHISTORY) {
   // 点击 `<a>`
   window.addEventListener('hashchange', ({ isTrusted }) => {
     if (isTrusted) {
-      gemHistory.replace({ hash: decodeURIComponent(location.hash) });
+      gemHistory.replace({ hash: location.hash });
     }
   });
 
@@ -254,7 +271,7 @@ if (!window._GEMHISTORY) {
       paramsMap.set(newState.$key, {
         path: pathname,
         query: new QueryString(search),
-        hash,
+        hash: decodeURIComponent(hash),
         title: newState.$title, // document.title 是导航前的
         data: newState,
       });
@@ -292,6 +309,7 @@ if (!window._GEMHISTORY) {
       }
     }
 
+    dispatchBeforeChangeEvent();
     cleanObject(store);
     updateHistoryStore(newState);
   });