Lesson 04 · Pinia

Pinia，以及那个叫 store 但不是 store 的目录

src/store/ 下有两个子目录。它们名字都叫 store， 但一个装运行状态，一个装表格字段定义 —— 分不清会一直别扭。

先复习

先说人话：Pinia 解决的是什么问题

上一课讲了：组件之间传数据靠 props 往下传、emit 往上传。 这在父子之间很好用。

问题是有些数据跟组件树的形状完全无关。 比如「当前登录用户是谁」「当前选的是哪台服务器」—— 顶栏要用，某个深埋在五层组件里的表单也要用。 靠 props 一层层传下去，中间那些完全不关心这个数据的组件也得跟着接一手再传一手。

Pinia 就是把这类数据从组件树里拿出来，放到一个所有组件都够得着的地方。 仅此而已。它不神秘，本质就是一个「带响应式的全局对象」。

一、一个 store 长什么样

项目里所有 store 都用同一套写法（选项式）。看 src/store/modules/counter.ts，是最短的一个：

import { defineStore } from 'pinia'
import { store } from '../index'

export const useCounter = defineStore('counter', {
  state: () => ({          // ① 数据
    isCoolingDown: false,
    timer: null
  }),
  getters: {},             // ② 派生数据（相当于 computed）
  actions: {               // ③ 改数据的方法
    setCoolingDown(status) {
      this.isCoolingDown = status    // ← 用 this
    },
    startCoolingPeriod() {
      this.setCoolingDown(true)      // ← action 之间可以互相调
      this.timer = setTimeout(() => {
        this.setCoolingDown(false)
      }, 30000)
    }
  }
})

组件里这么用：

const counter = useCounter()

counter.isCoolingDown          // 读，不用 .value
counter.setCoolingDown(true)   // 改，调 action

二、useXxxWithOut()：本项目最特别的一个约定

你会发现每个 store 文件末尾都跟着一个奇怪的双胞胎。 src/store/modules/GameEvn.ts:40：

export const useGameEvnWithOut = () => {
  return useGameEvn(store)      // ← 显式把 pinia 实例传进去
}

为什么需要它？ 正常的 useGameEvn() 靠 Vue 的「当前活动实例」找到 pinia。 这只在组件的 setup 期间成立。

而这个项目有大量 store 使用发生在组件之外 —— axios 拦截器、路由守卫、api 模块的顶层。那些地方没有「当前组件」， 直接调 useGameEvn() 会报错。 WithOut 版本把 pinia 实例显式传进去，绕开这个限制。

18 个 store 模块里都有这个 WithOut 变体。 记住这条规则，能省掉一个很难懂的运行时报错。

三、核心：store/ 下的两个目录不是一回事

3.1 modules/：19 个运行态 store

3.2 app.ts 里有个容易看错的地方

// src/store/modules/app.ts
state: () => ({
  token: 'token',           // ← 这不是 token 本身
  userInfo: 'userInfo',     // ← 这也不是用户信息
  initialize: 'initialize',
  …
})

这些字段存的是存储键名，不是值。 真正的 token 在 localStorage 里，appStore.getToken 给出的是「去 localStorage 里用哪个 key 找」。所以你会看到：

const token = getStorage(appStore.getToken)   // 用 store 里的键名去 storage 里取值

3.3 config/：16 份表字段定义

看 src/store/config/Box.ts 的开头，最能说明这是什么：

const DialogConfig: ConfigModel = {
  id: {
    type: 'Number',
    summary: 'id',
    desc: '物品的ID',
    meta: { readonly: true }
  },
  name: {
    type: 'String',
    summary: '名称',
    desc: '盒子的名称'
  },
  type: {
    type: 'Number',
    summary: '宝箱类型（0：普通，1：数量随机 ）',
    desc: '0：普通宝箱\n1：数量随机宝箱',
    editor: 'select',                        // ← 用哪个控件
    options: [
      { label: '普通', value: 0 },
      { label: '数量随机', value: 1 }
    ]
  },
  …
}

3.4 两个目录怎么接上：table.ts

src/store/modules/table.ts:9 这一行是关键：

const TableConfig: any = import.meta.glob('@/store/config/*.ts')

import.meta.glob 是 Vite 的功能： 按通配符把一批文件收集成一个 { 路径: () => import(路径) } 的对象。也就是说 config/ 下的文件 没有任何地方显式 import 它们，全靠这一行扫进来。

然后 init()（table.ts:103）逐个 await 加载，把每个文件的 default 导出转成 Map， 存进 this.config[文件名]。页面用 TableStore.getConfigByKey('Npc') （table.ts:196）取出来。

3.5 init() 有个 1500 毫秒的延迟

table.ts 的 init() 不是在应用启动时调的， 而是在登录成功之后延迟 1500 毫秒 （views/ReLogin/index.vue:195-198）：

setTimeout(async () => {
  await getServerIds()
  TableStore.init()
}, 1500)

四、看懂一条完整的状态流

把这一课和前三课串起来，一条真实的链路：

两条链在第 ⑥ 步汇合：一条是数据（modules）， 一条是描述（config）。这就是架构图 FIG.04 画的那两条泳道。

真机验证