@love-sqjm/magic 2026.4.15

package/doc/api/index.md

@@ -0,0 +1,563 @@
+# Magic Runtime API 参考
+
+## 概述
+
+Magic Runtime 是框架的客户端运行时库，提供 DOM 操作、模块加载、事件处理等核心功能。
+
+## 全局对象
+
+### magic_version
+
+框架版本号（只读）
+
+```typescript
+const version: string;
+console.log(magic_version); // "1.0.0"
+```
+
+### nop
+
+空值常量，用于接口占位
+
+```typescript
+const nop: null;
+```
+
+### __MAGIC__
+
+框架内部存储对象
+
+```typescript
+const __MAGIC__: {
+    M: Record<string, new (...args: any[]) => any>;
+    CREATE_ELEMENT_LIST: Map<any, any>;
+};
+```
+
+## magic 对象
+
+框架核心对象，提供所有运行时功能。
+
+### init()
+
+初始化 Magic 框架
+
+```typescript
+init(main: string): void
+```
+
+**参数:**
+- `main` - 主模块名称
+
+**示例:**
+```javascript
+magic.init("index");
+```
+
+---
+
+### dom
+
+DOM 操作工具集
+
+#### dom.element()
+
+创建 DOM 元素
+
+```typescript
+element(tag: string): HTMLElement & { __MAGIC_CREATE_ELEMENT__: boolean }
+```
+
+**示例:**
+```javascript
+const div = magic.dom.element("div");
+```
+
+#### dom.text()
+
+创建文本节点
+
+```typescript
+text(content: string): Text
+```
+
+**示例:**
+```javascript
+const textNode = magic.dom.text("Hello");
+```
+
+#### dom.append()
+
+追加子元素
+
+```typescript
+append(
+    p: HTMLElement | DocumentFragment,
+    ...childs: Array<HTMLElement | { fragment: DocumentFragment }>
+): void
+```
+
+**示例:**
+```javascript
+magic.dom.append(parentElement, child1, child2);
+```
+
+#### dom.attribute()
+
+设置元素属性
+
+```typescript
+attribute(e: HTMLElement, atts: Record<string, string>): void
+```
+
+**示例:**
+```javascript
+magic.dom.attribute(element, {
+    "class": "container active",
+    "data-id": "123"
+});
+```
+
+#### dom.event()
+
+绑定元素事件
+
+```typescript
+event(
+    e: HTMLElement,
+    eventName: string,
+    _this: { __magic_event: Record<string, Function> },
+    fnName: string,
+    opt?: AddEventListenerOptions
+): void
+```
+
+**示例:**
+```javascript
+magic.dom.event(element, "click", scope, "handleClick");
+```
+
+---
+
+### importM()
+
+导入并实例化模块
+
+```typescript
+importM(
+    name: string,
+    args?: Record<string, any>,
+    listen?: Record<string, Function>
+): ImportedModuleElement
+```
+
+**参数:**
+- `name` - 模块名称（会自动转小写并过滤非字母字符）
+- `args` - 传递给模块的参数
+- `listen` - 事件监听对象
+
+**返回值:** ImportedModuleElement
+
+**示例:**
+```javascript
+const dialog = magic.importM("ui/widget/dialog", {
+    title: "Hello",
+    width: 300
+}, {
+    close: (data) => console.log("Closed:", data)
+});
+```
+
+**返回值接口:**
+```typescript
+interface ImportedModuleElement extends HTMLElement {
+    __file: string;           // 文件路径
+    mid: string;              // 模块 ID
+    fragment: DocumentFragment;
+    interface: Record<string, Function>;  // 模块接口
+    templateArgs: {
+        inline: boolean;
+    };
+    __root__element__: HTMLElement;
+}
+```
+
+---
+
+### call()
+
+创建作用域调用器
+
+```typescript
+call(scope: {
+    __magic_interface: Record<string, Function>;
+    __magic_event: Record<string, Function>;
+}): {
+    interface: (name: string, ...args: any[]) => any;
+    event: (name: string, ...args: any[]) => any;
+    listen: (funcName: string, ...args: any[]) => any;
+}
+```
+
+**示例:**
+```javascript
+const caller = magic.call(moduleInstance);
+caller.interface("setTitle", "New Title");
+caller.event("click", eventData);
+```
+
+---
+
+### emit
+
+事件发射器
+
+#### emit.event()
+
+创建事件发射函数
+
+```typescript
+emit.event(listen: Record<string, Function>): (name: string, ...args: any[]) => any
+```
+
+**示例:**
+```javascript
+const emit_event = magic.emit.event({
+    select: (data) => console.log("Selected:", data)
+});
+emit_event("select", { value: "A" });
+```
+
+---
+
+### $id()
+
+创建 ID 元素查找器
+
+```typescript
+$id(_$id: Map<string, HTMLElement>): {
+    (): Record<string, HTMLElement>;
+    (id: string): HTMLElement;
+}
+```
+
+**示例:**
+```javascript
+const ids = $id(elementMap);
+const element = ids();           // 获取所有元素
+const btn = ids("submit-btn");   // 获取指定 ID 的元素
+```
+
+---
+
+### parserArgs()
+
+解析参数对象
+
+```typescript
+parserArgs(args: string | Record<string, any>): Record<string, any>
+```
+
+**特性:**
+- 字符串参数会被解析为 JSON
+- 支持嵌套键解析（`a:b:c` → `{a: {b: {c: value}}}`）
+
+**示例:**
+```javascript
+magic.parserArgs('{"name": "test"}');
+magic.parserArgs({ "user:profile:name": "John" });
+// 结果: { user: { profile: { name: "John" } } }
+```
+
+---
+
+### createArgs()
+
+创建参数字符串
+
+```typescript
+createArgs(obj: Record<string, any>): string
+```
+
+**示例:**
+```javascript
+const jsonStr = magic.createArgs({ name: "test", value: 123 });
+```
+
+---
+
+### parserListen()
+
+解析事件监听对象
+
+```typescript
+parserListen(listen?: Record<string, any>): Record<string, any>
+```
+
+**示例:**
+```javascript
+const handlers = magic.parserListen({
+    click: handleClick,
+    change: handleChange
+});
+```
+
+---
+
+### on_event()
+
+触发事件（开始阶段）
+
+```typescript
+on_event(
+    event: { type: string; runState?: string },
+    listen: Record<string, Function>
+): any
+```
+
+**特性:**
+- 设置 `event.runState = "on"`
+- 调用匹配的监听函数
+
+---
+
+### end_event()
+
+触发事件（结束阶段）
+
+```typescript
+end_event(
+    event: { type: string; runState?: string },
+    listen: Record<string, Function>
+): any
+```
+
+**特性:**
+- 设置 `event.runState = "end"`
+- 调用匹配的监听函数
+
+---
+
+### mapIdElement()
+
+创建 ID-元素映射表
+
+```typescript
+mapIdElement(): Map<string, HTMLElement> & {
+    s(id: string, e: HTMLElement, s?: string): void;
+}
+```
+
+**示例:**
+```javascript
+const map = magic.mapIdElement();
+map.s("myId", element, "active");
+```
+
+---
+
+### createUiData()
+
+合并 UI 数据（深度拷贝）
+
+```typescript
+createUiData(
+    target: Record<string, any>,
+    source: Record<string, any>
+): Record<string, any>
+```
+
+**特性:**
+- 深度合并对象
+- 类型转换支持（Boolean、Number、Array、RegExp）
+- 返回带响应式绑定的深拷贝代理
+
+**示例:**
+```javascript
+const defaults = { text: "Hello", count: 0 };
+const userData = { text: "World" };
+const merged = magic.createUiData(defaults, userData);
+```
+
+---
+
+### importElementInit()
+
+初始化导入的元素
+
+```typescript
+importElementInit(...args: Array<{ interface: Record<string, any> }>): void
+```
+
+**描述:**
+依次调用每个元素的 `_render` 和 `__render__` 接口方法（如果存在）。
+
+---
+
+### exportInterface()
+
+导出接口到目标对象
+
+```typescript
+exportInterface(
+    scope: Record<string, any>,
+    target: Record<string, any>,
+    parcel: Record<string, any>
+): void
+```
+
+**参数:**
+- `scope` - 源作用域对象
+- `target` - 目标对象
+- `parcel` - 接口映射配置
+
+**示例:**
+```javascript
+magic.exportInterface(scope, target, {
+    _render: nop,           // 直接映射
+    onClick: (args) => {}    // 函数包装
+});
+```
+
+---
+
+### GetInterface()
+
+获取元素绑定的作用域接口
+
+```typescript
+GetInterface(ele: HTMLElement): Record<string, any> | null
+```
+
+---
+
+### BindScope()
+
+为元素数组绑定作用域
+
+```typescript
+BindScope(
+    arr: HTMLElement[],
+    ths: Record<string, any>
+): Array<HTMLElement & { readonly __SCOPE__: Record<string, any> }>
+```
+
+**特性:**
+- 为元素添加不可写的 `__SCOPE__` 属性
+- 添加 `__MAGIC_MODULE_ID` 标识
+
+---
+
+### DynamicValueBind()
+
+动态值绑定
+
+```typescript
+DynamicValueBind(...elements: HTMLElement[], uiData: object): void
+```
+
+**示例:**
+```javascript
+magic.DynamicValueBind(textElement1, textElement2, uiData);
+```
+
+---
+
+## 编译时宏
+
+### magic_define_include()
+
+编译时宏，包含文件内容
+
+```typescript
+magic_define_include(path: string): string
+```
+
+**限制:** 参数必须是静态字符串
+
+---
+
+### magic_define_ui_data()
+
+编译时宏，创建 UiData 对象
+
+```typescript
+magic_define_ui_data(data: object): object
+```
+
+**转换:** 编译时转换为 `magic.createUiData()` 调用
+
+---
+
+### magic_dynamic_value_bind()
+
+编译时宏，动态值绑定
+
+```typescript
+magic_dynamic_value_bind(...nodes: HTMLElement[]): void
+```
+
+**前置条件:** 必须先使用 `magic_define_ui_data` 创建 UiData 对象
+
+**转换:** 编译时转换为 `magic.DynamicValueBind()` 调用
+
+---
+
+## Element 扩展
+
+### remove()
+
+Magic 重写了 Element.prototype.remove，在移除元素前执行清理逻辑。
+
+```typescript
+interface Element {
+    remove(): void;
+}
+```
+
+**行为:**
+1. 遍历所有子元素执行清理
+2. 调用原生 remove 方法
+
+---
+
+## 示例代码
+
+### 模块定义与使用
+
+**模块 (button.m):**
+```xml
+<template>
+    <button #id="btn">点击</button>
+</template>
+
+<script code="global">
+const { $btn } = $id();
+</script>
+
+<script code="event">
+click = () => {
+    emit_event("click", { time: Date.now() });
+}
+</script>
+
+<script code="interface">
+setText = (text) => {
+    $btn.textContent = text;
+};
+</script>
+
+<expose-event>
+    <click/>
+</expose-event>
+```
+
+**使用:**
+```javascript
+const btn = magic.importM("button");
+btn.interface.setText("新文本");
+
+const btn2 = magic.importM("button", {}, {
+    click: (data) => console.log("Clicked at:", data.time)
+});
+```