@love-sqjm/magic 2026.4.15

package/doc/data-model.md

@@ -0,0 +1,622 @@
+# Magic 数据模型文档
+
+## 概述
+
+本文档描述 Magic 框架的核心数据模型和内部状态结构。
+
+---
+
+## 1. 编译器数据模型
+
+### 1.1 全局项目状态 (project)
+
+位置: `script/module/compiler/global.js`
+
+```typescript
+const project = {
+    // 构建配置
+    build_config: {
+        config: {
+            name: string,           // 项目名称
+            src: string,            // 源码目录
+            main: string            // 入口文件
+        },
+        build: {
+            out: string,            // 输出目录
+            model: "debug"|"release", // 构建模式
+            platform: {
+                target: string,     // 目标平台
+                config: object       // 平台配置
+            },
+            exclude: {
+                dir: string[],       // 排除目录
+                file: string[]       // 排除文件
+            },
+            optimize: {
+                "min-code": {
+                    js: boolean,
+                    css: boolean,
+                    html: boolean
+                },
+                "out-default-theme": boolean
+            }
+        }
+    },
+
+    // 应用配置
+    app_config: {
+        title: string,              // 页面标题
+        lang: string,              // 语言
+        icon: string | false,       // 图标
+        initScript: string | null, // 初始化脚本
+        import: importItem[]        // 导入列表
+    },
+
+    // 源文件映射
+    source_file: {
+        [ext: string]: source[],   // 按扩展名分组
+        "*it": () => source[]      // 迭代所有文件
+    },
+
+    // DOM 索引
+    index_dom: IndexDom,
+
+    // 目录路径
+    outDir: string,                // 输出目录
+    outDirMagic: string,           // magic 目录
+    srcDir: string                 // 源码目录
+};
+```
+
+### 1.2 source 类
+
+```typescript
+class source {
+    ext: string;                  // 文件扩展名
+
+    // 获取构建输出路径
+    build(): string;
+
+    // 获取相对路径
+    relative(): string;
+
+    // 获取绝对路径
+    absolute(): string;
+}
+```
+
+### 1.3 mData 类
+
+`.m` 文件编译时的中间数据结构。
+
+```typescript
+class mData {
+    data: {
+        // 导入
+        import: {
+            [namespace: string]: {
+                [tagName: string]: string  // 路径
+            }
+        },
+
+        // 模板
+        template: {
+            var: {
+                [varName: string]: {
+                    type: "element" | "import" | "text",
+                    tagName?: string,
+                    attribs?: object,
+                    event?: object,
+                    args?: object,
+                    keyword?: object,
+                    content?: string
+                }
+            },
+            sh: string[],          // DOM 构建语句
+            fragment: boolean      // 是否为片段
+        },
+
+        // 脚本
+        before: { code: string },
+        global: { code: string },
+        event: {
+            code: string,
+            list: string[]
+        },
+        listen: {
+            code: string,
+            list: string[]
+        },
+        interface: {
+            code: string,
+            list: string[]
+        },
+        once_interface: string[],
+
+        // 样式
+        css: string,
+        cssScope: { [key: string]: string },
+
+        // 事件暴露
+        "expose-event": string,
+
+        // 元素 ID 列表
+        "use-element-id-list": string[],
+
+        // 元数据
+        name: string,
+        originalFile: string,
+        templateArgs: { inline: boolean }
+    }
+}
+```
+
+### 1.4 IndexDom 类
+
+```typescript
+class IndexDom {
+    headString: string;            // head 内容
+    bodyString: string;           // body 内容
+
+    // 添加元素
+    add(load: "begin" | "end", element: {
+        tag: string,
+        attrs: { [key: string]: string }[],
+        one?: boolean
+    }): void;
+
+    // 生成 HTML
+    generate(): string;
+}
+```
+
+---
+
+## 2. 构建配置模型
+
+### 2.1 Type 配置类型定义
+
+位置: `script/module/compiler/project-build-config.js`
+
+```typescript
+class Type {
+    type: "string" | "number" | "boolean" | "array" | "object";
+    key: boolean;                 // 是否必需
+    scope: any[] | false;         // 枚举范围
+
+    getScope(): any[] | false;
+    getType(): string;
+    isKey(): boolean;
+}
+```
+
+### 2.2 ProjectBuildConfig
+
+```typescript
+const ProjectBuildConfig = {
+    // Web 平台基础配置
+    base: {
+        config: {
+            name: Type("string"),     // 项目名
+            src: Type("string"),       // 源码目录
+            main: Type("string")      // 入口
+        },
+        build: {
+            out: Type("string"),
+            model: Type("string", true, ["debug", "release"]),
+            platform: {
+                target: Type("string", true, ["web", "node-webkit", "module"]),
+                config: Type("object")
+            },
+            exclude: {
+                dir: Type("array", false),
+                file: Type("array", false)
+            },
+            optimize: {
+                "out-default-theme": Type("boolean", false, [true, false]),
+                "min-code": {
+                    js: Type("boolean", false, [true, false]),
+                    css: Type("boolean", false, [true, false]),
+                    html: Type("boolean", false, [true, false])
+                }
+            },
+            import: {
+                module: Type("array", false)
+            }
+        }
+    },
+
+    // 模块配置
+    base_module: { /* ... */ },
+
+    // Web 平台配置
+    web: { /* base + server config */ },
+
+    // Node-Webkit 配置
+    nodeWebkit: { /* base + app */ }
+};
+```
+
+---
+
+## 3. app.xml 数据模型
+
+### 3.1 AppConfig 结构
+
+```typescript
+interface AppConfig {
+    lang: string;                 // 语言代码
+    icon: string | false;        // 图标路径
+    title: string;               // 页面标题
+    initScript: string | null;   // 初始化脚本
+    import: ImportItem[];        // 导入列表
+}
+
+interface ImportItem {
+    o: {
+        element: string;         // 生成的 HTML 标签
+        load: "begin" | "end" | string;
+    }
+}
+```
+
+### 3.2 Import 解析结构
+
+```typescript
+interface ImportGroup {
+    // 命名空间
+    namespace?: string;
+
+    // 根路径
+    root?: string;
+
+    // 子节点
+    childNodes: ImportNode[];
+}
+
+interface ImportNode {
+    // 模块标签名
+    rawTagName: string;
+
+    // 属性
+    attrs: { [key: string]: string };
+
+    // 子节点
+    childNodes?: ImportNode[];
+}
+
+interface ParsedImport {
+    [namespace: string]: {
+        [tagName: string]: string  // 模块路径
+    }
+}
+```
+
+---
+
+## 4. Runtime 数据模型
+
+### 4.1 Window 全局对象
+
+```typescript
+// 全局版本号
+const magic_version: string;
+
+// 全局空值
+const nop: null;
+
+// Magic 内部存储
+const __MAGIC__: {
+    M: {
+        [moduleName: string]: new (...args: any[]) => any
+    },
+    CREATE_ELEMENT_LIST: Map<any, any>
+};
+```
+
+### 4.2 magic 对象结构
+
+```typescript
+const magic: {
+    // 初始化
+    init(main: string): void;
+
+    // DOM 操作
+    dom: {
+        element(tag: string): HTMLElement;
+        text(content: string): Text;
+        append(p: HTMLElement, ...childs: any[]): void;
+        attribute(e: HTMLElement, atts: object): void;
+        event(e: HTMLElement, eventName: string, _this: any, fnName: string, opt?: object): void;
+    };
+
+    // 模块操作
+    importM(name: string, args?: object, listen?: object): ImportedModuleElement;
+
+    // 作用域调用
+    call(scope: any): {
+        interface: (name: string, ...args: any[]) => any;
+        event: (name: string, ...args: any[]) => any;
+        listen: (name: string, ...args: any[]) => any;
+    };
+
+    // 事件发射
+    emit: {
+        event(listen: object): (name: string, ...args: any[]) => any;
+    };
+
+    // 元素查找
+    $id(_$id: Map<string, HTMLElement>): {
+        (): Record<string, HTMLElement>;
+        (id: string): HTMLElement;
+    };
+
+    // 参数处理
+    parserArgs(args: string | object): object;
+    createArgs(obj: object): string;
+    parserListen(listen?: object): object;
+
+    // 事件处理
+    on_event(event: object, listen: object): any;
+    end_event(event: object, listen: object): any;
+
+    // ID 管理
+    mapIdElement(): Map<string, HTMLElement> & {
+        s(id: string, e: HTMLElement, s?: string): void;
+    };
+
+    // UI 数据
+    createUiData(target: object, source: object): object;
+
+    // 元素初始化
+    importElementInit(...args: any[]): void;
+
+    // 接口导出
+    exportInterface(scope: object, target: object, parcel: object): void;
+
+    // 获取接口
+    GetInterface(ele: HTMLElement): object | null;
+
+    // 作用域绑定
+    BindScope(arr: HTMLElement[], ths: object): HTMLElement[];
+
+    // 动态绑定
+    DynamicValueBind(...elements: HTMLElement[]): void;
+
+    // ID 生成
+    idGenerate(): string;
+
+    // DOM 查询
+    $(id: string, root?: HTMLElement): HTMLElement | null;
+};
+```
+
+### 4.3 ImportedModuleElement 接口
+
+```typescript
+interface ImportedModuleElement extends HTMLElement {
+    // 文件路径
+    __file: string;
+
+    // 模块 ID
+    mid: string;
+
+    // 文档片段
+    fragment: DocumentFragment;
+
+    // 接口对象
+    interface: {
+        [methodName: string]: (...args: any[]) => any;
+    };
+
+    // 模板参数
+    templateArgs: {
+        inline: boolean;
+    };
+
+    // 根元素
+    __root__element__: HTMLElement;
+
+    // 暴露的事件
+    exposeEvent: object;
+}
+```
+
+---
+
+## 5. 编译输出模型
+
+### 5.1 生成的模块结构
+
+```javascript
+// 编译后的 .m.js 文件
+window["__MAGIC__"]["M"]["模块名"] = function(__args__, __listen__) {
+    const call = magic.call(this);
+    this._$id = magic.mapIdElement();
+    const $id = magic.$id(this._$id);
+    const _args = {_file: "path", _id: magic.idGenerate(), ...magic.parserArgs(__args__)};
+    const _listen = magic.parserListen(__listen__);
+    const emit_event = magic.emit.event(_listen);
+
+    // 元素定义
+    let $e1, $e2, $t1;
+    this.__magic_element_root = document.createDocumentFragment();
+
+    // before 脚本
+    { before_code }
+
+    // 模板渲染
+    this.__magic_template = (() => {
+        const { element: e, text: t, ... } = magic.dom;
+        return {
+            render: () => {
+                // 元素创建
+                // 属性设置
+                // 事件绑定
+                // DOM 追加
+            },
+            bind_event: () => { /* 事件绑定 */ },
+            export_element: () => { /* 导出元素 */ }
+        };
+    })();
+
+    this.__magic_template.render();
+
+    // global 脚本
+    { global_code }
+
+    // listen 脚本
+    { listen_code }
+
+    // event 脚本
+    { event_code }
+
+    this.__magic_template.bind_event();
+
+    // interface 脚本
+    { interface_code }
+
+    // default 脚本
+    { script_code }
+
+    // 返回元素
+    return { /* fragment or element */ };
+};
+```
+
+### 5.2 module.info.json 结构
+
+模块模式构建时生成：
+
+```json
+{
+    "name": "module-name",
+    "dir": "output-dir",
+    "model": "release",
+    "files": [
+        "default-theme-var.css",
+        "module.js",
+        "module.css"
+    ]
+}
+```
+
+---
+
+## 6. 宏处理数据流
+
+### 6.1 magic_define_include
+
+```typescript
+// 输入
+magic_define_include("./template.html")
+
+// 编译时处理
+const filePath = "./template.html";
+const fileContent = fs.readFileSync(filePath);
+
+// 输出
+// 替换为文件内容字符串
+```
+
+### 6.2 magic_define_ui_data
+
+```typescript
+// 输入
+const UiData = magic_define_ui_data({
+    text: "hello",
+    count: 0
+});
+
+// 编译时处理
+// 转换为 magic.createUiData() 调用
+
+// 输出
+const UiData = magic.createUiData({
+    text: "hello",
+    count: 0
+}, _args);
+```
+
+### 6.3 magic_dynamic_value_bind
+
+```typescript
+// 输入
+magic_dynamic_value_bind($textElement)
+
+// 编译时处理
+// 添加到 uiData 的绑定列表
+
+// 输出
+magic.DynamicValueBind($textElement, UiData);
+```
+
+---
+
+## 7. CSS 变量映射
+
+### 7.1 default-theme-var.css 结构
+
+```css
+:root {
+    --组件名-作用域-属性名-序号: 原始值;
+    --button-m-css-scope-xxx-background-color: #c6c6c6;
+    --button-m-css-scope-xxx-border-radius: 5px;
+}
+```
+
+### 7.2 CSS 作用域映射
+
+```typescript
+// 输入
+<css scope="#id:button">
+& {
+    background-color: #c6c6c6;
+}
+</css>
+
+// 编译时生成
+.m-css-scope-{随机6位} {
+    background-color: var(--button-m-css-scope-{随机6位}-background-color);
+}
+```
+
+---
+
+## 8. 事件系统数据流
+
+### 8.1 事件对象结构
+
+```typescript
+interface MagicEvent {
+    type: string;               // 事件类型
+    runState?: "on" | "end";   // 运行状态
+}
+```
+
+### 8.2 监听器注册
+
+```typescript
+// 模板中定义
+<button @click="handler:arg1,arg2">
+
+// 编译后
+magic.dom.event(
+    buttonElement,
+    "click",
+    scope,
+    "handler",
+    { /* options */ }
+);
+```
+
+### 8.3 emit_event 调用
+
+```typescript
+// 定义
+emit_event("select", { value: "A" });
+
+// 实现
+const emit_event = magic.emit.event(_listen);
+emit_event("select", { value: "A" });
+```