From 9ed486c343dee6d26e900ddbf73b9d101c4f9136 Mon Sep 17 00:00:00 2001 From: root Date: Fri, 24 Jul 2026 09:15:23 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=B2=BE=E7=AE=80=20README=EF=BC=88?= =?UTF-8?q?=E7=BB=93=E6=9E=84/=E4=BE=9D=E8=B5=96/=E4=BD=BF=E7=94=A8?= =?UTF-8?q?=EF=BC=89=EF=BC=8C=E7=BB=86=E8=8A=82=E7=A7=BB=E8=87=B3=20docs/i?= =?UTF-8?q?ntegration.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 74 ++++++++++++++++++--------------------------- docs/integration.md | 24 +++++++++++++++ 2 files changed, 53 insertions(+), 45 deletions(-) create mode 100644 docs/integration.md diff --git a/README.md b/README.md index d1b3ced..d259999 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,6 @@ # z449 - 移动游戏项目展示页 -跨学期 Unity 移动游戏毕设（448/449）的展示页：项目概览、团队、玩家排行榜、版本迭代记录、ML-Agents 实验。 - -纯前端 Vue 3 应用，独立可渲染与维护，亦可作为 [mainPage](https://git.zikai.wang/zikai/zMainPage) 的子模块（git submodule）构建期集成展示。 - -## 功能 - -- Hero 区：项目元数据（技术栈 / 时间 / 课程） -- 概览 + 截图轮播（自动播放） -- 团队成员卡片 -- 玩家分数排行榜（复用 449 现有 PHP 接口 `/449/449rest.php`） -- 版本演进时间线（2D -> 3D 形态转变，多线并行） -- ML-Agents 强化学习演示视频 -- 中英双语（中文默认，英文懒加载） +跨学期 Unity 移动游戏毕设（448/449）的展示页：项目概览、团队、玩家排行榜、版本迭代记录、ML-Agents 实验。纯前端 Vue 3 应用，独立可渲染与维护，亦可作为 [mainPage](https://git.zikai.wang/zikai/zMainPage) 的子模块集成展示。 ## 项目结构 @@ -22,51 +10,43 @@ z449/ ├── package.json ├── vite.config.js 含 /448 /449 开发代理 ├── .npmrc npmmirror 镜像加速 -├── src/ -│ ├── main.js 独立 app 挂载（i18n + 全局样式） -│ ├── App.vue ★ 便携式根组件：接 :locale prop，嵌入与独立两用 -│ ├── config.js 静态配置（资源路径 / 排行榜接口 / 子标签） -│ ├── i18n/ 独立 vue-i18n 实例 + 中英 locale（mobileGame.* 文案单一来源） -│ ├── components/ Hero / 轮播 / 子标签 / 排行榜 / 时间线 / 实验 -│ │ └── ui/ PageShell / Tag（自洽 UI 基元） -│ ├── data/ 团队成员 / 版本演进数据 -│ └── styles/ variables.css（令牌）+ base.css（重置，仅独立 app 加载） -└── docs/ 设计文档 +├── README.md +├── docs/ 设计文档 +└── src/ + ├── main.js 独立 app 挂载（i18n + 全局样式） + ├── App.vue 便携式根组件（嵌入与独立两用） + ├── config.js 静态配置（资源路径 / 排行榜接口 / 子标签） + ├── i18n/ 独立 vue-i18n 实例 + 中英 locale + ├── composables/ + │ └── useLocale.js 语言辅助（直读自身 i18n 实例） + ├── components/ Hero / 轮播 / 子标签 / 排行榜 / 时间线 / 实验 + │ └── ui/ PageShell / Tag + ├── data/ 团队成员 / 版本演进数据 + └── styles/ variables.css（令牌）+ base.css（重置，仅独立 app 加载） ``` -## 嵌入 mainPage（i18n 桥接） +## 外部依赖 -`App.vue` 是便携式组件： +| 项 | 说明 | +|----|------| +| Node.js | ≥ 18 | +| `/448` 静态资源 | 游戏截图、WebGL 试玩、APK 下载（站点根提供） | +| `/449` 静态资源 + PHP | 玩家分数排行榜接口 `/449/449rest.php`（站点根提供） | -- **嵌入时**：mainPage 侧包装器 `import` 本项目 `src/App.vue`，把父项目当前语言经 `:locale` prop 传入。`App.vue` 内 `watch` 该 prop，同步到本项目独立的 `vue-i18n` 实例 `locale`，从而跟随父项目语言开关响应式切换。文案来自本项目自有 locale 文件，不共享父项目的 messages。 -- **独立运行时**：不接收 prop，默认中文；可自管语言切换。 +> 开发时 `vite.config.js` 已把 `/448` `/449` 代理到 `localhost:8080`；生产由 Apache 静态 / PHP 服务提供。 -样式隔离：子组件均为 scoped；全局重置（`variables.css` / `base.css`）仅在独立 app 的 `main.js` 加载，嵌入时不加载，复用宿主 `:root` 令牌级联。 - -## Ubuntu 从零安装 +## 如何使用 ```bash -# 1. 安装 Node.js 18+ -curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - -sudo apt-get install -y nodejs - -# 2. 克隆并安装 +# 克隆并安装 git clone https://git.zikai.wang/zikai/z449.git cd z449 npm install # 已配 npmmirror 镜像加速 -# 3. 构建生产版本 -npm run build # 产物输出到 dist/ +npm run dev # 开发服务器 http://localhost:5174 +npm run build # 构建到 dist/ ``` -开发模式： - -```bash -npm run dev # http://localhost:5174 -``` - -> 排行榜与游戏资源依赖站点根的 `/448` `/449` 静态资源与 `/449/449rest.php` 接口。开发时 `vite.config.js` 已配代理到 `localhost:8080`；生产由 Apache 静态 / PHP 服务提供。 - ## 技术栈 | 项 | 选择 | @@ -75,3 +55,7 @@ npm run dev # http://localhost:5174 | 构建 | Vite 5 | | 国际化 | vue-i18n 9（中文同步，英文懒加载） | | 包源 | npmmirror.com（中国镜像加速） | + +## 了解更多 + +- [嵌入 mainPage（i18n prop 桥接 / 样式隔离）](./docs/integration.md) diff --git a/docs/integration.md b/docs/integration.md new file mode 100644 index 0000000..c7bae53 --- /dev/null +++ b/docs/integration.md @@ -0,0 +1,24 @@ +# 嵌入 mainPage + +z449 可作为 [mainPage](https://git.zikai.wang/zikai/zMainPage) 的子模块（git submodule）经构建期组件集成展示，位于 mainPage 的 `third_party/z449`。 + +## 便携式 App.vue + +`src/App.vue` 是嵌入与独立两用的根组件： + +- **嵌入时**：mainPage 侧包装器 `import` 本项目 `src/App.vue`，把父项目当前语言经 `:locale` prop 传入。`App.vue` 内 `watch` 该 prop，同步到本项目独立的 `vue-i18n` 实例 `locale`，从而跟随父项目语言开关响应式切换。文案来自本项目自有 locale 文件，不共享父项目的 messages。 +- **独立运行时**：不接收 prop，默认中文。 + +## i18n 桥接关键点 + +组件内用 `useLocale` composable **直接读自身模块级 i18n 实例**（`i18n.global`），而非 `useI18n({ useScope: 'global' })`。 + +原因：`useI18n({ useScope: 'global' })` 解析的是「当前运行 app 已安装的全局 i18n」。嵌入 mainPage 时那是父项目的实例（不含本项目 `mobileGame.*` 文案），会导致文案回退成 i18n key（显示 ID 而非文字）。改为直接引用本项目实例的 `.global`，无论是否 `app.use()` 都拿到本项目的 `t`。 + +## 样式隔离 + +子组件均为 scoped；全局重置（`variables.css` / `base.css`）仅在独立 app 的 `main.js` 加载，嵌入时不加载，复用宿主 `:root` 令牌级联。 + +## 集成 / 升级 / 移除 + +详见 mainPage 仓库的 [`docs/submodule-z449.md`](https://git.zikai.wang/zikai/zMainPage/src/branch/main/docs/submodule-z449.md)（克隆含子模块、升级 gitlink、移除页签等流程）。