@epxing/utils 0.0.0-stage → 5.3.0-beta.1

package/src/nav-history.js

@@ -0,0 +1,274 @@
+/**
+ * 导航历史记账器：让浏览器历史与内部页面栈/弹窗严格一一对应
+ *
+ * 背景：本框架的页面栈是内存栈（epx-router-view 的 routes 数组），与浏览器
+ * history 天然脱钩。旧实现打开页面时 pushState 哑条目、应用内返回却从不回退
+ * 历史，且每个页面组件各挂一个 popstate 监听——导致移动端系统返回手势要按
+ * 很多次才能退出应用、根页面按返回没反应等问题。
+ *
+ * 记账规则（每个「可关闭物」对应恰好一条浏览器历史）：
+ * - 打开页面 / 新标签 / 弹窗 / 抽屉时 pushEntry() 压入一条哑历史
+ * - 系统返回（popstate）：全局唯一监听器按文档序找到最顶层可见的
+ *   routerView，让其栈顶页面执行一次 backPage（弹窗页会走弹窗分支）
+ * - 应用内主动关闭（返回按钮 / 弹窗 X / 遮罩等）：consume() 对称回退等量历史
+ * 由此系统返回在任意时刻的语义都是「关一层」；条目耗尽后再按返回即可
+ * 直接回到上一个应用/页面。
+ */
+
+const state = {
+  // 当前由本应用压入且未被消耗的哑历史条数
+  entryCount: 0,
+  // 待吞掉的、由 consume/leaveApp 自身 history.go 触发的 popstate 数
+  suppressCount: 0,
+  suppressDeadline: 0,
+  // 正在处理系统返回：此期间联动触发的关闭动作不再回退历史
+  handlingPop: false,
+  // 冷启动退出守卫是否生效（见 install/markAppJump）
+  guardMode: false
+}
+
+// 所有存活的 epx-router-view 实例（含弹窗/抽屉内的）
+const routerViews = []
+
+// 待合并回退的历史条数（微任务内一次 history.go，避免与 pushState 时序交错）
+let pendingGo = 0
+let flushScheduled = false
+
+// 当前应用上下文标识（路由路径前 4 段，容忍 role 等尾段差异）
+// 大厅→应用 的正向跳转是 pushState+reload 整页重启（见 AppList.vue），
+// 反向回退若不重启：hall 与 app 路由共用 App 组件，vue-router 复用实例导致白屏
+let bootIdentity = ''
+
+// 冷启动退出守卫（state.guardMode）：应用不是从大厅/上个应用跳转而来时
+// （无 epx-nav-prev 标记），移动端启动即压一条守卫条目，返回键打到守卫上就
+// 原地补一条（视觉无操作），恢复旧版「防止移动端返回键直接退出网页」的语义；
+// 从大厅跳转而来的应用不设守卫，根页面一次返回即回大厅
+const PREV_CONTEXT_KEY = 'epx-nav-prev'
+
+function pushGuard () {
+  window.history.pushState({ epxGuard: true }, '')
+}
+
+/**
+ * 跨应用跳转（大厅点应用 / 返回大厅 / 打开其他应用）前调用：
+ * 在 sessionStorage 留下标记，目标应用启动时据此关闭退出守卫，使返回键可以回到本页
+ */
+export function markAppJump () {
+  try {
+    sessionStorage.setItem(PREV_CONTEXT_KEY, window.location.href)
+  } catch (e) {
+    // sessionStorage 不可用（隐私模式等）时退化为守卫模式
+  }
+}
+
+function routeIdentity () {
+  const hash = window.location.hash || ''
+  let path = hash.charAt(0) === '#' ? hash.slice(1) : window.location.pathname
+  path = path.split('?')[0]
+  return path.split('/').filter(Boolean).slice(0, 4).join('/')
+}
+
+/**
+ * 真实回退落到了本应用上下文之外（返回服务大厅/上一个应用）时整页重启目标路由，
+ * 与正向 pushState+reload 对称；同应用内的回退不受影响
+ */
+function reloadIfLeftContext () {
+  if (bootIdentity && routeIdentity() !== bootIdentity) {
+    window.location.reload()
+    return true
+  }
+  return false
+}
+
+/**
+ * 未拦截的回退（含 leaveApp/consume 自发的）落点处理：
+ * 离开应用上下文 → 整页重启目标路由；仍在应用内且已无可关闭物 → 守卫模式下补回守卫条目
+ */
+function handleLanding () {
+  if (reloadIfLeftContext()) return
+  if (state.guardMode && state.entryCount <= 0 && pendingGo <= 0) {
+    pushGuard()
+  }
+}
+
+export function registerRouterView (rv) {
+  if (routerViews.indexOf(rv) === -1) routerViews.push(rv)
+}
+
+export function unregisterRouterView (rv) {
+  const index = routerViews.indexOf(rv)
+  if (index > -1) routerViews.splice(index, 1)
+}
+
+/**
+ * 打开一个可关闭物（页面/新标签/弹窗/抽屉）时调用，压入一条哑历史。
+ * state 里记录当前深度，供整页刷新后 install() 恢复计数。
+ */
+export function pushEntry () {
+  // 应用上下文可能在启动后被路由守卫补全（如追加 role 段），压条目时刷新基准
+  bootIdentity = routeIdentity()
+  if (pendingGo > 0) {
+    // 有待回退的条目未冲销：直接复用栈顶现有哑条目，一进一出相抵
+    pendingGo--
+    state.entryCount++
+    return
+  }
+  state.entryCount++
+  window.history.pushState({ epxNav: state.entryCount }, '')
+}
+
+/**
+ * 应用内主动关闭 delta 个可关闭物后调用，对称回退等量浏览器历史。
+ * 系统返回（popstate）联动的关闭不需要也不允许再回退——由 handlingPop 拦截。
+ */
+export function consume (delta = 1) {
+  if (state.handlingPop) return
+  const n = Math.min(delta, state.entryCount)
+  if (n <= 0) return
+  state.entryCount -= n
+  pendingGo += n
+  scheduleFlush()
+}
+
+/**
+ * 弹窗/抽屉关闭时的历史冲销（幂等：只对压过历史且未冲销的弹窗生效）
+ */
+export function consumeForPopup (popupObj) {
+  if (!popupObj || !popupObj._pushedHistory) return
+  popupObj._pushedHistory = false
+  consume(1)
+}
+
+/**
+ * 吞掉下一次 popstate（自己发起 history 回退前调用）。
+ * 带超时：history.go 越过栈底或被 iframe 条目吃掉时 popstate 不会来，防止泄漏。
+ */
+export function suppressNextPop () {
+  state.suppressCount++
+  state.suppressDeadline = Date.now() + 1500
+}
+
+/**
+ * 是否处于应用根页面：没有打开的弹窗/抽屉，且所有可见 routerView 的页面栈都只剩 1 页。
+ * 供 $backPage 判断「返回」语义应为离开应用（回上个应用/大厅）而非销毁页面
+ */
+export function isAtRootPage () {
+  const opened = window.openedPopup
+  if (Array.isArray(opened) && opened.some(popup => popup && !popup.closed)) return false
+  for (const rv of routerViews) {
+    if (!rv.routes || rv.routes.length === 0) continue
+    if (!rv.$el || !isVisible(rv.$el)) continue
+    if (rv.routes.length > 1) return false
+  }
+  return true
+}
+
+/**
+ * 把控制权交还浏览器/宿主（原 Tabs 的 history.go(-1)）：
+ * 越过所有残留哑条目直接离开应用。
+ */
+export function leaveApp () {
+  const n = state.entryCount + pendingGo + 1
+  state.entryCount = 0
+  pendingGo = 0
+  suppressNextPop()
+  window.history.go(-n)
+}
+
+function scheduleFlush () {
+  if (flushScheduled) return
+  flushScheduled = true
+  Promise.resolve().then(() => {
+    flushScheduled = false
+    if (pendingGo <= 0) return
+    const n = pendingGo
+    pendingGo = 0
+    suppressNextPop()
+    window.history.go(-n)
+  })
+}
+
+function isVisible (el) {
+  return !!el && el.isConnected && el.offsetParent !== null
+}
+
+/**
+ * 找到当前应响应系统返回的页面组件：
+ * 可见且栈非空的 routerView 中取文档序最靠后的一个（嵌套内层在外层之后、
+ * 弹窗/抽屉挂在 body 尾部在主界面之后），其栈顶页面即当前用户看到的最顶层页。
+ */
+function findTopPage () {
+  let top = null
+  for (const rv of routerViews) {
+    if (!rv.routes || rv.routes.length === 0) continue
+    if (!rv.$el || !isVisible(rv.$el)) continue
+    if (!top) {
+      top = rv
+      continue
+    }
+    const pos = top.$el.compareDocumentPosition(rv.$el)
+    // FOLLOWING 含「在其后」与「被其包含」两种情况，都视为更顶层
+    if (pos & Node.DOCUMENT_POSITION_FOLLOWING) top = rv
+  }
+  if (!top) return null
+  const pageWrap = top.$refs && top.$refs.page
+  // Vue3 无 $children（原 Vue2 实现用 pageWrap.$children[0] 取 epx-page 唯一的渲染子节点）：
+  // epx-page（packages/components/src/page/Page.vue）内部动态渲染实际页面组件的
+  // `<component :is="componentName">` 标了 ref="component"，直接取同一个实例，语义等价。
+  return (pageWrap && pageWrap.$refs && pageWrap.$refs.component) || null
+}
+
+function onPopstate (event) {
+  if (state.suppressCount > 0) {
+    if (Date.now() <= state.suppressDeadline) {
+      state.suppressCount--
+      // leaveApp 的回退会越出应用上下文，同样需要整页重启目标路由
+      handleLanding()
+      return
+    }
+    state.suppressCount = 0
+  }
+  // 推迟到微任务：让 AiChatPage 等自管理 popstate 的组件先行处理并标记
+  Promise.resolve().then(() => {
+    if (event && event._epxNavHandled) return
+    if (state.entryCount <= 0) {
+      // 条目耗尽后的真实回退：离开本应用（返回大厅/上一个应用）或撞上退出守卫
+      handleLanding()
+      return
+    }
+    state.entryCount--
+    const page = findTopPage()
+    if (!page || typeof page.backPage !== 'function') return
+    state.handlingPop = true
+    try {
+      page.backPage({ fromPopstate: true })
+    } finally {
+      state.handlingPop = false
+    }
+  })
+}
+
+export function install () {
+  if (window.__epxNavHistoryInstalled) return
+  window.__epxNavHistoryInstalled = true
+  // 调试句柄：控制台可查 entryCount/suppressCount 排查返回问题
+  window.__epxNavHistory = state
+  bootIdentity = routeIdentity()
+  // 冷启动（非跨应用跳转而来）的移动端：压守卫条目防止返回键直接退出网页
+  let cameFromApp = false
+  try {
+    cameFromApp = !!sessionStorage.getItem(PREV_CONTEXT_KEY)
+  } catch (e) {
+    // 读不到时按冷启动处理
+  }
+  if (!cameFromApp && window.innerWidth <= 992) {
+    state.guardMode = true
+    pushGuard()
+  }
+  // 整页刷新恢复：当前条目若带 epxNav 深度标记，说明其下方还有等量哑条目
+  const s = window.history.state
+  if (s && typeof s.epxNav === 'number' && s.epxNav > 0) {
+    state.entryCount = s.epxNav
+  }
+  window.addEventListener('popstate', onPopstate)
+}

package/src/page.js

@@ -0,0 +1,129 @@
+class Page {
+  constructor (props) {
+    const { label, linkEntitys, relatedEntitys, sysId, data } = props
+    const { CONTENT, FLAG, ID, META_ID, META_CODE, PAGE_ID, PAGE_CODE, PAGE_PATH, VISUAL_CONFIG_PATH, TITLE, HELP, SYSTEM, SYSTEM_CODE, RIGHT_CONTROL_MODE } = data
+    this.label = label
+    this.title = TITLE
+    this.linkEntitys = linkEntitys
+    this.relatedEntitys = relatedEntitys
+    this.sysId = sysId
+    // eslint-disable-next-line no-eval
+    this.config = eval('(' + (CONTENT || '{}') + ')')
+    this.flag = FLAG
+    this.pageId = ID
+    this.templateId = PAGE_ID
+    this.metaId = META_ID
+    this.metaCode = META_CODE
+    this.pagePath = PAGE_PATH
+    this.pageCode = PAGE_CODE
+    this.system = SYSTEM
+    this.systemCode = SYSTEM_CODE
+    this.help = HELP
+    this.rightControlMode = RIGHT_CONTROL_MODE
+    this.visualConfigPath = VISUAL_CONFIG_PATH
+    return this
+  }
+
+  getPageId () {
+    return this.pageId
+  }
+
+  getLabel () {
+    return this.label
+  }
+
+  getMetaId () {
+    return this.metaId
+  }
+
+  getFlag () {
+    return this.flag
+  }
+
+  getPagePath () {
+    return this.pagePath
+  }
+
+  getConfig () {
+    return this.config
+  }
+
+  /**
+ * 主键字段
+ * @return {}
+ */
+  getKey () {
+  // var me=this;
+    return this.keyNames[0]
+  }
+
+  /**
+ * 获取所有属性
+ * @return {}
+ */
+  getAttris () {
+    const data = []
+    const m = this
+    const attris = m.attributes
+    attris.forEach((name, index) => {
+      const a = attris[name]
+      data[index] = { ID: a.name, NAME: a.label }
+    })
+    return data
+  }
+
+  /**
+ * ID对应LAVEL
+ */
+  getIdLabelAttris () {
+    const data = []
+    const m = this
+    const attris = m.attributes
+    attris.forEach((name, index) => {
+      const a = attris[name]
+      data[index] = { ID: a.id, NAME: a.label }
+    })
+    return data
+  }
+
+  /**
+ * NAME对应LAVEL
+ */
+  getNameLabelAttris () {
+    const data = []
+    const m = this
+    const attris = m.attributes
+    attris.forEach((name, index) => {
+      const a = attris[name]
+      data[index] = { ID: a.name, NAME: a.label }
+    })
+    return data
+  }
+
+  /**
+ * 根据字段ID获取字段Name
+ * @param {} attriId
+ * @return {}
+ */
+  getAttriNameById (attriId) {
+    const me = this
+    if (me.attriIds) {
+      return me.attriIds[attriId]
+    }
+    return null
+  }
+
+  /**
+   * 根据字段key获取label
+   */
+  getLabelByField (field) {
+    const m = this
+    const attribute = m.getAttributes()[field]
+    if (attribute) {
+      return attribute.label
+    }
+    return null
+  }
+}
+
+export default Page

package/src/pdf.viewer.js

@@ -0,0 +1,2 @@
+// 兼容旧路径；新代码从 @epxing/core 导入。
+export { default } from '@epxing/core/src/runtime-utils/pdf.viewer'

package/src/placeholder.js

@@ -0,0 +1,107 @@
+// 统一的 `#{path}` 占位符解析。
+//
+// 为什么要有这个文件：同一个「按 key 从当前上下文取值」的操作，全仓被复制粘贴出
+// **8 种不同语义**（105 行 / 51 个文件），归一化后是这样：
+//
+//     30 次  $query → $tab                        ← 根本不查组件自身
+//     16 次  $query → $tab → this                 ← 组件自身排最后
+//     12 次  this → $query                        ← 少了 $tab
+//      8 次  this → $query → $tab → $route.query  ← 多一个来源
+//      6 次  this → $query → $tab
+//      3 次  this
+//      …
+//
+// 也就是说同一个 `#{userId}` 写在不同组件里，解析结果不一样。本文件不试图替所有调用点
+// 决定「该查哪些来源」——那是各组件的语境，强行统一等于拿 51 个文件的行为去赌。
+// 它统一的是**取值语义**，把三个各处都错的地方一次修掉：
+//
+//   1. 命中判据是「这个来源**有没有**这个路径」，不是「取出来真不真」。
+//      存量用 `eval(a.k) || eval(b.k) || ''` 串联，于是合法的 `0` / `''` / `false`
+//      会静默穿透到下一个来源去取同名值——这是个真 bug，不是风格问题。
+//   2. **全局**替换。存量写的是 `.replace(/#\{…\}/, fn)`，没有 `g`，
+//      一个字符串里有多个占位符时只有第一个被替换。
+//   3. 不用 eval。存量靠 `eval(\`that.${key}\`)` 做属性取值；这里就是纯属性路径遍历。
+//      （顺带说明：存量那个 eval 的注入风险其实很低——正则字符集里没有括号，
+//      写不进函数调用。所以这次改动的理由是**语义一致性**，不是安全。）
+//
+// 迁移策略：新代码一律用这里；存量按「哪天碰到哪个文件就顺手迁哪个」推进，
+// 不做一次性全量替换。
+
+// 与存量 `#{}` 正则的字符集保持一致（含 `|`：`busi|NAME` 这类字段名里带竖线），
+// 但补上 g —— 见上面第 2 点。
+export const PLACEHOLDER_RE = /#\{([\w\-.|$#]+)\}/g
+
+/**
+ * 按属性路径在**一个**来源里取值。
+ * 只按 `.` 和 `[...]` 分段；`|` 当普通字符（字段名可能长这样：`busi|NAME`）。
+ * @returns {{ found: boolean, value: any }} found 区分「没有这个路径」与「值恰好是 undefined」
+ */
+export function lookup (path, source) {
+  if (source == null || typeof path !== 'string' || !path) return { found: false, value: undefined }
+  const keys = []
+  let cur = ''
+  let inBracket = false
+  for (const ch of path) {
+    if (ch === '[') {
+      inBracket = true
+      if (cur) { keys.push(cur); cur = '' }
+    } else if (ch === ']') {
+      inBracket = false
+      if (cur) { keys.push(cur.replace(/^['"](.*)['"]$/, '$1')); cur = '' }
+    } else if (ch === '.' && !inBracket) {
+      if (cur) { keys.push(cur); cur = '' }
+    } else {
+      cur += ch
+    }
+  }
+  if (cur) keys.push(cur)
+  if (!keys.length) return { found: false, value: undefined }
+
+  let obj = source
+  for (let i = 0; i < keys.length; i++) {
+    if (obj == null) return { found: false, value: undefined }
+    const k = keys[i]
+    // 用 in / hasOwnProperty 判存在，而不是看取出来的值真不真
+    const has = typeof obj === 'object' ? (k in obj) : Object.prototype.hasOwnProperty.call(Object(obj), k)
+    if (!has) return { found: false, value: undefined }
+    obj = obj[k]
+  }
+  return { found: true, value: obj }
+}
+
+/**
+ * 按给定顺序在多个来源里找第一个**拥有**该路径的。
+ * @param {string} path
+ * @param {Array<object>} sources 有序来源，如 [this, this.$query, this.$tab]
+ * @returns {{ found: boolean, value: any, index: number }} index 为命中的来源下标，未命中为 -1
+ */
+export function resolveKey (path, sources = []) {
+  for (let i = 0; i < sources.length; i++) {
+    const r = lookup(path, sources[i])
+    if (r.found) return { found: true, value: r.value, index: i }
+  }
+  return { found: false, value: undefined, index: -1 }
+}
+
+/**
+ * 替换字符串里的全部 `#{path}`。
+ * @param {string} text
+ * @param {Array<object>} sources 有序来源
+ * @param {object} [options]
+ * @param {'empty'|'keep'} [options.onMissing='empty']
+ *        'empty' —— 取不到就换成空串（与存量 `… || ''` 的收尾一致，是默认）
+ *        'keep'  —— 原样保留 `#{path}`。⚠️ 保留下来的是**非空字符串**，
+ *                   也就是真值，`a || b` 形式的兜底会失效——选它之前先确认调用方判得了。
+ * @returns {string}
+ */
+export function resolvePlaceholders (text, sources = [], options = {}) {
+  if (typeof text !== 'string' || text.indexOf('#{') === -1) return text
+  const onMissing = options.onMissing || 'empty'
+  return text.replace(PLACEHOLDER_RE, (match, path) => {
+    const r = resolveKey(path, sources)
+    if (!r.found) return onMissing === 'keep' ? match : ''
+    return r.value == null ? '' : String(r.value)
+  })
+}
+
+export default { PLACEHOLDER_RE, lookup, resolveKey, resolvePlaceholders }

package/src/public.js

@@ -0,0 +1,11 @@
+export { default as Config } from './Config'
+export { default as Page } from './page'
+export { default as placeholder } from './placeholder'
+export * from './placeholder'
+export * from './date-helper'
+export * from './dom-helper'
+export { default as storage, getXsrfToken, setXsrfToken } from './storage'
+export { default as cookie } from './storage'
+export { default as moment, default as dateTime, createMoment } from './moment-compat'
+export { default as lodash } from './collection'
+export * from './collection'

package/src/security.js

@@ -0,0 +1,29 @@
+const DANGEROUS_PATTERNS = [
+  /\beval\s*\(/,
+  /(?:^|[^$])\balert\s*\(/,
+  /(?:^|[^$])\bconfirm\s*\(/,
+  /(?:^|[^$])\bprompt\s*\(/,
+  /\bdocument\s*\.\s*write\s*\(/,
+  /\bdocument\s*\.\s*writeln\s*\(/,
+  /\blocation\s*\.\s*(href|replace|assign)\s*[=(]/,
+  /\bsetTimeout\s*\(\s*['"`]/,
+  /\bsetInterval\s*\(\s*['"`]/,
+  /\bnew\s+Function\s*\(/,
+  /\bimportScripts\s*\(/,
+  /\bfetch\s*\(/,
+  /\bXMLHttpRequest\b/
+]
+
+/**
+ * 检查函数是否包含高危调用
+ * @param {Function} fn
+ * @returns {boolean} true 表示安全，false 表示包含高危调用
+ */
+export function isSafeFn (fn) {
+  const hit = DANGEROUS_PATTERNS.find(pattern => pattern.test(fn.toString()))
+  if (hit) {
+    console.warn('[security] 函数包含高危调用，已阻止执行。', hit)
+    return false
+  }
+  return true
+}

package/src/storage.js

@@ -0,0 +1,135 @@
+/**
+ * Web Storage 兼容层：提供与 js-cookie 同形的 get / set / remove API，
+ * 但底层只读写 sessionStorage / localStorage，完全不接触浏览器 Cookie。
+ *
+ * 背景：安全扫描要求站点不使用 Cookie。前端历史上只用 cookie 读过后端下发的
+ * xsrf_token；现在 `$cookie` / `Frame.cookie` 都指向本模块，老代码
+ * `this.$cookie.get(...)` 不用改，只是再也读写不到浏览器 Cookie。
+ *
+ * 语义约定：
+ * - get(key)：先查 sessionStorage，再查 localStorage；已过期的值当不存在处理（顺手清掉）
+ * - set(key, value, options)：默认写 localStorage；options.session = true 写 sessionStorage；
+ *   options.expires 支持「天数」或 Date（对齐 js-cookie），过期时间另存在 `${key}.expires`；
+ *   同名键只保留一份（写入一个存储区时清掉另一个存储区的同名键）
+ * - remove(key)：两个存储区连同过期标记一起清掉
+ * 所有读写都包在 try/catch 里：隐私模式 / 禁用存储时退化为 no-op，不抛错。
+ */
+const EXPIRES_SUFFIX = '.expires'
+
+const getArea = (session) => {
+  try {
+    return session ? window.sessionStorage : window.localStorage
+  } catch (e) {
+    return null
+  }
+}
+
+// 查找顺序：sessionStorage 优先于 localStorage
+const getAreas = () => [getArea(true), getArea(false)].filter(Boolean)
+
+const toExpiresAt = (expires) => {
+  if (expires === undefined || expires === null || expires === '') return null
+  if (expires instanceof Date) return expires.getTime()
+  const days = Number(expires)
+  if (Number.isNaN(days)) return null
+  return Date.now() + days * 864e5
+}
+
+const toText = (value) => {
+  if (typeof value === 'string') return value
+  if (value === undefined || value === null) return ''
+  if (typeof value === 'object') return JSON.stringify(value)
+  return String(value)
+}
+
+const readFrom = (area, key) => {
+  try {
+    const value = area.getItem(key)
+    if (value === null) return undefined
+    const expiresAt = Number(area.getItem(key + EXPIRES_SUFFIX))
+    if (expiresAt && Date.now() > expiresAt) {
+      area.removeItem(key)
+      area.removeItem(key + EXPIRES_SUFFIX)
+      return undefined
+    }
+    return value
+  } catch (e) {
+    return undefined
+  }
+}
+
+const removeFrom = (area, key) => {
+  try {
+    area.removeItem(key)
+    area.removeItem(key + EXPIRES_SUFFIX)
+  } catch (e) {}
+}
+
+const storage = {
+  /**
+   * @param {string} key
+   * @returns {string | undefined} 不存在或已过期返回 undefined（与 js-cookie 一致）
+   */
+  get (key) {
+    if (key === undefined || key === null) return undefined
+    key = String(key)
+    const areas = getAreas()
+    for (let i = 0; i < areas.length; i++) {
+      const value = readFrom(areas[i], key)
+      if (value !== undefined) return value
+    }
+    return undefined
+  },
+  /**
+   * @param {string} key
+   * @param {*} value 非字符串会被转成字符串（对象走 JSON.stringify）
+   * @param {{ expires?: number | Date, session?: boolean }} [options]
+   * @returns {string | undefined} 实际写入的字符串
+   */
+  set (key, value, options) {
+    if (key === undefined || key === null) return undefined
+    key = String(key)
+    const { session = false, expires } = options || {}
+    const target = getArea(session)
+    if (!target) return undefined
+    const text = toText(value)
+    const expiresAt = toExpiresAt(expires)
+    try {
+      target.setItem(key, text)
+      if (expiresAt) target.setItem(key + EXPIRES_SUFFIX, String(expiresAt))
+      else target.removeItem(key + EXPIRES_SUFFIX)
+    } catch (e) {
+      return undefined
+    }
+    const other = getArea(!session)
+    if (other) removeFrom(other, key)
+    return text
+  },
+  /**
+   * @param {string} key
+   */
+  remove (key) {
+    if (key === undefined || key === null) return
+    key = String(key)
+    getAreas().forEach(area => removeFrom(area, key))
+  }
+}
+
+/**
+ * 防 CSRF 令牌：由后端通过响应头 `xsrf_token`（或 `X-XSRF-TOKEN`）下发，
+ * axios 响应拦截器写入 sessionStorage（随标签页关闭失效），请求拦截器再回填到
+ * `xsrf_token` 请求头 / 下载类 URL 的 `xsrf_token` 查询参数。
+ */
+export const XSRF_TOKEN_KEY = 'xsrf_token'
+
+/** @returns {string} 没有令牌时返回空串，方便直接拼接到 URL / 请求头 */
+export const getXsrfToken = () => storage.get(XSRF_TOKEN_KEY) || ''
+
+export const setXsrfToken = (token) => {
+  if (!token) return
+  storage.set(XSRF_TOKEN_KEY, token, { session: true })
+}
+
+export const clearXsrfToken = () => storage.remove(XSRF_TOKEN_KEY)
+
+export default storage