mirror of https://gitee.com/ulthon/ulthon_admin.git synced 2026-07-03 16:32:48 +08:00

Files

augushong 9669bc61a3 feat(tools): 添加 Ulthon Admin 前端静态构建工具

- 新增 `tools:ua:build` 命令，用于合并前端模块文件
- 添加构建配置文件 `ua.build.json` 定义源文件和输出
- 引入基础服务类 `ToolsUaServiceBase` 处理路径和配置读取
- 创建命令基类 `ToolsUaBuildBase` 实现文件合并逻辑
- 注册新命令到 UlthonAdminService 服务容器
- 提供完整的模块化前端代码结构（core、common、table、listen、api、utils）
- 添加详细的使用说明文档 README.md
- 包含示例 Scheme 文件展示功能

2026-01-30 22:24:44 +08:00

3.5 KiB

Raw Permalink Blame History

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(...)：统一消息

如何开发

新增功能的推荐方式

判断属于哪类能力：核心/公共/表格/监听/API/工具
在对应模块内追加 admin.xxx = ... 或 admin.xxx = { ... }
若新增模块，请更新 ua.build.json 中的 sources 顺序
执行构建命令生成最新 ulthon-admin.js

新增模块的边界

只负责“补全 ua 对象”，不引入不必要的全局变量
只引用 __uaCtx 中已注册的上下文
避免模块内重复初始化全局配置

构建命令

php think tools:ua:build

可通过命令参数指定配置文件路径（默认读取本目录的 ua.build.json）：

php think tools:ua:build --config public/static/plugs/ulthon-admin/ua.build.json

构建清单说明

ua.build.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 建议保持稳定，避免破坏老页面
合并构建可纳入发布流程，避免线上文件与源码不一致

3.5 KiB Raw Permalink Blame History Unescape Escape