mm_tpl 2.4.4 → 2.4.6

package/README.md

@@ -1,6 +1,16 @@
 # mm_tpl
 
-这是超级美眉模板帮助类模块，用于MVC模式下的视图渲染。基于art-template模板引擎，提供了更强大的模板渲染功能。
+超级美眉模板引擎模块，基于art-template模板引擎，提供强大的MVC模式视图渲染功能，支持钩子系统、主题切换和缓存机制。
+
+## 特性
+
+- 🚀 基于art-template高性能模板引擎
+- 🔧 支持多种模板语法规则
+- 🎨 主题切换和模板文件优先级搜索
+- ⚡ 内置缓存机制提升性能
+- 🔌 强大的钩子系统支持
+- 📁 灵活的目录结构支持
+- 🛡️ 完善的错误处理机制
 
 ## 安装
 
@@ -8,35 +18,47 @@
 npm install mm_tpl
 ```
 
-## 基本使用
+## 快速开始
+
+### 1. 安装依赖
+
+```bash
+npm install mm_tpl
+```
 
-### 1. 初始化模板引擎
+### 2. 初始化模板引擎
 
 ```javascript
-const Tpl = require('mm_tpl');
+const {Tpl} = require('mm_tpl');
+
+// 创建模板实例
 const tpl = new Tpl({
-    // 可选配置参数
     root: process.cwd(),           // 根目录
     default_dir: "./template/",    // 默认模板目录
     default_theme: 'default',      // 默认主题
     extname: ".html",             // 模板文件扩展名
     cache_root: './cache',        // 缓存目录
-    cache_extname: '.cache.html'  // 缓存文件扩展名
+    cache_extname: '.cache.html', // 缓存文件扩展名
+    rules: [nativeRule, artRule, htmlRule, jsRule, pyRule, pyRule2] // 模板规则
 });
 ```
 
-### 2. 基础模板渲染
+### 3. 基础模板渲染
 
 ```javascript
 // 简单变量替换
 const result = tpl.render("<div>${message}</div>", {
     message: "Hello World"
 });
-
 // 输出: <div>Hello World</div>
+
+// 编译模板函数
+const compiled = tpl.compile("<div>${name} - ${age}</div>");
+const result2 = compiled({ name: "张三", age: 25 });
+// 输出: <div>张三 - 25</div>
 ```
 
-### 3. 循环渲染
+### 4. 循环渲染
 
 ```javascript
 // 数组循环
@@ -83,24 +105,39 @@ const eachResult = tpl.render(`
 `, {
     arr: [123, 234]
 });
+// 输出: 
+// <ul>
+//     <li>123</li>
+//     <li>234</li>
+// </ul>
 ```
 
-### 4. 视图渲染
+### 5. 视图渲染
 
 ```javascript
 // 设置全局变量
 $.globalBag.siteName = "我的网站";
 
 // 设置视图变量
-tpl.viewBag.title = "首页";
+tpl.set({
+    title: "首页",
+    keywords: "关键词"
+});
 
 // 渲染视图文件
 const html = tpl.view("./views/index.html", {
     user: { name: "张三" }
 });
+// 输出: 渲染结果 <div>Hello World</div>
+
+// 获取视图变量
+const title = tpl.get("title");
+
+// 删除视图变量
+tpl.del("keywords");
 ```
 
-### 5. 缓存机制
+### 6. 缓存机制
 
 ```javascript
 // 使用缓存渲染视图
@@ -111,11 +148,13 @@ const html = tpl.view("./views/page", {
     cache_filename: "./cache"   // 缓存文件名
 });
 
-// 清除指定目录的缓存
-tpl.clear_cache('./views/mall');
+// 清除缓存
+tpl.clearCache('./views/mall'); // 清除指定目录缓存
+// 或
+tpl.clearCache(); // 清除所有缓存
 ```
 
-### 6. 钩子系统
+### 7. 钩子系统
 
 #### 添加函数钩子
 ```javascript
@@ -126,7 +165,7 @@ $.hook.addFunc('list', async function(viewBag, req, type) {
         viewBag.user_id = query.user_id;
     }
     return someData;
-});
+}, 100, 'listFunc'); // sort: 优先级, alias: 别名
 ```
 
 #### 添加动作钩子
@@ -143,26 +182,45 @@ $.hook.addFilter('content', function(viewBag, content, param) {
 }, 1, "contentFilter");
 ```
 
-#### 在模板中使用钩子
+#### 执行钩子
 ```javascript
-// 运行函数钩子
-await tpl.runFunc('list', {
-    query: { page: 1 }
-}, 'article');
+// 执行函数钩子
+const result = await tpl.runFunc('list', { query: { page: 1 } }, 'article');
+
+// 执行动作钩子
+const actionResult = tpl.runHook('header', { param: 'value' });
+
+// 在模板中使用钩子
+const html = tpl.render(`
+    <div>
+        ${hookAction('header')}
+        ${hookFilter('content', '原始内容')}
+    </div>
+`, data);
+```
 
-// 在模板中使用动作钩子
-${hook_action('header')}
+#### 删除钩子
+```javascript
+// 删除指定钩子
+$.hook.delFunc('list', 'listFunc');
+$.hook.delAction('header', 'headerAction');
+$.hook.delFilter('content', 'contentFilter');
 
-// 在模板中使用过滤器钩子
-${hook_filter('content', '原始内容')}
+// 清空所有钩子
+$.hook.clear();
 ```
 
 ## 高级特性
 
-### 1. 主题支持
+### 1. 主题和目录支持
 ```javascript
 // 设置当前主题
 tpl.current_theme = "dark";
+
+// 模板文件查找顺序（优先级从高到低）：
+// 1. diy目录（自定义目录）
+// 2. 当前主题目录
+// 3. 默认主题目录
 ```
 
 ### 2. 模板规则
@@ -177,36 +235,80 @@ tpl.current_theme = "dark";
 ```javascript
 const html = tpl.view("./template.html", data);
 if (tpl.error) {
-    $.log.error("渲染错误:", tpl.error);
+    console.error("渲染错误:", tpl.error);
 }
 ```
 
-### 4. 视图背包操作
+### 4. 字符转义
 ```javascript
-// 设置视图变量
-tpl.set({
-    title: "页面标题",
-    keywords: "关键词"
-});
+// 自动转义特殊字符
+const escaped = tpl.escape("<div>${content}</div>");
+// 输出: <div>·$·{content}</div>
 
-// 获取视图变量
-const title = tpl.get("title");
+// 还原转义字符
+const restored = tpl.escape(escaped, true);
+// 输出: <div>${content}</div>
+```
 
-// 删除视图变量
-tpl.del("title");
-// 或批量删除
-tpl.del(["title", "keywords"]);
+### 5. 全局挂载
+```javascript
+// 自动挂载到全局对象
+if (global.$ && !$.Tpl) {
+    $.Tpl = Tpl;
+    $.tpl = new Tpl();
+}
 ```
 
+## API 参考
+
+### Tpl 类方法
+
+- `constructor(config)` - 构造函数，创建模板实例
+- `setConfig(config)` - 设置配置参数
+- `render(body, model, options)` - 渲染模板字符串
+- `compile(body, options)` - 编译模板为函数
+- `view(file, model, options)` - 渲染模板文件
+- `set(obj)` - 设置视图数据
+- `get(key)` - 获取视图数据
+- `del(keys)` - 删除视图数据
+- `clearCache(path, file)` - 清除缓存
+- `runFunc(name, req, ...args)` - 执行函数钩子
+- `runHook(name, req, ...args)` - 执行动作钩子（runFunc别名）
+- `escape(body, restore)` - 转义/还原字符
+
+### Hook 类方法
+
+- `addFunc(name, func, sort, alias)` - 添加函数钩子
+- `addAction(name, func, sort, alias)` - 添加动作钩子
+- `addFilter(name, func, sort, alias)` - 添加过滤器钩子
+- `runFunc(name, model, req, ...args)` - 执行函数钩子
+- `runAction(name, model, ...args)` - 执行动作钩子
+- `runFilter(name, model, ret, ...args)` - 执行过滤器钩子
+- `delFunc(name, alias)` - 删除函数钩子
+- `delAction(name, alias)` - 删除动作钩子
+- `delFilter(name, alias)` - 删除过滤器钩子
+- `clear(name)` - 清空钩子
+
 ## 注意事项
 
-1. 确保模板目录具有正确的读写权限
-2. 使用缓存时注意及时清理过期缓存
-3. 钩子的优先级数值越小，执行顺序越靠前
-4. 建议在生产环境开启模板缓存以提高性能
-5. 模板文件查找顺序：diy > current_theme > default_theme
-6. 使用钩子系统时注意处理异步操作
+1. **依赖要求**: 需要安装 `art-template` 和 `mm_expand` 依赖包
+2. **目录权限**: 确保模板目录具有读写权限
+3. **缓存管理**: 及时清理过期缓存，避免内存泄漏
+4. **钩子优先级**: 数值越小优先级越高，执行顺序越靠前
+5. **异步处理**: 钩子函数支持异步操作，注意错误处理
+6. **文件查找**: 模板文件按优先级顺序查找，确保文件存在
+7. **字符转义**: 自动处理模板语法字符，避免冲突
+
+## 开发
+
+```bash
+# 运行测试
+npm test
+
+# 查看代码覆盖率
+npm run coverage
+```
 
 ## 许可证
 
-MIT
+MIT License

package/cache/test.cache.html

@@ -2,28 +2,26 @@
 <html>
 	<head>
 		<meta charset="utf-8">
-		<title>超级美眉Art模板引擎</title>
+		<title>超级美眉Art模板引擎-游戏测试</title>
 	</head>
 	<body>
-		<h5>系统名称</h5>
-		<p>您真的是人才！</p>
-		<p>您真的是人才！</p>
-		<ul>
-			<li>\·$·{· value }</li>
-			<li>\·$·{· value }</li>
-		</ul>
-		<ul>
-			<li>123</li>
-			<li>234</li>
-		</ul>
-		<ul>
-			<li>\·$·{· value }</li>
-			<li>\·$·{· value }</li>
-		</ul>
-		<script type="text/javascript">
-			var a_0 =123;
-			var a_1 =234;
-		</script>系统名称计算
-		123123'priceNIHAO'#计算
+		<div>游戏主题</div>
+		<div><div class="bar_user">
+	<div>用户ID：1</div>
+	<div>当前项目ID：2</div>
+	<div>hello world！</div>
+</div>
+
+<div class="bar">导航栏</div>
+<!-- 广告位 -->
+<div class="ad"><div>
+	<p>这是一个广告位！</p>
+</div>
+</div>
+<style>
+	.bar {
+		font-weight: 800;
+	}
+</style></div>
 	</body>
 </html>