@love-sqjm/magic 2026.4.15

package/doc/development-guide.md

@@ -0,0 +1,582 @@
+# Magic 开发规范
+
+## 目录
+
+1. [编码标准](#1-编码标准)
+2. [命名约定](#2-命名约定)
+3. [文件组织](#3-文件组织)
+4. [组件开发规范](#4-组件开发规范)
+5. [CSS 规范](#5-css-规范)
+6. [事件处理规范](#6-事件处理规范)
+7. [接口设计规范](#7-接口设计规范)
+8. [文档规范](#8-文档规范)
+
+---
+
+## 1. 编码标准
+
+### 1.1 基本原则
+
+- 使用 UTF-8 编码
+- 使用 Tab 缩进（2-4 个 Tab）
+- 每行不超过 120 个字符
+- 关键字后加空格：`if (condition)`
+- 函数调用不加空格：`func(arg)`
+
+### 1.2 字符串
+
+- 优先使用单引号
+- 模板字符串用于多行或变量插值
+
+```javascript
+// 推荐
+const name = 'Magic';
+const message = `Hello, ${name}!`;
+
+// 避免
+const name = "Magic";
+```
+
+### 1.3 变量声明
+
+- 使用 `const` 优先于 `let`
+- 避免使用 `var`
+- 命名清晰的变量名
+
+```javascript
+// 推荐
+const maxRetries = 3;
+const userList = [];
+
+// 避免
+const a = 3;
+const list = [];
+```
+
+### 1.4 函数
+
+```javascript
+// 箭头函数
+const add = (a, b) => a + b;
+
+// 普通函数
+function multiply(a, b) {
+    return a * b;
+}
+
+// 异步函数
+async function fetchData(url) {
+    const response = await fetch(url);
+    return response.json();
+}
+```
+
+### 1.5 对象和数组
+
+```javascript
+// 对象
+const config = {
+    name: 'my-app',
+    version: '1.0.0',
+    getData() {
+        return this.name;
+    }
+};
+
+// 数组
+const items = [1, 2, 3];
+const newItems = items.map(item => item * 2);
+```
+
+---
+
+## 2. 命名约定
+
+### 2.1 文件命名
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| .m 组件 | kebab-case | `greeting-card.m`, `user-profile.m` |
+| JavaScript | camelCase | `util.js`, `api-handler.js` |
+| CSS | kebab-case | `theme.css`, `button-styles.css` |
+| 图片 | kebab-case | `logo-small.png`, `bg-pattern.jpg` |
+
+### 2.2 元素 ID 命名
+
+```xml
+<!-- 推荐：描述性名称 -->
+<div #id="header-container">...</div>
+<div #id="user-name-label">...</div>
+
+<!-- 避免：无意义名称 -->
+<div #id="div1">...</div>
+<div #id="d1">...</div>
+```
+
+**命名模式：**
+- `$id="元素类型-功能"` 如 `$id="main-content"`
+- `$id="元素类型-序号"` 如 `$id="list-item-1"`
+
+### 2.3 变量命名
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| 普通变量 | camelCase | `userName`, `isValid` |
+| 常量 | UPPER_SNAKE | `MAX_COUNT`, `API_URL` |
+| 布尔值 | is/has/can 前缀 | `isVisible`, `hasChildren` |
+| 数组 | 复数名词 | `users`, `itemList` |
+| DOM 元素 | `$` 前缀 | `$button`, `$container` |
+
+### 2.4 函数命名
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| 事件处理 | `on` + 事件名 | `onClick`, `onChange` |
+| 事件定义 | 动词 | `handleClick`, `processSubmit` |
+| 回调 | `callback` | `onCompleteCallback` |
+| 获取数据 | `get` + 名词 | `getUserData`, `fetchConfig` |
+| 设置数据 | `set` + 名词 | `setUserName`, `updateConfig` |
+| 判断 | `is`/`has`/`can` + 名词 | `isValid`, `hasPermission` |
+
+### 2.5 CSS 类名
+
+```css
+/* BEM 风格 */
+.button { }
+.button__icon { }
+.button--disabled { }
+
+/* 组件作用域 */
+.m-css-scope-xxx { }
+```
+
+---
+
+## 3. 文件组织
+
+### 3.1 目录结构
+
+```
+app/
+├── app.xml                 # 应用配置（必需）
+├── index.m                 # 入口模块（必需）
+├── components/             # 可复用组件
+│   ├── button/
+│   │   └── button.m
+│   ├── dialog/
+│   │   └── dialog.m
+│   └── card/
+│       └── card.m
+├── pages/                  # 页面组件
+│   ├── home/
+│   │   └── index.m
+│   └── about/
+│       └── index.m
+├── layouts/               # 布局组件
+│   └── main-layout.m
+├── shared/                # 共享模块
+│   ├── header.m
+│   └── footer.m
+└── assets/                 # 静态资源
+    ├── images/
+    ├── fonts/
+    └── data/
+```
+
+### 3.2 导入组织
+
+```xml
+<!-- 1. 导入外部库（如有） -->
+<!-- 2. 导入共享组件 -->
+<!-- 3. 导入页面组件 -->
+
+<import root=".">
+    <!-- 共享组件 -->
+    <header/>
+    <footer/>
+
+    <!-- 页面组件 -->
+    <home/>
+</import>
+```
+
+---
+
+## 4. 组件开发规范
+
+### 4.1 .m 文件结构顺序
+
+```xml
+<import>          <!-- 1. 导入（可选） -->
+<template>         <!-- 2. 模板（必需） -->
+<script code="">   <!-- 3. 脚本（可选，多个） -->
+<css>             <!-- 4. 样式（可选，多个） -->
+<expose-event>    <!-- 5. 事件暴露（可选） -->
+```
+
+### 4.2 模板规范
+
+```xml
+<template>
+    <!-- 根元素必须有 #id -->
+    <div #id="组件根元素">
+        <!-- 子元素使用有意义的 #id -->
+        <header #id="组件头部">
+            <h1 #id="标题">Title</h1>
+        </header>
+        <main #id="内容区域">
+            <!-- 组件内容 -->
+        </main>
+        <footer #id="组件底部">
+        </footer>
+    </div>
+</template>
+```
+
+### 4.3 脚本规范
+
+#### 全局脚本 (code="global")
+
+```xml
+<script code="global">
+// 1. 获取元素
+const {
+    $root,
+    $header,
+    $content
+} = $id();
+
+// 2. 定义组件状态
+const state = {
+    isExpanded: false
+};
+</script>
+```
+
+#### 事件脚本 (code="event")
+
+```xml
+<script code="event">
+// 事件处理函数定义
+clickHandler = (event) => {
+    // 处理点击
+}
+
+submitForm = (data) => {
+    // 处理表单提交
+}
+</script>
+```
+
+#### 接口脚本 (code="interface")
+
+```xml
+<script code="interface">
+// 对外暴露的方法
+setTitle = (title) => {
+    $header.textContent = title;
+};
+
+getData = () => {
+    return state;
+};
+</script>
+```
+
+### 4.4 组件接口设计
+
+```xml
+<!-- 组件 -->
+<script code="interface">
+// 数据设置
+setData = (data) => {
+    // 设置组件数据
+};
+
+// 状态控制
+enable = () => {};
+disable = () => {};
+
+// 事件触发
+show = () => {};
+hide = () => {};
+
+// 数据获取
+getValue = () => {};
+</script>
+```
+
+---
+
+## 5. CSS 规范
+
+### 5.1 作用域使用
+
+```xml
+<!-- 正确：使用 #id:xx 作用域 -->
+<css scope="#id:my-component">
+& {
+    /* 组件样式 */
+}
+</css>
+```
+
+### 5.2 样式分离
+
+```xml
+<!-- 主题样式（带 default-theme） -->
+<css scope="#id:button" default-theme>
+& {
+    background-color: #007bff;
+    color: #ffffff;
+}
+</css>
+
+<!-- 布局样式 -->
+<css scope="#id:button">
+& {
+    display: inline-flex;
+    padding: 8px 16px;
+    border-radius: 4px;
+}
+</css>
+```
+
+### 5.3 嵌套规则
+
+```xml
+<css scope="#id:card">
+& {
+    /* 根样式 */
+}
+& > .header {
+    /* 直接子元素 */
+}
+& .content {
+    /* 后代元素 */
+}
+&:hover {
+    /* 伪类 */
+}
+</css>
+```
+
+### 5.4 避免样式冲突
+
+- 不使用全局样式
+- 所有样式都在作用域内
+- 使用 `#id:xx` 而非直接使用元素名
+
+```xml
+<!-- 避免 -->
+<css>
+div { color: red; }
+</css>
+
+<!-- 推荐 -->
+<css scope="#id:container">
+& div { color: red; }
+</css>
+```
+
+---
+
+## 6. 事件处理规范
+
+### 6.1 事件命名
+
+使用小驼峰命名：
+
+| 事件 | 说明 |
+|------|------|
+| `click` | 点击 |
+| `change` | 值改变 |
+| `select` | 选中 |
+| `open` | 打开 |
+| `close` | 关闭 |
+| `submit` | 提交 |
+| `cancel` | 取消 |
+
+### 6.2 expose-event 定义
+
+```xml
+<expose-event>
+    <!-- 基本事件 -->
+    <click/>
+    <change/>
+
+    <!-- 带参数事件 -->
+    <select :value/>
+    <action :type :data/>
+</expose-event>
+```
+
+### 6.3 事件触发
+
+```xml
+<script code="event">
+click = (event) => {
+    emit_event("click", event);
+}
+
+select = (value) => {
+    emit_event("select", { value });
+}
+</script>
+```
+
+### 6.4 事件监听
+
+```xml
+<template>
+    <!-- 监听子组件事件 -->
+    <my-component
+        #listen:click="onChildClick"
+        #listen:select="onChildSelect"
+    />
+</template>
+
+<script code="listen">
+onChildClick = (event) => {
+    console.log("Child clicked:", event);
+}
+
+onChildSelect = (data) => {
+    console.log("Child selected:", data);
+}
+</script>
+```
+
+---
+
+## 7. 接口设计规范
+
+### 7.1 接口命名
+
+```xml
+<script code="interface">
+// 设置方法
+setData = (data) => {};
+setTitle = (title) => {};
+setOptions = (options) => {};
+
+// 获取方法
+getData = () => {};
+getValue = () => {};
+
+// 状态方法
+show = () => {};
+hide = () => {};
+enable = () => {};
+disable = () => {};
+
+// 动作方法
+refresh = () => {};
+reset = () => {};
+submit = () => {};
+</script>
+```
+
+### 7.2 once 接口
+
+`once` 标记的接口在模块初始化时只执行一次：
+
+```xml
+<script code="interface" once>
+initialize = () => {
+    // 只执行一次
+};
+</script>
+```
+
+### 7.3 接口参数设计
+
+```xml
+<script code="interface">
+// 简单参数
+setTitle = (title) => {};
+
+// 对象参数（推荐用于多参数）
+setConfig = (config) => {
+    if (config.width) { /* ... */ }
+    if (config.height) { /* ... */ }
+};
+
+// 回调参数
+load = (onComplete, onError) => {
+    // ...
+};
+</script>
+```
+
+---
+
+## 8. 文档规范
+
+### 8.1 .m 文件注释
+
+```xml
+<!--
+ * Button 组件
+ * 用于触发操作
+ *
+ * @param {string} text - 按钮文本
+ * @param {boolean} disabled - 是否禁用
+ * @fires click
+ -->
+<template>
+    <button #id="btn">按钮</button>
+</template>
+```
+
+### 8.2 脚本注释
+
+```javascript
+/**
+ * 处理按钮点击事件
+ * @param {Event} event - 原生事件对象
+ */
+clickHandler = (event) => {
+    // ...
+};
+```
+
+### 8.3 示例注释
+
+```xml
+<!-- 示例：基本用法 -->
+<!--
+<import root=".">
+    <my-button/>
+</import>
+
+<script>
+// 使用
+const btn = magic.importM("my-button");
+btn.interface.setText("点击我");
+</script>
+-->
+```
+
+---
+
+## 最佳实践总结
+
+### DO
+
+1. **使用有意义的命名**
+2. **保持组件职责单一**
+3. **合理拆分大型组件**
+4. **使用 `const` 避免意外修改**
+5. **事件处理函数抽离**
+6. **样式使用作用域隔离**
+7. **提供清晰的接口文档**
+
+### DON'T
+
+1. **避免全局变量污染**
+2. **避免巨型单一组件**
+3. **避免硬编码值**
+4. **避免样式冲突**
+5. **避免不必要的事件冒泡**
+6. **避免裸露的内部实现**