@love-sqjm/magic 2026.4.15

package/doc/magic-file/index.md

@@ -0,0 +1,610 @@
+# Magic .m 文件格式规范
+
+## 概述
+
+`.m` 文件是 Magic 框架的核心组件格式，它将 HTML 模板、CSS 样式和 JavaScript 脚本整合到单一声明式文件中。
+
+## 文件结构
+
+```xml
+<import>           <!-- 1. 模块导入 (可选) -->
+<template>         <!-- 2. DOM 模板 (必需) -->
+<script code="">  <!-- 3. 脚本 (可选, 可多个) -->
+<css>             <!-- 4. 样式 (可选, 可多个) -->
+<expose-event>    <!-- 5. 事件暴露 (可选) -->
+```
+
+## 1. import - 模块导入
+
+### 基本语法
+
+```xml
+<import>
+    <!-- 导入组件 -->
+    <button/>
+    <edit/>
+    <list-view/>
+</import>
+```
+
+### 带命名空间
+
+```xml
+<import namespace="magic-ui/ui">
+    <!-- 从指定命名空间导入 -->
+    <module:control>
+        <list-view/>
+    </module:control>
+    <module:input>
+        <button/>
+        <search/>
+    </module:input>
+</import>
+```
+
+### 带 root 属性
+
+```xml
+<import root="magic-ui/ui">
+    <!-- root 指定基础路径 -->
+</import>
+```
+
+### 组合使用
+
+```xml
+<import root="magic-ui/ui">
+    <module:control>
+        <list-view/>
+    </module:control>
+    <module:input>
+        <button/>
+    </module:input>
+</import>
+```
+
+### import 属性说明
+
+| 属性 | 说明 |
+|------|------|
+| `namespace` | 命名空间前缀，区分不同模块组 |
+| `root` | 基础路径，解析模块的相对路径 |
+
+### 模块路径解析规则
+
+1. 无命名空间: `<组件名>` → `{root}/{组件名}/{组件名}.m`
+2. 有命名空间: `<命名空间:组件名>` → `{root}/{命名空间}/{组件名}.m`
+
+## 2. template - DOM 模板
+
+### 基本语法
+
+```xml
+<template>
+    <div>Hello World</div>
+</template>
+```
+
+### 元素属性
+
+| 属性前缀 | 说明 | 示例 |
+|----------|------|------|
+| `#id` | 元素 ID，用于 `$id()` 获取 | `<div #id="myDiv">` |
+| `#name` | 元素名称，用于 `$name()` 查找 | `<div #name="title">` |
+| `@事件名` | 绑定事件监听 | `<button @click="handler">` |
+| `:属性` | 传递参数给组件 | `<comp :value="123">` |
+| `#id:监听名` | 监听子模块事件 | `<child #listen:select="handler">` |
+
+### 属性详解
+
+#### #id - 元素标识
+
+```xml
+<template>
+    <div #id="container">
+        <span #id="title">Title</span>
+    </div>
+</template>
+```
+
+#### @ - 事件绑定
+
+```xml
+<!-- 基本用法 -->
+<button @click="click">Click</button>
+
+<!-- 带参数 -->
+<button @click="click:arg1,arg2">Click</button>
+```
+
+事件格式: `@事件名="处理函数"` 或 `@事件名="处理函数:参数"`
+
+#### : - 参数传递
+
+```xml
+<!-- 传递静态值 -->
+<edit :text="Hello" />
+
+<!-- 传递动态值 -->
+<edit :value="someVariable" />
+```
+
+#### #listen - 监听子模块事件
+
+```xml
+<!-- 监听子模块暴露的事件 -->
+<child-component #listen:select="onSelect"/>
+```
+
+#### #import - 动态导入
+
+```xml
+<!-- 动态导入模块 -->
+<dynamic-component #import="path/to/module"/>
+```
+
+### 文本插值
+
+使用 `${}` 语法进行文本插值:
+
+```xml
+<template>
+    <p>Hello ${userName}</p>
+    <p>Count: ${count + 1}</p>
+</template>
+```
+
+### 完整示例
+
+```xml
+<template>
+    <div #id="main-view">
+        <h1 #id="title">${projectName}</h1>
+        <button
+            #id="submit-btn"
+            @click="submit:arg1"
+            :text="提交"
+        >提交</button>
+        <child-component #listen:select="onSelect"/>
+    </div>
+</template>
+```
+
+## 3. script - 脚本
+
+### 脚本类型
+
+通过 `code` 属性区分不同类型的脚本:
+
+| code 值 | 加载顺序 | 说明 |
+|---------|----------|------|
+| 无 / `default` | 4 | 普通脚本，组件初始化后执行 |
+| `before` | -1 | 元素生成前执行，无法调用元素 |
+| `global` | 0 | 全局脚本，元素生成后执行 |
+| `event` | 2 | 事件处理函数定义 |
+| `listen` | 1 | 监听功能定义 |
+| `interface` | 3 | 接口方法定义 |
+
+### 加载顺序图
+
+```
+before(-1) → global(0) → listen(1) → event(2) → interface(3) → default(4)
+```
+
+### 脚本作用域
+
+在 `<script>` 中可以使用以下内置对象:
+
+| 对象 | 说明 |
+|------|------|
+| `$id()` | 获取模板中定义的元素 |
+| `emit_event` | 触发事件 |
+| `UiData` | UI 数据对象 (通过 `magic_define_ui_data` 创建) |
+
+### $id() 用法
+
+```xml
+<script code="global">
+const {
+    $mainView,    // 获取 #id="mainView" 的元素
+    $title,       // 获取 #id="title" 的元素
+    $submitBtn    // 获取 #id="submitBtn" 的元素
+} = $id();
+</script>
+```
+
+### emit_event 用法
+
+```xml
+<script code="event">
+click = (event) => {
+    emit_event("select", { value: "test" });
+}
+</script>
+```
+
+### 完整示例
+
+```xml
+<script code="before">
+// 可以定义函数和变量
+function createItems(...textArr) {
+    const arr = [];
+    textArr.forEach(text => {
+        arr.push(magic.importM("item", { text }));
+    });
+    return arr;
+}
+
+const templateItemList = {
+    "type-a": createItems("A", "B"),
+    "type-b": createItems("X", "Y")
+};
+</script>
+
+<script code="global">
+// 获取元素
+const {
+    $container,
+    $title
+} = $id();
+</script>
+
+<script code="listen">
+// 监听处理 - 接收子模块事件
+typeSelect = (data) => {
+    console.log("Selected:", data);
+}
+</script>
+
+<script code="event">
+// 事件处理函数
+click = (event) => {
+    console.log("Clicked!");
+}
+</script>
+
+<script code="interface" once>
+setTitle = (title) => {
+    $title.textContent = title;
+};
+</script>
+
+<script>
+// 普通脚本 - 组件初始化逻辑
+function init() {
+    $container.appendChild(something);
+}
+init();
+</script>
+```
+
+## 4. css - 样式
+
+### 基本语法
+
+```xml
+<css>
+div {
+    color: red;
+}
+</css>
+```
+
+### scope 属性 - 作用域
+
+| scope 值 | 效果 |
+|----------|------|
+| 无 | 全局样式 |
+| `#id:xx` | 作用于 `#id="xx"` 的元素 |
+| `.class` | 作用于指定 class 的元素 |
+| `#id` | 作用于指定 id 的元素 |
+
+#### #id:xx 作用域
+
+```xml
+<!-- Magic 特有的选择器语法 -->
+<css scope="#id:myComponent">
+/* 只影响 #id="myComponent" 内部的元素 */
+& {
+    color: red;
+}
+& > .child {
+    padding: 10px;
+}
+</css>
+```
+
+编译后自动转换为带唯一类名的选择器:
+
+```css
+.m-css-scope-abc123 {
+    color: red;
+}
+.m-css-scope-abc123 > .child {
+    padding: 10px;
+}
+```
+
+### default-theme 属性
+
+添加 `default-theme` 属性会将所有 CSS 值转换为 CSS 变量，用于主题化样式。
+
+**使用场景：**
+- 用于定义元素的基础样式（颜色、边框、背景等）
+- 这些样式可以被主题系统覆盖
+- 适合需要随主题变化的样式
+
+```xml
+<css scope="#id:button" default-theme>
+& {
+    background-color: #c6c6c6;
+    border-radius: 5px;
+    color: #333333;
+}
+</css>
+```
+
+生成默认主题变量文件 `default-theme-var.css`:
+
+```css
+:root {
+    --button-m-css-scope-xxx-background-color: #c6c6c6;
+    --button-m-css-scope-xxx-border-radius: 5px;
+    --button-m-css-scope-xxx-color: #333333;
+}
+.m-css-scope-xxx {
+    background-color: var(--button-m-css-scope-xxx-background-color);
+    border-radius: var(--button-m-css-scope-xxx-border-radius);
+    color: var(--button-m-css-scope-xxx-color);
+}
+```
+
+### 无 default-theme 的 CSS
+
+不使用 `default-theme` 的 CSS 会直接输出，不转换为变量。
+
+**使用场景：**
+- 用于定义元素的布局样式（display、position、text-wrap 等）
+- 这些样式定义了元素本身的行为，不应被主题覆盖
+- 适合结构性样式
+
+```xml
+<css scope="#id:app">
+& {
+    display: flex;
+    text-wrap: wrap;
+    position: relative;
+}
+</css>
+```
+
+### default-theme 的最佳实践
+
+**推荐用法：**
+- 有 `default-theme`：定义可主题化的样式（颜色、字体、边框等）
+- 无 `default-theme`：定义布局和行为样式（flex、grid、position 等）
+
+```xml
+<!-- 主题样式：颜色、背景等 -->
+<css scope="#id:app" default-theme>
+& {
+    background-color: pink;
+    color: #333;
+}
+</css>
+
+<!-- 布局样式：flex、position 等 -->
+<css scope="#id:app">
+& {
+    display: flex;
+    text-wrap: wrap;
+}
+</css>
+```
+
+### & 引用符
+
+`&` 代表当前作用域的根元素:
+
+```xml
+<css scope="#id:container">
+& {
+    padding: 10px;  /* #id="container" 本身 */
+}
+& > .child {
+    margin: 5px;    /* #id="container" 的直接子元素 .child */
+}
+</css>
+```
+
+### 完整示例
+
+```xml
+<css scope="#id:message" default-theme>
+& {
+    background-color: #ff0000;
+    color: #ffffff;
+}
+</css>
+
+<css scope="#id:message">
+& {
+    display: flex;
+    align-items: center;
+    padding: 5px;
+}
+& > .icon {
+    font-size: 20px;
+}
+</css>
+```
+
+## 5. expose-event - 事件暴露
+
+定义子模块可以触发的事件，供父模块通过 `#listen` 监听。
+
+### 基本语法
+
+```xml
+<expose-event>
+    <click/>
+    <change/>
+</expose-event>
+```
+
+### 带参数
+
+```xml
+<expose-event>
+    <select :value/>
+    <change :oldValue :newValue/>
+</expose-event>
+```
+
+### 完整示例
+
+```xml
+<expose-event>
+    <click/>
+    <select :value/>
+</expose-event>
+```
+
+在 `<script code="event">` 中通过 `emit_event()` 触发:
+
+```xml
+<script code="event">
+click = (event) => {
+    emit_event("click", event);
+}
+select = (data) => {
+    emit_event("select", { value: data });
+}
+</script>
+```
+
+父模块监听:
+
+```xml
+<template>
+    <my-component #listen:click="onClick" #listen:select="onSelect"/>
+</template>
+```
+
+## 6. 宏 - 编译时处理
+
+### magic_define_include
+
+在编译时包含文件内容:
+
+```xml
+<script code="before">
+const template = magic_define_include("./template.html");
+</script>
+```
+
+### magic_define_ui_data
+
+创建带类型转换和响应式绑定的 UI 数据对象:
+
+```xml
+<script code="global">
+const UiData = magic_define_ui_data({
+    text: "hello",
+    count: 0,
+    options: ["a", "b"]
+});
+</script>
+```
+
+### magic_dynamic_value_bind
+
+动态绑定值到文本节点:
+
+```xml
+<script code="interface">
+show = (text) => {
+    magic_dynamic_value_bind($textElement, UiData);
+}
+</script>
+```
+
+## 7. 完整示例
+
+```xml
+<import root="magic-ui/ui">
+    <module:input>
+        <button/>
+        <edit/>
+    </module:input>
+</import>
+
+<template>
+    <div #id="container">
+        <h2 #id="title">新建项目</h2>
+        <edit #id="name-input" :placeholder="项目名称"/>
+        <button #id="submit-btn" @click="submit">创建</button>
+    </div>
+</template>
+
+<script code="before">
+function validateName(name) {
+    return name.length > 0;
+}
+</script>
+
+<script code="global">
+const {
+    $container,
+    $title,
+    $nameInput,
+    $submitBtn
+} = $id();
+</script>
+
+<expose-event>
+    <confirm/>
+    <cancel/>
+</expose-event>
+
+<script code="event">
+submit = (event) => {
+    const name = $nameInput.value;
+    if (validateName(name)) {
+        emit_event("confirm", { name });
+    }
+}
+</script>
+
+<script code="interface">
+setTitle = (title) => {
+    $title.textContent = title;
+};
+</script>
+
+<css scope="#id:container" default-theme>
+& {
+    background-color: #f5f5f5;
+    padding: 20px;
+}
+</css>
+
+<css scope="#id:container">
+& {
+    display: flex;
+    flex-direction: column;
+    gap: 15px;
+    width: 350px;
+}
+</css>
+```
+
+## 8. 注意事项
+
+1. **模板根元素**: `<template>` 内必须有根元素
+2. **ID 唯一性**: `#id` 值在同一文件中必须唯一
+3. **脚本执行顺序**: 按照 `before` → `global` → `listen` → `event` → `interface` → `default` 的顺序执行
+4. **宏使用限制**: `magic_define_include` 的参数必须是静态字符串
+5. **CSS 作用域**: 使用 `#id:xx` 选择器避免样式冲突
+6. **事件命名**: 推荐使用小驼峰命名，如 `click`, `selectChange`