mirror of
https://gitee.com/ulthon/ulthon_admin.git
synced 2026-07-04 09:02:49 +08:00
9669bc61a3
- 新增 `tools:ua:build` 命令，用于合并前端模块文件 - 添加构建配置文件 `ua.build.json` 定义源文件和输出 - 引入基础服务类 `ToolsUaServiceBase` 处理路径和配置读取 - 创建命令基类 `ToolsUaBuildBase` 实现文件合并逻辑 - 注册新命令到 UlthonAdminService 服务容器 - 提供完整的模块化前端代码结构（core、common、table、listen、api、utils） - 添加详细的使用说明文档 README.md - 包含示例 Scheme 文件展示功能
102 lines
3.5 KiB
Markdown
102 lines
3.5 KiB
Markdown
# Ulthon Admin 前端静态构建说明
|
||
|
||
本目录使用纯 PHP 的 ThinkPHP 命令进行静态合并构建，不依赖前端构建工具。拆分后的模块文件都会“完善 ua 对象”，最终合并为单文件供页面直接引用。
|
||
|
||
## 设计结构
|
||
|
||
**目录结构**
|
||
- `src/`：拆分后的源码模块
|
||
- `ua.build.json`：构建清单（sources + output）
|
||
- `ulthon-admin.js`：合并输出文件（运行时引用）
|
||
|
||
**模块划分**
|
||
- `ulthon-admin.01-core.js`：基础上下文与核心能力（ctx、init、config、url、headers、checkAuth、parame）
|
||
- `ulthon-admin.02-common.js`：请求/消息/公共方法（request、common、msg）
|
||
- `ulthon-admin.03-table.js`：表格能力（admin.table）
|
||
- `ulthon-admin.04-listen.js`：统一监听入口（admin.listen、open、checkMobile）
|
||
- `ulthon-admin.05-api.js`：组件 API 能力（admin.api）
|
||
- `ulthon-admin.06-utils.js`：工具能力（查询、缓存、页面设置、扩展名识别等）
|
||
|
||
**设计要点**
|
||
- 每个模块都只做“补全 ua 对象”的工作，避免模块间互相覆盖。
|
||
- 使用 `window.__uaCtx` 做跨模块上下文共享，保证拆分后仍能共享变量。
|
||
- 构建顺序严格依赖 `ua.build.json`，以顺序决定覆盖与依赖关系。
|
||
|
||
## 如何使用
|
||
|
||
**前端引用**
|
||
- 页面只需要引用合并后的 `ulthon-admin.js`，无需加载 `src/` 内的拆分文件。
|
||
- 全局入口保持不变：`window.ua` / `window.ulAdmin`。
|
||
|
||
**常见调用**
|
||
- `ua.listen()`：初始化页面常规行为
|
||
- `ua.table.render(...)`：渲染表格
|
||
- `ua.request.post(...)`：通用请求
|
||
- `ua.msg.success(...)`：统一消息
|
||
|
||
## 如何开发
|
||
|
||
**新增功能的推荐方式**
|
||
1. 判断属于哪类能力：核心/公共/表格/监听/API/工具
|
||
2. 在对应模块内追加 `admin.xxx = ...` 或 `admin.xxx = { ... }`
|
||
3. 若新增模块，请更新 `ua.build.json` 中的 `sources` 顺序
|
||
4. 执行构建命令生成最新 `ulthon-admin.js`
|
||
|
||
**新增模块的边界**
|
||
- 只负责“补全 ua 对象”，不引入不必要的全局变量
|
||
- 只引用 `__uaCtx` 中已注册的上下文
|
||
- 避免模块内重复初始化全局配置
|
||
|
||
**构建命令**
|
||
```bash
|
||
php think tools:ua:build
|
||
```
|
||
|
||
可通过命令参数指定配置文件路径（默认读取本目录的 `ua.build.json`）：
|
||
```bash
|
||
php think tools:ua:build --config public/static/plugs/ulthon-admin/ua.build.json
|
||
```
|
||
|
||
## 构建清单说明
|
||
|
||
`ua.build.json` 使用相对路径时，基于配置文件所在目录解析：
|
||
|
||
```json
|
||
{
|
||
"output": "ulthon-admin.js",
|
||
"sources": [
|
||
"src/ulthon-admin.01-core.js",
|
||
"src/ulthon-admin.02-common.js",
|
||
"src/ulthon-admin.03-table.js",
|
||
"src/ulthon-admin.04-listen.js",
|
||
"src/ulthon-admin.05-api.js",
|
||
"src/ulthon-admin.06-utils.js"
|
||
]
|
||
}
|
||
```
|
||
|
||
## 兼容性与约定
|
||
|
||
- 兼容原有 `ua` 对外 API，保持使用方式不变
|
||
- 不依赖前端打包工具
|
||
- 模块拆分后只影响维护方式，不改变运行结果
|
||
|
||
## 常见问题
|
||
|
||
**1. 构建后功能异常**
|
||
- 检查 `ua.build.json` 的顺序是否符合依赖
|
||
- 检查新增模块是否遗漏 `window.ulAdmin = window.ua = admin;`
|
||
|
||
**2. 新方法不可用**
|
||
- 确认方法定义在 `admin` 上
|
||
- 确认构建文件已更新（重新执行构建）
|
||
|
||
**3. 引用未更新**
|
||
- 页面只引用 `ulthon-admin.js`，不要引用 `src/` 文件
|
||
|
||
## 进一步建议
|
||
|
||
- 若模块继续增大，建议细分 `admin.api` 为 upload/editor/form 等更小模块
|
||
- 对外 API 建议保持稳定，避免破坏老页面
|
||
- 合并构建可纳入发布流程，避免线上文件与源码不一致
|