Files

115 lines
3.9 KiB
TypeScript
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* 应用内引导漫游(driver.js)— 轻量方案
*
* - 各页面定义步骤(selector + i18n 文案 key),经 startTour() 启动
* - 「看过」标记存服务端 app_settings(tours_seen):桌面端每次启动端口随机,
* localStorage 随 origin 失效,故落库;localStorage 仅作离线兜底缓存
* - 首次自动弹、帮助按钮随时重看;跳过/完成都算看过
* - 主题样式沿用设计 token(火焰橙 accent),见 app.vue 内 .driver-theme 覆写
*/
import { driver } from 'driver.js'
import 'driver.js/dist/driver.css'
const SEEN_KEY = 'huobao:tours'
let seenSet = new Set<string>()
let hydrated = false
let hydratePromise: Promise<void> | null = null
function readLocal(): string[] {
try { return JSON.parse(localStorage.getItem(SEEN_KEY) || '[]') } catch { return [] }
}
function writeLocal(ids: string[]) {
try { localStorage.setItem(SEEN_KEY, JSON.stringify(ids)) } catch { /* ignore */ }
}
/**
* 从服务端拉取已看过的 tour id,与本地缓存取并集(保留升级前 localStorage 里的标记)。
* 由客户端插件在应用启动时调用;autoTour 在 onMounted 后延迟数百 ms 触发,此时已就绪。
*/
export function hydrateTours(): Promise<void> {
if (hydratePromise) return hydratePromise
hydratePromise = (async () => {
try {
const res = await fetch('/api/v1/settings/tours-seen')
const json = await res.json().catch(() => null)
const server: string[] = Array.isArray(json?.data?.seen) ? json.data.seen : []
seenSet = new Set([...server, ...readLocal()])
} catch {
seenSet = new Set(readLocal())
}
hydrated = true
writeLocal([...seenSet])
})()
return hydratePromise
}
export function tourSeen(id: string): boolean {
return seenSet.has(id) || readLocal().includes(id)
}
export function markTourSeen(id: string) {
if (seenSet.has(id)) return
seenSet.add(id)
writeLocal([...seenSet])
// 落库(fire-and-forget);未水合时先合并服务端数据避免覆盖其他页面已标记的 tour
void (async () => {
try {
if (!hydrated) await hydrateTours()
seenSet.add(id)
await fetch('/api/v1/settings/tours-seen', {
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ seen: [...seenSet] }),
})
} catch { /* 服务端不可达时 localStorage 已兜底 */ }
})()
}
export interface TourStep {
element: string // CSS selector;'#__nuxt' 等兜底表示居中弹窗(无高亮)
titleKey: string // i18n key
descKey: string // i18n key
popoverSide?: 'top' | 'bottom' | 'left' | 'right'
popoverAlign?: 'start' | 'center' | 'end'
}
/**
* 启动一段引导。t 为 useI18n 的翻译函数。
* 返回是否真正启动(元素缺失或步骤为空时静默跳过)。
*/
export function startTour(id: string, steps: TourStep[], t: (key: string) => string): boolean {
const usable = steps.filter(s => s.element === '#__nuxt' || document.querySelector(s.element))
if (!usable.length) return false
const drv = driver({
showProgress: true,
allowClose: true,
overlayClickBehavior: 'nextStep',
popoverClass: 'huobao-tour-popover',
progressText: '{{current}} / {{total}}',
nextBtnText: t('tour.next'),
prevBtnText: t('tour.prev'),
doneBtnText: t('tour.done'),
onDestroyed: () => markTourSeen(id),
steps: usable.map(s => ({
element: s.element,
popover: {
title: t(s.titleKey),
description: t(s.descKey),
side: s.popoverSide || 'bottom',
align: s.popoverAlign || 'start',
},
})),
})
drv.drive()
return true
}
/** 首次进入自动引导:看过或元素未就绪则跳过 */
export function autoTour(id: string, steps: TourStep[], t: (key: string) => string) {
if (tourSeen(id)) return
startTour(id, steps, t)
}