From 7621db10e90fdfed7782d864cd810c0a4220c7e7 Mon Sep 17 00:00:00 2001 From: mantou132 <709922234@qq.com> Date: Fri, 5 Jan 2024 15:20:39 +0800 Subject: [PATCH] [gem] Support scroll position restore Break change: - `GemRouteElement.locationStore` update by location hash --- .../duoyun-ui/src/elements/page-loadbar.ts | 2 + packages/duoyun-ui/src/lib/utils.ts | 14 ++- .../gem-book/docs/zh/002-guide/003-cli.md | 2 +- packages/gem-book/docs/zh/003-plugins.md | 4 +- packages/gem-book/src/element/elements/404.ts | 7 +- .../gem-book/src/element/elements/main.ts | 69 ++++++++------- .../gem-book/src/element/elements/meta.ts | 17 ++-- .../gem-book/src/element/elements/plugin.ts | 18 +++- .../gem-book/src/element/elements/sidebar.ts | 7 +- packages/gem-book/src/element/helper/theme.ts | 10 +-- packages/gem-book/src/element/index.ts | 35 +++----- packages/gem-book/src/element/lib/utils.ts | 10 --- packages/gem-book/src/element/store.ts | 15 ++-- packages/gem-book/src/plugins/api.ts | 1 + packages/gem-book/src/plugins/comment.ts | 16 ++-- packages/gem-book/src/plugins/raw.ts | 5 ++ packages/gem-examples/src/ref-route/index.ts | 2 +- .../gem/docs/en/004-blog/005-improve-route.md | 52 ++++++++--- .../gem/docs/zh/004-blog/005-improve-route.md | 61 +++++++++---- packages/gem/src/elements/base/route.ts | 87 +++++++++++++------ packages/gem/src/helper/i18n.ts | 2 +- packages/gem/src/lib/element.ts | 14 +-- packages/gem/src/lib/history.ts | 36 ++++++-- packages/gem/src/lib/utils.ts | 9 +- 24 files changed, 307 insertions(+), 188 deletions(-) diff --git a/packages/duoyun-ui/src/elements/page-loadbar.ts b/packages/duoyun-ui/src/elements/page-loadbar.ts index c85a687a..55a68c54 100644 --- a/packages/duoyun-ui/src/elements/page-loadbar.ts +++ b/packages/duoyun-ui/src/elements/page-loadbar.ts @@ -38,6 +38,7 @@ export class DuoyunPageLoadbarElement extends GemElement { static instance?: DuoyunPageLoadbarElement; static timer = 0; + /**在延时时间内结束将不会显示加载条 */ static async start({ delay = 100 }: { delay?: number } = {}) { clearInterval(Loadbar.timer); Loadbar.timer = window.setTimeout(() => { @@ -51,6 +52,7 @@ export class DuoyunPageLoadbarElement extends GemElement { } static async end() { + // 能同时取消 setTimeout ID clearInterval(Loadbar.timer); const instance = Loadbar.instance; if (instance) { diff --git a/packages/duoyun-ui/src/lib/utils.ts b/packages/duoyun-ui/src/lib/utils.ts index 5d30d2b3..a4a4aefa 100644 --- a/packages/duoyun-ui/src/lib/utils.ts +++ b/packages/duoyun-ui/src/lib/utils.ts @@ -377,7 +377,15 @@ export function useCacheStore>( } /**@deprecated use `useCacheStore` */ -export const createCacheStore = (...args: Parameters) => { - const [store, , save] = useCacheStore(...args); +export function createCacheStore>( + storageKey: string, + initStore: T, + options?: { + cacheExcludeKeys?: (keyof T)[]; + prefix?: string | (() => string | undefined); + depStore?: Store; + }, +) { + const [store, , save] = useCacheStore(storageKey, initStore, options); return [store, save] as const; -}; +} diff --git a/packages/gem-book/docs/zh/002-guide/003-cli.md b/packages/gem-book/docs/zh/002-guide/003-cli.md index 41519e37..7c59d78a 100644 --- a/packages/gem-book/docs/zh/002-guide/003-cli.md +++ b/packages/gem-book/docs/zh/002-guide/003-cli.md @@ -8,7 +8,7 @@ npx gem-book -h `gem-book` 命令会自动从项目根目录查找配置文件 `gem-book.cli.{js|json|mjs}`，支持大部分命令行选项（同时提供时合并命令行选项），例如: - + > [!TIP] > 如果用 `json` 格式，可以添加 `"$schema": "https://unpkg.com/gem-book/schema.json"` 以获取类型提示， diff --git a/packages/gem-book/docs/zh/003-plugins.md b/packages/gem-book/docs/zh/003-plugins.md index 7e13d2bb..12904b27 100644 --- a/packages/gem-book/docs/zh/003-plugins.md +++ b/packages/gem-book/docs/zh/003-plugins.md @@ -38,12 +38,12 @@ yarn add gem-book 用于显示远端代码，如果提供的 `src` 只包含路径，则会从当前项目的 GitHub 上读取内容（受 [`sourceDir`](./002-guide/003-cli.md#--source-dir)，[`sourceBranch`](./002-guide/003-cli.md#--source-branch) 影响），比如： - + ```md - + ``` ## `` diff --git a/packages/gem-book/src/element/elements/404.ts b/packages/gem-book/src/element/elements/404.ts index edfe6d23..6f175aaa 100644 --- a/packages/gem-book/src/element/elements/404.ts +++ b/packages/gem-book/src/element/elements/404.ts @@ -1,7 +1,7 @@ -import { connectStore, customElement, GemElement, history, html } from '@mantou/gem'; +import { connectStore, customElement, GemElement, html } from '@mantou/gem'; import { getGithubPath, getUserLink } from '../lib/utils'; -import { bookStore } from '../store'; +import { bookStore, locationStore } from '../store'; import { selfI18n } from '../helper/i18n'; import { icons } from './icons'; @@ -14,8 +14,7 @@ import '@mantou/gem/elements/title'; export class Meta extends GemElement { #getMdFullPath = () => { const { links = [] } = bookStore; - const { path } = history.getParams(); - const parts = path.replace(/\/$/, '').split('/'); + const parts = locationStore.path.replace(/\/$/, '').split('/'); const newFile = parts.pop(); const parentPath = parts.join('/'); const link = links.find(({ originLink }) => getUserLink(originLink).startsWith(parentPath)); diff --git a/packages/gem-book/src/element/elements/main.ts b/packages/gem-book/src/element/elements/main.ts index d3c93049..54330a51 100644 --- a/packages/gem-book/src/element/elements/main.ts +++ b/packages/gem-book/src/element/elements/main.ts @@ -1,4 +1,13 @@ -import { html, GemElement, customElement, css, property, createCSSSheet, adoptedStyle, history } from '@mantou/gem'; +import { + html, + GemElement, + customElement, + css, + property, + createCSSSheet, + adoptedStyle, + connectStore, +} from '@mantou/gem'; import { Renderer, parse } from 'marked'; import { mediaQuery } from '@mantou/gem/helper/mediaquery'; @@ -52,9 +61,10 @@ const linkStyle = css` @customElement('gem-book-main') @adoptedStyle(style) +@connectStore(locationStore) export class Main extends GemElement { - @property content: string; - @property renderer: Renderer; + @property content?: string; + @property renderer?: Renderer; // homepage/footer 等内置元素渲染在 main 前面，不能使用自定义渲染器 static instance?: Main; @@ -75,29 +85,23 @@ export class Main extends GemElement { constructor() { super(); Main.instance = this; - this.memo(() => { - const [, , _sToken, _frontmatter, _eToken, mdBody] = - this.content.match(/^(([\r\n\s]*---\s*(?:\r\n|\n))(.*?)((?:\r\n|\n)---\s*(?:\r\n|\n)?))?(.*)$/s) || []; - this.#content = mdBody; - }); + this.memo( + () => { + const [, , _sToken, _frontmatter, _eToken, mdBody = ''] = + this.content?.match(/^(([\r\n\s]*---\s*(?:\r\n|\n))(.*?)((?:\r\n|\n)---\s*(?:\r\n|\n)?))?(.*)$/s) || []; + this.#content = Main.parseMarkdown(mdBody); + }, + () => [this.content], + ); } - #content = ''; + #content: Element[] = []; - #hashChangeHandle = () => { - const { hash, path } = history.getParams(); - // 确保是页内跳转或者新页（mounted）跳转 - if (hash && path === locationStore.path) { - this.shadowRoot?.querySelector(`[id="${decodeURIComponent(hash.slice(1))}"]`)?.scrollIntoView({ - block: 'start', - }); - } - }; - - #updateToc = () => + #updateToc = () => { updateTocStore({ elements: [...this.shadowRoot!.querySelectorAll('h2,h3')], }); + }; render() { return html` @@ -315,7 +319,7 @@ export class Main extends GemElement { } } - ${Main.parseMarkdown(this.#content)} + ${this.#content} @@ -325,23 +329,30 @@ export class Main extends GemElement { mounted() { this.effect( () => { + checkBuiltInPlugin(this.shadowRoot!); + this.#updateToc(); + const mo = new MutationObserver(this.#updateToc); mo.observe(this.shadowRoot!, { childList: true, subtree: true, }); - checkBuiltInPlugin(this.shadowRoot!); - this.#hashChangeHandle(); - window.addEventListener('hashchange', this.#hashChangeHandle); - - return () => { - window.removeEventListener('hashchange', this.#hashChangeHandle); - mo.disconnect(); - }; + return () => mo.disconnect(); }, () => [this.content], ); + + this.effect( + ([hash]) => { + if (hash) { + this.shadowRoot?.querySelector(`[id="${hash.slice(1)}"]`)?.scrollIntoView({ + block: 'start', + }); + } + }, + () => [locationStore.hash], + ); } } diff --git a/packages/gem-book/src/element/elements/meta.ts b/packages/gem-book/src/element/elements/meta.ts index b33d7655..56a77036 100644 --- a/packages/gem-book/src/element/elements/meta.ts +++ b/packages/gem-book/src/element/elements/meta.ts @@ -1,18 +1,25 @@ -import { connectStore, customElement, GemElement, html, history } from '@mantou/gem'; +import { connectStore, customElement, GemElement, html } from '@mantou/gem'; import { mediaQuery } from '@mantou/gem/helper/mediaquery'; -import { getAlternateUrl, getURL } from '../lib/utils'; -import { bookStore } from '../store'; +import { getRemotePath, getURL } from '../lib/utils'; +import { bookStore, locationStore } from '../store'; import '@mantou/gem/elements/reflect'; +function getAlternateUrl(lang: string, pathname?: string) { + const { origin } = location; + const { path, query, hash } = locationStore; + const fullPath = getRemotePath(pathname || path, lang); + if (pathname) return `${origin}${fullPath}`; + return `${origin}${fullPath}${query}${hash}`; +} + @customElement('gem-book-meta') @connectStore(bookStore) export class Meta extends GemElement { render() { const { langList, lang = '', routes, homePage, getCurrentLink, currentLinks } = bookStore; - const { path } = history.getParams(); - const route = routes?.find((route) => route.pattern === path && route.redirect); + const route = routes?.find((route) => route.pattern === locationStore.path && route.redirect); const canonicalLink = getAlternateUrl( lang && langList && !location.pathname.startsWith(`/${lang}`) ? langList[0].code : lang, route?.redirect, diff --git a/packages/gem-book/src/element/elements/plugin.ts b/packages/gem-book/src/element/elements/plugin.ts index abde0237..1e965928 100644 --- a/packages/gem-book/src/element/elements/plugin.ts +++ b/packages/gem-book/src/element/elements/plugin.ts @@ -5,7 +5,7 @@ import { mediaQuery } from '@mantou/gem/helper/mediaquery'; import { logger } from '@mantou/gem/helper/logger'; import { theme } from '../helper/theme'; -import { bookStore } from '../store'; +import { bookStore, locationStore } from '../store'; import { BookConfig } from '../../common/config'; import { icons } from '../elements/icons'; @@ -17,6 +17,7 @@ export class GemBookPluginElement extends GemElement { static theme = theme; static icons = icons; static mediaQuery = mediaQuery; + static locationStore = locationStore; static config = new Proxy>( {}, { @@ -56,6 +57,21 @@ export class GemBookPluginElement extends GemElement { return bookStore.getCurrentLink?.(); } + static caches?: Map; + + cacheState(getDeps: () => string[]) { + if (!this.state) throw new Error('Only cache state'); + const cons = this.constructor as typeof GemBookPluginElement; + const caches = cons.caches || (cons.caches = new Map()); + this.memo( + () => { + Object.assign(this.state!, caches.get(getDeps().join())); + return () => caches.set(getDeps().join(), this.state); + }, + () => getDeps(), + ); + } + @globalemitter error: Emitter = logger.error; /**获取资源的远端 GitHub raw 地址，如果使用 `DEV_MODE`，则返回本机服务的 URL */ diff --git a/packages/gem-book/src/element/elements/sidebar.ts b/packages/gem-book/src/element/elements/sidebar.ts index 71353296..d7e8d2e6 100644 --- a/packages/gem-book/src/element/elements/sidebar.ts +++ b/packages/gem-book/src/element/elements/sidebar.ts @@ -10,7 +10,6 @@ import { useStore, refobject, RefObject, - history, } from '@mantou/gem'; import { mediaQuery } from '@mantou/gem/helper/mediaquery'; @@ -18,7 +17,6 @@ import { NavItem } from '../../common/config'; import { capitalize, isSameOrigin } from '../lib/utils'; import { theme } from '../helper/theme'; import { bookStore, locationStore } from '../store'; -import { GemBookElement } from '..'; import { icons } from './icons'; import { tocStore } from './toc'; @@ -63,7 +61,6 @@ export class SideBar extends GemElement { { type = 'file', link, title, children, sidebarIgnore }: NavItem, isTop = false, ): TemplateResult | null => { - const { path } = history.getParams(); const { homePage, config } = bookStore; const { homeMode, onlyFile } = config || {}; if (sidebarIgnore || (homeMode && homePage === link)) { @@ -91,7 +88,7 @@ export class SideBar extends GemElement { > ${title ? capitalize(title) : 'No title'} - ${!onlyFile && path === link + ${!onlyFile && locationStore.path === link ? html`
${tocStore.elements .filter((e) => e.tagName === 'H2') @@ -272,7 +269,7 @@ export class SideBar extends GemElement { } - +
${mediaQuery.isPhone && topNavList?.length diff --git a/packages/gem-book/src/element/helper/theme.ts b/packages/gem-book/src/element/helper/theme.ts index 6fae0d1d..4d8c16f0 100644 --- a/packages/gem-book/src/element/helper/theme.ts +++ b/packages/gem-book/src/element/helper/theme.ts @@ -1,4 +1,4 @@ -import { createTheme, getThemeProps, getThemeStore, updateTheme } from '@mantou/gem/helper/theme'; +import { getThemeProps, getThemeStore, useTheme } from '@mantou/gem/helper/theme'; import { defaultTheme } from './default-theme'; @@ -31,12 +31,10 @@ function generateTheme(theme: Theme) { }; } -export const theme = createTheme(generateTheme(defaultTheme)); +export const [theme, updateTheme] = useTheme(generateTheme(defaultTheme)); export const themeStore = getThemeStore(theme); export const themeProps = getThemeProps(theme); -export function changeTheme(newTheme?: Partial) { - if (newTheme) { - updateTheme(theme, generateTheme({ ...getThemeStore(theme), ...newTheme })); - } +export function changeTheme(newTheme: Partial = {}) { + updateTheme(generateTheme({ ...getThemeStore(theme), ...newTheme })); } diff --git a/packages/gem-book/src/element/index.ts b/packages/gem-book/src/element/index.ts index 1f7620a5..cb9fc72f 100644 --- a/packages/gem-book/src/element/index.ts +++ b/packages/gem-book/src/element/index.ts @@ -5,7 +5,6 @@ import { property, attribute, connectStore, - history, Emitter, part, slot, @@ -109,18 +108,13 @@ export class GemBookElement extends GemElement { }); } - changeTheme(newTheme?: Partial) { - return changeTheme(newTheme); - } - #onLoading = () => { Loadbar.start(); }; - #onRouteChange = (e: CustomEvent) => { + #onRouteChange = () => { Loadbar.end(); - document.body.scroll(0, 0); - this.routechange(e.detail); + this.routechange(null); }; render() { @@ -128,12 +122,11 @@ export class GemBookElement extends GemElement { if (!config) return null; const { icon = '', title = '', homeMode } = config; - const { path } = history.getParams(); const hasNavbar = icon || title || nav.length; - const renderHomePage = homeMode && homePage === path; + const renderHomePage = homeMode && homePage === locationStore.path; const missSidebar = homeMode ? currentSidebar?.every((e) => e.link === homePage) : !currentSidebar?.length; // 首次渲染 - const isRedirectRoute = routes.find(({ pattern }) => matchPath(pattern, path))?.redirect; + const isRedirectRoute = routes.find(({ pattern }) => matchPath(pattern, locationStore.path))?.redirect; const renderFullWidth = renderHomePage || (missSidebar && !isRedirectRoute); this.isHomePage = !!renderHomePage; @@ -287,6 +280,7 @@ export class GemBookElement extends GemElement { .locationStore=${locationStore} .key=${lang} .routes=${routes} + .scrollContainer=${document.body} @loading=${this.#onLoading} @routechange=${this.#onRouteChange} > @@ -302,26 +296,21 @@ export class GemBookElement extends GemElement { mounted() { this.effect( async () => { - if (this.src) { - const config = await (await fetch(this.src)).json(); - updateBookConfig(config, this); - } + if (!this.src) return; + const config = await (await fetch(this.src)).json(); + updateBookConfig(config, this); }, () => [this.src], ); this.effect( - () => { - if (this.config) { - updateBookConfig(this.config, this); - } - }, + () => updateBookConfig(this.config, this), () => [this.config], ); this.effect( - () => { - changeTheme(this.theme); - }, + () => changeTheme(this.theme), () => [this.theme], ); } + + changeTheme = changeTheme; } diff --git a/packages/gem-book/src/element/lib/utils.ts b/packages/gem-book/src/element/lib/utils.ts index 6d463eb2..52c7ebad 100644 --- a/packages/gem-book/src/element/lib/utils.ts +++ b/packages/gem-book/src/element/lib/utils.ts @@ -1,5 +1,3 @@ -import { history } from '@mantou/gem'; - import { NavItem } from '../../common/config'; import { isIndexFile, parseFilename } from '../../common/utils'; import { bookStore } from '../store'; @@ -41,14 +39,6 @@ export function getURL(originPath: string, lang = '', hash = '') { return `${getRemotePath(originPath, lang)}?hash=${hash}`; } -export function getAlternateUrl(lang: string, pathname?: string) { - const { origin } = location; - const { path, query, hash } = history.getParams(); - const fullPath = getRemotePath(pathname || path, lang); - if (pathname) return `${origin}${fullPath}`; - return `${origin}${fullPath}${query}${hash}`; -} - export function isSameOrigin(link: string) { const { origin } = new URL(link, location.origin); return origin === location.origin; diff --git a/packages/gem-book/src/element/store.ts b/packages/gem-book/src/element/store.ts index c3d58ed8..fa839f50 100644 --- a/packages/gem-book/src/element/store.ts +++ b/packages/gem-book/src/element/store.ts @@ -8,10 +8,7 @@ import { selfI18n } from './helper/i18n'; import { getLinkPath, getUserLink, NavItemWithLink, flatNav, capitalize, getURL } from './lib/utils'; import { getRenderer } from './lib/renderer'; -import { GemBookElement } from '.'; - -import './elements/main'; -import './elements/404'; +import type { GemBookElement } from '.'; interface CurrentBookConfig { config: BookConfig; @@ -151,6 +148,7 @@ function getLinkRouters(links: NavItemWithLink[], title: string, lang: string, d title: routeTitle, pattern: link, async getContent() { + await import('./elements/main'); const renderer = getRenderer({ lang, link: originLink, displayRank }); const content = await (await fetch(getURL(originLink, lang, hash))).text(); if (bookStore.isDevMode?.()) await new Promise((res) => setTimeout(res, 500)); @@ -191,7 +189,10 @@ function getLinkRouters(links: NavItemWithLink[], title: string, lang: string, d routes.push({ pattern: '*', - content: html``, + async getContent() { + await import('./elements/404'); + return html``; + }, }); return routes; @@ -200,8 +201,6 @@ function getLinkRouters(links: NavItemWithLink[], title: string, lang: string, d // 如果当前路径不在 isNav 目录中，则返回除所有 isNav 目录的内容 // 不考虑嵌套 isNav 目录 function getCurrentSidebar(sidebar: NavItemWithLink[]) { - const { path } = history.getParams(); - let currentLink: NavItemWithLink | undefined; let currentNavNode: NavItemWithLink | undefined; let resultNavNode: NavItemWithLink | undefined; @@ -210,7 +209,7 @@ function getCurrentSidebar(sidebar: NavItemWithLink[]) { const traverseSidebar = (items: NavItemWithLink[], result: NavItemWithLink[]) => { items.forEach((item) => { let tempNode: NavItemWithLink | undefined; - if (item.link === path) { + if (item.link === locationStore.path) { currentLink = item; if (!resultNavNode && currentNavNode && item.type === 'file') { resultNavNode = currentNavNode; diff --git a/packages/gem-book/src/plugins/api.ts b/packages/gem-book/src/plugins/api.ts index 0a1149be..7309bbc2 100644 --- a/packages/gem-book/src/plugins/api.ts +++ b/packages/gem-book/src/plugins/api.ts @@ -46,6 +46,7 @@ customElements.whenDefined('gem-book').then(() => { constructor() { super({ isLight: true }); + this.cacheState(() => [this.name, this.src]); } state: State = {}; diff --git a/packages/gem-book/src/plugins/comment.ts b/packages/gem-book/src/plugins/comment.ts index c1684111..e5820104 100644 --- a/packages/gem-book/src/plugins/comment.ts +++ b/packages/gem-book/src/plugins/comment.ts @@ -5,10 +5,11 @@ const gitalkCSSUrl = 'https://esm.sh/gitalk@1.7.2/dist/gitalk.css'; customElements.whenDefined('gem-book').then(async () => { const { GemBookPluginElement } = customElements.get('gem-book') as typeof GemBookElement; - const { config, Gem, theme } = GemBookPluginElement; - const { html, customElement, attribute, history } = Gem; + const { config, Gem, theme, locationStore } = GemBookPluginElement; + const { html, customElement, attribute, connectStore } = Gem; @customElement('gbp-comment') + @connectStore(locationStore) class _GbpCommentElement extends GemBookPluginElement { @attribute clientID: string; @attribute clientSecret: string; @@ -79,18 +80,17 @@ customElements.whenDefined('gem-book').then(async () => { repo: this.repo || repo, owner: this.owner || owner, admin: [owner].concat(this.admin.split(',')), - id: `${location.origin}${history.getParams().path}`, + id: `${location.origin}${locationStore.path}`, distractionFreeMode: false, language: GemBookPluginElement.lang, }).render(ele); } mounted() { - this.init(); - } - - updated() { - this.init(); + this.effect( + () => this.init(), + () => [locationStore.path], + ); } } }); diff --git a/packages/gem-book/src/plugins/raw.ts b/packages/gem-book/src/plugins/raw.ts index 99197f3c..181a9cae 100644 --- a/packages/gem-book/src/plugins/raw.ts +++ b/packages/gem-book/src/plugins/raw.ts @@ -51,6 +51,11 @@ customElements.whenDefined('gem-book').then(() => { @attribute range: string; @attribute highlight: string; + constructor() { + super(); + this.cacheState(() => [this.src]); + } + state: State = { content: '', }; diff --git a/packages/gem-examples/src/ref-route/index.ts b/packages/gem-examples/src/ref-route/index.ts index b0539024..01fe0706 100644 --- a/packages/gem-examples/src/ref-route/index.ts +++ b/packages/gem-examples/src/ref-route/index.ts @@ -99,7 +99,7 @@ export class App extends GemElement { ` +## Read URL parameters `GemRouteElement` has a `createLocationStore` method, which creates a [Store](../001-guide/001-basic/003-global-state-management.md) containing the URL parameters and then provides it to ` ` to get updates after a new page loads, for example: @@ -28,26 +29,49 @@ html` `; -``` -> [!Tip] -> -> `route-change`, `loading` events of `` allow you to add a progress bar for page loading -> -> Read URL parameters from `locationStore` in pages to prevent unnecessary updates to old pages that are not unloaded: - -```ts -@customElement('my-element') +@customElement('page-about') @connectStore(locationStore) -class MyElement extends GemElement { +class PageAboutElement extends GemElement { render = () => { return html`${locationStore.query}`; }; } ``` -Now you have a better user experience for your app routing switch. +## Restore scrollbar + +`` can automatically restore the scrollbar position. It is called immediately after the route is rendered: + +```ts 5 +html` + +`; +``` + +> [!NOTE] +> Scroll based on `hash` requires additional logic, for example: +> +> ```ts +> this.effect( +> ([hash]) => { +> if (!hash) return; +> this.shadowRoot +> ?.querySelector(`[id="${hash.slice(1)}"]`) +> ?.scrollIntoView({ +> block: 'start', +> }); +> }, +> () => [locationStore.hash], +> ); +> ``` diff --git a/packages/gem/docs/zh/004-blog/005-improve-route.md b/packages/gem/docs/zh/004-blog/005-improve-route.md index 6bda41a6..433b8661 100644 --- a/packages/gem/docs/zh/004-blog/005-improve-route.md +++ b/packages/gem/docs/zh/004-blog/005-improve-route.md @@ -5,21 +5,21 @@ ## 问题 -当切换路由时，当前组件被立即卸载，随即动态加载新组件的资源，加载好了再渲染组件，期间，将会显示白屏或者一个简单的加载器。 +当切换路由时，当前页面被立即卸载，随即动态加载新页面的资源，加载好了再渲染页面，期间，将会显示白屏或者一个简单的加载器。 +如果加载时间由于一些原因较慢，那么用户将长时间看不到有效内容从而造成焦虑。 ## 优化策略 切换路由时，不立刻卸载组件，而是显示新页面加载的进度条，当新页面已经准备就绪时，再卸载旧页面，挂载新页面， -这样，我们不会看到白屏，改善用户体验。 +这样，我们不会看到白屏，改善用户体验。采用此种策略后，需要注意几点： -采用此种策略后，需要注意两点： - -1. 旧页面不会立即卸载，当 URL 改变时，需要禁止旧页面根据 URL 进行更新 +1. 旧页面不会立即卸载，当 URL 改变时，旧页面可能会响应 URL 的更改读取错误的 URL 参数 2. 如果网速稍慢，连续多次切换路由时，需要保证渲染最终正确的页面 +3. 新页面加载后应该重置滚动条位置，当使用浏览器“前进”、“后退”后应该恢复滚动条位置 -## 使用 `` +## 安全的获取 URL 参数 -`GemRouteElement` 有一个 `createLocationStore` 方法，他会创建一个包含 URL 参数的 [Store](../001-guide/001-basic/003-global-state-management.md)，然后将它提供给 `` 即可在新页面加载后获得更新，例如： +`GemRouteElement` 有一个 `createLocationStore` 静态方法，他会创建一个包含 URL 参数的 [Store](../001-guide/001-basic/003-global-state-management.md)，只需将它提供给 `` 即可从中安全的获取 URL 参数，例如： ```ts const locationStore = GemRouteElement.createLocationStore(); @@ -28,26 +28,49 @@ html` `; -``` - -> [!TIP] -> -> `` 的 `route-change`, `loading` 事件允许你添加页面加载的进度条 - -在页面中从 `locationStore` 读取 URL 参数，防止未卸载的旧页面进行不必要的更新： -```ts -@customElement('my-element') +@customElement('page-about') @connectStore(locationStore) -class MyElement extends GemElement { +class PageAboutElement extends GemElement { render = () => { return html`${locationStore.query}`; }; } ``` -现在，你已经为你的应用路由切换提供了更好的用户体验。 +## 恢复滚动条位置 + +`` 可以自动恢复滚动条位置，它在路由渲染完后立即调用，只需要为它指定滚动容器即可： + +```ts 5 +html` + +`; +``` + +> [!NOTE] +> 根据 `hash` 跳转需要另外的逻辑，例如： +> +> ```ts +> this.effect( +> ([hash]) => { +> if (!hash) return; +> this.shadowRoot +> ?.querySelector(`[id="${hash.slice(1)}"]`) +> ?.scrollIntoView({ +> block: 'start', +> }); +> }, +> () => [locationStore.hash], +> ); +> ``` diff --git a/packages/gem/src/elements/base/route.ts b/packages/gem/src/elements/base/route.ts index 6a51d554..48c5c02f 100644 --- a/packages/gem/src/elements/base/route.ts +++ b/packages/gem/src/elements/base/route.ts @@ -2,7 +2,7 @@ import { GemElement, html, TemplateResult } from '../../lib/element'; 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; @@ -114,9 +114,11 @@ type State = { export type RouteTrigger = { store: Store; replace: (arg: { path: string }) => void; - getParams: () => { path: string; query: any }; + getParams: () => { path: string; query?: string | QueryString; hash?: string }; }; +const scrollPositionMap = new Map(); + /** * @attr inert 暂停路由更新 * @fires routechange @@ -127,18 +129,24 @@ export class GemRouteElement extends GemElement { @boolattribute transition: boolean; @property routes?: RouteItem[] | RoutesObject; /** - * 不要多个 `` 共享，因为那样会导致后面的元素卸载前触发更新 + * 路由更新后更新的 store，能从中读取到安全的路由数据 * * @example * const locationStore = GemRouteElement.createLocationStore() * html`` */ - @property locationStore?: Store<{ path: string; params: Params; query: QueryString; data?: any }>; + @property locationStore?: ReturnType<(typeof GemRouteElement)['createLocationStore']>; @property key?: any; // 除了 href 提供另外一种方式来更新，比如语言更新也需要刷新 + @emitter loading: Emitter; + @emitter beforeroutechange: Emitter; @emitter routechange: Emitter; // path 改变或者 key 改变，包含初始渲染 - @emitter loading: Emitter; @emitter error: Emitter; + /**自动让滚动容器恢复滚动位置 */ + @property scrollContainer?: HTMLElement | (() => HTMLElement); + /**默认当有 `hash` 时不进行滚动 */ + @property scrollIgnoreHash?: boolean; + @property trigger: RouteTrigger = history; /**当前使用的路由对象 */ @@ -148,9 +156,10 @@ export class GemRouteElement extends GemElement { #lastLoader?: Promise; + /**不要多个 `` 共享，因为那样会导致后面的元素卸载前触发更新 */ static createLocationStore = () => { - const { path, query, data } = history.getParams(); - return createStore({ path, query, data, params: {} as Record }); + const { path, query, hash, data } = history.getParams(); + return createStore({ path, query, hash, data, params: {} as Params }); }; static findRoute = (target: RouteItem[] | RoutesObject = [], path: string) => { @@ -174,6 +183,10 @@ export class GemRouteElement extends GemElement { return { route: defaultRoute }; }; + get #scrollContainer() { + return typeof this.scrollContainer === 'function' ? this.scrollContainer() : this.scrollContainer; + } + constructor({ isLight, routes }: ConstructorOptions = {}) { super({ isLight }); this.routes = routes; @@ -184,38 +197,59 @@ export class GemRouteElement extends GemElement { }; #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({})), @@ -232,15 +266,14 @@ export class GemRouteElement extends GemElement { this.update(); }, () => { - const { path, query } = this.trigger.getParams(); - return [this.key, path + query]; + 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() { @@ -269,8 +302,8 @@ export class GemRouteElement extends GemElement { updateStore(titleStore, { title: route?.title }); } const contentOrLoader = content || getContent?.(params); + this.loading(route); if (contentOrLoader instanceof Promise) { - this.loading(route!); this.#lastLoader = contentOrLoader; const isSomeLoader = () => this.#lastLoader === contentOrLoader; contentOrLoader diff --git a/packages/gem/src/helper/i18n.ts b/packages/gem/src/helper/i18n.ts index 266bb710..0a91824d 100644 --- a/packages/gem/src/helper/i18n.ts +++ b/packages/gem/src/helper/i18n.ts @@ -78,7 +78,7 @@ export class I18n> implements RouteTrigger { this.setLanguage(path); }; - getParams = () => ({ path: this.currentLanguage, query: '' }); + getParams = () => ({ path: this.currentLanguage }); get #cacheCurrentKey() { return `${this.cachePrefix}:current`; diff --git a/packages/gem/src/lib/element.ts b/packages/gem/src/lib/element.ts index 3c93e1de..54cb94b9 100644 --- a/packages/gem/src/lib/element.ts +++ b/packages/gem/src/lib/element.ts @@ -473,15 +473,17 @@ export abstract class GemElement> 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) => { - e.initialized = false; - return e.inConstructor; + #clearEffect = (list?: EffectItem[]) => { + return list?.filter((e) => { + execCallback(e.preCallback); + e.initialized = false; + return e.inConstructor; + }); }; } diff --git a/packages/gem/src/lib/history.ts b/packages/gem/src/lib/history.ts index cfa582a1..6e8a0162 100644 --- a/packages/gem/src/lib/history.ts +++ b/packages/gem/src/lib/history.ts @@ -38,7 +38,12 @@ export interface UpdateHistoryParams { } // 实际应用值 -type HistoryParams = UpdateHistoryParams & { title: string; path: string; query: QueryString; hash: string }; +type HistoryParams = Omit & { + title: string; + path: string; + query: QueryString; + hash: string; +}; const paramsMap = new Map(); @@ -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 = decodeURIComponent(params.hash ? params.hash : !pathChanged && statusChanged ? 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; } @@ -292,6 +309,7 @@ if (!window._GEMHISTORY) { } } + dispatchBeforeChangeEvent(); cleanObject(store); updateHistoryStore(newState); }); diff --git a/packages/gem/src/lib/utils.ts b/packages/gem/src/lib/utils.ts index 363822eb..9faaf27c 100644 --- a/packages/gem/src/lib/utils.ts +++ b/packages/gem/src/lib/utils.ts @@ -279,12 +279,9 @@ export function createCSSSheet(rules: T | string, return sheet as Sheet; } -export function randomStr(number = 5, origin = '0123456789abcdefghijklmnopqrstuvwxyz') { - const len = origin.length; - let str = ''; - for (let i = 0; i < number; i++) { - str += origin[Math.floor(Math.random() * len)]; - } +export function randomStr(len = 5): string { + const str = Math.random().toString(36).slice(2).slice(0, len); + if (str.length < len) return str + randomStr(len - str.length); return str; }