@love-sqjm/magic 2026.4.15

package/doc/config-reference.md

@@ -0,0 +1,646 @@
+# build.toml 配置参考手册
+
+## 概述
+
+`build.toml` 是 Magic 项目的构建配置文件，采用 TOML 格式。它定义了项目的基本信息、构建选项和平台配置。
+
+## 完整配置示例
+
+```toml
+# 配置
+[config]
+name = "my-project"
+src = "app"
+main = "index"
+
+[build]
+out = "build"
+model = "debug"
+
+[build.platform]
+target = "web"
+
+[build.import]
+module = []
+
+[build.exclude]
+file = []
+dir = []
+
+[build.optimize]
+out-default-theme = true
+
+[build.optimize.min-code]
+js = false
+css = false
+html = false
+
+[build.platform.config]
+server = { port = 8088, host = "127.0.0.1" }
+```
+
+## 配置项详解
+
+### [config] - 项目配置
+
+| 字段 | 类型 | 必需 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `name` | string | 是 | - | 项目名称 |
+| `src` | string | 是 | - | 源码目录，相对于项目根目录 |
+| `main` | string | 是 | - | 入口文件名（不含扩展名） |
+
+**示例:**
+```toml
+[config]
+name = "nice-game-creator"
+src = "app"
+main = "index"
+```
+
+---
+
+### [build] - 构建配置
+
+| 字段 | 类型 | 必需 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `out` | string | 否 | "build" | 构建输出目录 |
+| `model` | string | 否 | "debug" | 构建模式: `debug` 或 `release` |
+
+**debug vs release 模式:**
+
+| 特性 | debug | release |
+|------|-------|---------|
+| 代码压缩 | 否 | 可配置 |
+| CSS 压缩 | 否 | 可配置 |
+| HTML 压缩 | 否 | 可配置 |
+| 多个文件输出 | 是（按模块） | 可合并 |
+| Source Map | 无 | 无 |
+
+**示例:**
+```toml
+[build]
+out = "dist"
+model = "release"
+```
+
+---
+
+### [build.platform] - 平台配置
+
+| 字段 | 类型 | 必需 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `target` | string | 是 | - | 目标平台: `web`, `node-webkit`, `module` |
+| `config` | object | 否 | {} | 平台特定配置 |
+
+**支持的平台:**
+
+| 平台 | 说明 |
+|------|------|
+| `web` | 浏览器环境 |
+| `node-webkit` | Node-Webkit 桌面应用 |
+| `module` | 可复用模块库 |
+
+**示例:**
+```toml
+[build.platform]
+target = "web"
+```
+
+---
+
+### [build.platform.config] - 平台特定配置
+
+#### Web 平台配置
+
+```toml
+[build.platform.config]
+server = { port = 8088, host = "127.0.0.1" }
+browser = true
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `server.port` | number | HTTP 服务器端口 |
+| `server.host` | string | 服务器主机地址 |
+| `browser` | boolean | 是否自动打开浏览器 |
+
+**完整 Web 配置示例:**
+```toml
+[build.platform]
+target = "web"
+
+[build.platform.config]
+browser = true
+server = { port = 3000, host = "0.0.0.0" }
+```
+
+#### Node-Webkit 平台配置
+
+```toml
+[build.platform]
+target = "node-webkit"
+
+[build.platform.config]
+app = "/path/to/nw.exe"
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `app` | string | NW.js 可执行文件路径 |
+
+---
+
+### [build.import] - 模块导入配置
+
+定义要导入的外部 Magic 模块。
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `module` | array | [] | 模块路径列表 |
+
+**示例:**
+```toml
+[build.import]
+module = [
+    "./magic-ui",
+    "./common-components"
+]
+```
+
+---
+
+### [build.exclude] - 排除项配置
+
+定义构建时排除的文件和目录。
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `file` | array | [] | 排除的文件列表 |
+| `dir` | array | [] | 排除的目录列表 |
+
+**示例:**
+```toml
+[build.exclude]
+file = ["app.xml", "private.txt"]
+dir = ["test", "docs", ".git"]
+```
+
+**默认排除项:**
+- `app.xml` - 应用配置文件（自动排除）
+- `magic/` - Magic 内部目录（自动排除）
+
+---
+
+### [build.optimize] - 优化配置
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `out-default-theme` | boolean | true | 是否输出默认主题 CSS 变量文件 |
+
+#### out-default-theme
+
+启用后，会生成 `default-theme-var.css` 文件，将组件中的 `default-theme` CSS 属性转换为 CSS 变量。
+
+**示例:**
+```toml
+[build.optimize]
+out-default-theme = false
+```
+
+---
+
+### [build.optimize.min-code] - 代码压缩配置
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `js` | boolean | false | 是否压缩 JavaScript |
+| `css` | boolean | false | 是否压缩 CSS |
+| `html` | boolean | false | 是否压缩 HTML |
+
+**注意:** 压缩只在 `model = "release"` 时生效。
+
+**示例:**
+```toml
+[build.optimize]
+out-default-theme = true
+
+[build.optimize.min-code]
+js = true
+css = true
+html = true
+```
+
+---
+
+## app.xml 配置参考
+
+`app.xml` 是应用配置文件，位于源码目录中。
+
+## 完整配置示例
+
+```xml
+<app lang="zh" icon="path/to/icon.png">
+    <title>My Application</title>
+    <init-script>
+        $INIT$
+    </init-script>
+    <import
+        dir="."
+    >
+        <group dir="magic-ui">
+            <css src="style.css"/>
+            <js src="runtime.js"/>
+        </group>
+        <js src="main.js"/>
+    </import>
+</app>
+```
+
+## 配置项详解
+
+### app 根元素属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `lang` | string | "zh" | 页面语言代码 |
+| `icon` | string | - | 网站图标路径 |
+
+**示例:**
+```xml
+<app lang="en" icon="./favicon.png">
+```
+
+---
+
+### title - 页面标题
+
+```xml
+<title>My Application</title>
+```
+
+设置浏览器标签页标题。
+
+---
+
+### init-script - 初始化脚本
+
+```xml
+<init-script>
+    $INIT$
+</init-script>
+```
+
+**说明:**
+- `$INIT$` 是占位符，会被替换为框架初始化代码
+- 可以包裹在自定义代码中
+
+**示例:**
+```xml
+<init-script>
+    console.log("Before init");
+    $INIT$
+    console.log("After init");
+</init-script>
+```
+
+---
+
+### import - 资源导入
+
+定义要加载的 CSS 和 JavaScript 资源。
+
+#### 基本用法
+
+```xml
+<import>
+    <js src="main.js"/>
+    <css src="style.css"/>
+</import>
+```
+
+#### dir 属性
+
+设置资源的基础目录:
+
+```xml
+<import dir="lib">
+    <js src="jquery.js"/>
+    <css src="bootstrap.css"/>
+</import>
+```
+
+#### group 分组
+
+使用 `<group>` 组织资源:
+
+```xml
+<import dir=".">
+    <group dir="css">
+        <css src="reset.css"/>
+        <css src="theme.css"/>
+    </group>
+    <group dir="js">
+        <js src="vendor.js"/>
+        <js src="app.js"/>
+    </group>
+</import>
+```
+
+#### load 属性
+
+控制资源加载时机:
+
+| 值 | 说明 |
+|----|------|
+| `begin` | 在头部加载（默认） |
+| `end` | 在尾部加载 |
+
+```xml
+<js src="analytics.js" load="end"/>
+```
+
+---
+
+### import 标签详解
+
+#### js - JavaScript 资源
+
+```xml
+<js src="path/to/file.js" load="begin"/>
+```
+
+| 属性 | 说明 |
+|------|------|
+| `src` | 文件路径 |
+| `load` | 加载时机: `begin` 或 `end` |
+
+#### css - CSS 资源
+
+```xml
+<css src="path/to/file.css" load="begin"/>
+```
+
+| 属性 | 说明 |
+|------|------|
+| `src` | 文件路径 |
+| `load` | 加载时机: `begin` 或 `end` |
+
+#### link - 外部链接
+
+```xml
+<link href="https://fonts.googleapis.com/css?family=Roboto"/>
+```
+
+---
+
+### file - 内联文件内容
+
+使用 `file` 标签可以内联文件内容:
+
+```xml
+<import>
+    <file path="./inline-template.html" load="begin"/>
+</import>
+```
+
+---
+
+### module-import - 模块导入
+
+使用 `<module-import>` 标签可以导入一个包含 `.module-import` 配置文件的模块目录。
+
+#### 基本用法
+
+```xml
+<import dir=".">
+    <module-import src="xxx-ui"/>
+</import>
+```
+
+#### 工作原理
+
+1. `module-import` 根据 `src` 属性在指定目录中查找 `.module-import` 文件
+2. `.module-import` 文件定义了模块的 js、css、link、file 资源
+3. 所有资源路径相对于模块目录
+
+#### .module-import 文件格式
+
+```text
+js
+-[load:front]critical.js
+-runtime.js
+css
+-[load:end]mdi/materialdesignicons.min.css
+-atom.css
+-style.css
+link
+-https://fonts.googleapis.com/css?family=Roboto
+file
+-inline-template.html
+```
+
+格式说明:
+- 以 `js`、`css`、`link`、`file` 开头表示分类
+- 以 `-` 开头的行表示具体文件路径
+- 支持 `[load:xxx]` 格式指定加载时机，可选值: `begin`、`end`、`front`
+- `#` 开头或空行会被忽略
+
+#### 完整示例
+
+app.xml 配置:
+```xml
+<app lang="zh">
+    <title>Nice Game Creator</title>
+    <init-script>
+        $INIT$
+    </init-script>
+    <import dir=".">
+        <module-import src="xxx-ui"/>
+        <group dir="magic-ui">
+            <css src="style.css"/>
+            <js src="runtime.js"/>
+        </group>
+        <group dir="script">
+            <js src="platform.js"/>
+        </group>
+    </import>
+</app>
+```
+
+模块目录结构:
+```
+xxx-ui/
+├── .module-import    # 模块配置文件
+├── runtime.js        # 资源文件
+└── styles/
+    └── theme.css     # 子目录资源
+```
+
+对应的 `.module-import 文件:
+```
+js
+-runtime.js
+css
+-styles/theme.css
+```
+
+#### 资源加载顺序
+
+HTML 中 head 区域的资源加载位置顺序:
+
+```
+[front] → [runtime.css] → [runtime.js] → [begin] → [/head]
+```
+
+body 区域的资源加载位置:
+
+```
+[begin] → [/body] → [end]
+```
+
+| 类型 | 默认 load | 说明 |
+|------|-----------|------|
+| js | `begin` | 在 head 区域加载 |
+| css | `begin` | 在 head 区域加载 |
+| link | `begin` | 在 head 区域加载 |
+| file | `begin` | 内联内容，随 js/css 一起加载 |
+
+**load 可选值:**
+
+| 值 | 加载位置 | 说明 |
+|----|----------|------|
+| `front` | head 最开始 | 在 runtime.css 之前，用于关键 CSS/JS |
+| `begin` | head 中间 | 在 runtime.js 之后 |
+| `end` | body 末尾 | 在 `</body>` 之前 |
+
+---
+
+## 实战配置模板
+
+### Web 开发配置
+
+```toml
+[config]
+name = "my-web-app"
+src = "app"
+main = "index"
+
+[build]
+out = "build"
+model = "debug"
+
+[build.platform]
+target = "web"
+
+[build.platform.config]
+browser = true
+server = { port = 8088, host = "127.0.0.1" }
+
+[build.exclude]
+file = []
+dir = []
+
+[build.optimize]
+out-default-theme = false
+
+[build.optimize.min-code]
+js = false
+css = false
+html = false
+```
+
+### Web 生产配置
+
+```toml
+[config]
+name = "my-web-app"
+src = "app"
+main = "index"
+
+[build]
+out = "dist"
+model = "release"
+
+[build.platform]
+target = "web"
+
+[build.platform.config]
+server = { port = 80, host = "0.0.0.0" }
+
+[build.import]
+module = []
+
+[build.exclude]
+file = []
+dir = []
+
+[build.optimize]
+out-default-theme = true
+
+[build.optimize.min-code]
+js = true
+css = true
+html = true
+```
+
+### Node-Webkit 桌面应用配置
+
+```toml
+[config]
+name = "my-desktop-app"
+src = "app"
+main = "index"
+
+[build]
+out = "build"
+model = "release"
+
+[build.platform]
+target = "node-webkit"
+
+[build.platform.config]
+app = "C:/nwjs/nw.exe"
+
+[build.exclude]
+file = []
+dir = []
+
+[build.optimize]
+out-default-theme = false
+
+[build.optimize.min-code]
+js = true
+css = true
+html = true
+```
+
+### 模块库配置
+
+```toml
+[config]
+name = "my-magic-module"
+src = "app"
+version = "1.0.0"
+description = "A reusable Magic module"
+author = "Developer"
+license = "MIT"
+
+[build]
+out = "dist"
+model = "release"
+
+[build.platform]
+target = "module"
+
+[build.exclude]
+file = []
+dir = []
+
+[build.optimize]
+out-default-theme = false
+
+[build.optimize.min-code]
+js = true
+css = true
+html = true
+```