mm_tpl 2.4.5 → 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 = 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
 // 数组循环
@@ -90,23 +112,32 @@ const eachResult = tpl.render(`
 // </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
 // 使用缓存渲染视图
@@ -117,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
@@ -132,7 +165,7 @@ $.hook.addFunc('list', async function(viewBag, req, type) {
         viewBag.user_id = query.user_id;
     }
     return someData;
-});
+}, 100, 'listFunc'); // sort: 优先级, alias: 别名
 ```
 
 #### 添加动作钩子
@@ -149,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. 模板规则
@@ -183,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,29 +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>123</li>
-			<li>234</li>
-		</ul>
-		<strong>hello world！</strong>
-		<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>

package/hook.js

@@ -55,7 +55,7 @@ Hook.prototype._getName = function (func, alias) {
  * @param {string} alias - 函数别名
  * @returns {string} 函数别名
  */
-Hook.prototype.addFunc = function (name, func, sort, alias) {
+Hook.prototype.addFunc = function (name, func, sort = 100, alias = "") {
 	alias = this._getName(func, alias);
 	var obj = {
 		func,
@@ -185,14 +185,16 @@ Hook.prototype.delFilter = function (name, alias = "") {
 Hook.prototype.runFunc = async function (name, model, req, ...args) {
 	var ret;
 	var list = this._func[name];
-	if (!list) {
-		var len = list.length;
-		for (var i = 0; i < len; i++) {
+	if (list) {
+		for (var i = 0; i < list.length; i++) {
 			var item = list[i];
 			try {
-				ret = item.func(model, req, ...args);
-				if (ret) {
-					ret = await ret;
+				var ret_new = item.func(model, req, ...args);
+				if (types.isPromise(ret_new)) {
+					ret_new = await ret_new;
+					if (ret_new) {
+						ret = ret_new;
+					}
 				}
 			} catch (err) {
 				$.log.error(`[${this.constructor.name}] 执行函数钩子失败 ${item.alias}`, err);
@@ -235,9 +237,8 @@ Hook.prototype.runAction = function (name, model, ...args) {
  */
 Hook.prototype.runFilter = function (name, model, ret, ...args) {
 	var list = this._filter[name];
-	if (!list) {
-		var len = list.length;
-		for (var i = 0; i < len; i++) {
+	if (list) {
+		for (var i = 0; i < list.length; i++) {
 			var item = list[i];
 			try {
 				ret = item.func(model, ret, ...args) || ret;

package/index.js

@@ -346,17 +346,17 @@ Tpl.prototype.view = function (file, model, options) {
 	if (file.replace('./', '').indexOf('.') === -1 && !file.endsWith(this.config.extname)) {
 		file += this.config.extname;
 	}
-	var f = file.fullname(this.dir + 'diy');
+	var f = file.fullname('diy'.fullname(this.dir));
 	if (!f.hasFile()) {
-		f = file.fullname(this.config.default_dir + 'diy');
+		f = file.fullname('diy'.fullname(this.config.default_dir));
 		if (!f.hasFile()) {
-			f = file.fullname(this.dir + this.current_theme);
+			f = file.fullname(this.current_theme.fullname(this.dir));
 			if (!f.hasFile()) {
-				f = file.fullname(this.dir + this.config.default_theme);
+				f = file.fullname(this.config.default_theme.fullname(this.dir));
 				if (!f.hasFile()) {
-					f = file.fullname(this.config.default_dir + this.current_theme);
+					f = file.fullname(this.current_theme.fullname(this.config.default_dir));
 					if (!f.hasFile()) {
-						f = file.fullname(this.config.default_dir + this.config.default_theme);
+						f = file.fullname(this.config.default_theme.fullname(this.config.default_dir));
 					}
 				}
 			}
@@ -369,15 +369,16 @@ Tpl.prototype.view = function (file, model, options) {
 			message: f + "文件不存在！"
 		}
 	}
-	var body = f.loadText();
-	if (body) {
-		body = this.escape(body);
-		body = this._renderSub(body, model, options);
-		body = this.escape(body, true);
-		return body;
-	} else {
-		return "";
+	else {
+		var body = f.loadText();
+		if (body) {
+			body = this.escape(body);
+			body = this._renderSub(body, model, options);
+			body = this.escape(body, true);
+			return body;
+		}
 	}
+	return "";
 };
 
 /**
@@ -431,7 +432,7 @@ Tpl.prototype.clearCache = function (path, file) {
 	});
 };
 
-if (global.$ && !global.$.Tpl) {
+if (global.$ && !$.Tpl) {
 	$.Tpl = Tpl;
 	$.tpl = new Tpl();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mm_tpl",
-    "version": "2.4.5",
+    "version": "2.4.6",
     "description": "这是超级美眉模板帮助类模块，用于MVC模式下的视图渲染",
     "main": "index.js",
     "scripts": {

package/template/diy/ad.html

@@ -1,39 +1,3 @@
-<!DOCTYPE html>
-<html>
-	<head>
-		<meta charset="utf-8">
-		<title>${globalBag.name}</title>
-	</head>
-	<body>
-		<h5>${viewBag.name}</h5>
-		<p>${@hookFilter('test', '你真的是人才！')}</p>
-		<p><!--{@hookFilter('test', '你真的是人才！', {key: '123'})}--></p>
-		<ul>
-			${loop arr value idx}
-			<li>\${ value }</li>
-			${/loop}
-		</ul>
-		<ul>
-			<!--[ for(var i = 0; i < arr.length; i++) { ]-->
-			<li>${ arr[i] }</li>
-			<!--[ } ]-->
-		</ul>
-		<ul>
-			<!--{loop arr value idx}-->
-			<li>${ value }</li>
-			<!--{/loop}-->
-		</ul>
-		<strong>${message}</strong>
-		<script type="text/javascript">
-			/*[loop arr value idx]*/
-			var a_${idx} = ${value};
-			/*[/loop]*/
-		</script>
-		${viewBag.name}
-		## "计算" ##
-		123123'"""#
-		"price" + "NIHAO"
-		#"""'
-		## "#计算" ##
-	</body>
-</html>
+<div>
+	<p>这是一个广告位！</p>
+</div>

package/template/game/bar.html

@@ -1,11 +1,15 @@
 <div class="bar_user">
-	${@hookFilter('test', hook_action('test', '好的'), '真的')}
+	${@hookFilter('test', hookAction('test', '好的'), '真的')}
 	<div>用户ID：${viewBag.user_id}</div>
 	<div>当前项目ID：${viewBag.project_id}</div>
 	<div>${message}</div>
 </div>
 
 <div class="bar">导航栏</div>
+<!-- 广告位 -->
+<div class="ad">
+	${@view('./ad')}
+</div>
 <style>
 	.bar {
 		font-weight: 800;

package/template/game/test.html

@@ -2,7 +2,7 @@
 <html>
 	<head>
 		<meta charset="utf-8">
-		<title>${globalBag.name}</title>
+		<title>${globalBag.name}-游戏测试</title>
 	</head>
 	<body>
 		<div>游戏主题</div>

package/test.js

@@ -5,7 +5,7 @@ const {Tpl} = require('./index.js');
  * 演示简单的变量替换功能
  * @async
  */
-async function test() {
+async function test1() {
 	var tpl = new Tpl();
 	var body = tpl.render("<a>${test} + 123123</a>", {
 		test: 123
@@ -18,7 +18,7 @@ async function test() {
  * 演示模板中的循环功能
  * @async
  */
-async function test() {
+async function test2() {
 	var tpl = new Tpl();
 	// 数组循环示例
 	// var body = tpl.render("<a>${loop arr value idx} ${idx} ${ value } ${/loop} + 123123</a>", { arr: [123,234] });
@@ -42,8 +42,7 @@ async function test() {
  * 演示全局变量和视图渲染的使用
  * @async
  */
-async function test() {
-	$.log.debug("测试开始")
+async function test3() {
 	var tpl = new Tpl();
 	// 设置全局变量
 	$.globalBag.name = "超级美眉Art模板引擎";
@@ -62,7 +61,7 @@ async function test() {
  * 演示带有动作和过滤器的钩子系统
  * @async
  */
-async function test() {
+async function test4() {
 	var tpl = new Tpl();
 
 	// 设置全局变量
@@ -75,7 +74,6 @@ async function test() {
 
 	// 添加列表函数钩子
 	$.hook.addFunc('list', async function(m, req, type) {
-		console.log("参数", m, req, type);
 		var query = req.query;
 		if (query.user_id) {
 			m.user_id = query.user_id;
@@ -115,7 +113,7 @@ async function test() {
 	}, 'article');
 
 	// 使用缓存渲染视图
-	var body = tpl.view("./ad", {
+	var body = tpl.view("./test", {
 		arr: [123, 234],
 		message: "hello world！"
 	}, {
@@ -130,4 +128,16 @@ async function test() {
 }
 
 // 执行测试
-test();
+async function demo() {
+	$.log.debug("测试开始");
+	$.log.debug("测试1");
+	await test1();
+	$.log.debug("测试2");
+	await test2();
+	$.log.debug("测试3");
+	await test3();
+	$.log.debug("测试4");
+	await test4();
+}
+
+demo();

package/template/defualt/test.html

@@ -1,36 +0,0 @@
-<!DOCTYPE html>
-<html>
-	<head>
-		<meta charset="utf-8">
-		<title>${globalBag.name}</title>
-	</head>
-	<body>
-		<h5>${viewBag.name}</h5>
-		<ul>
-			${loop arr value idx}
-			<li>${ value }</li>
-			${/loop}
-		</ul>
-		<ul>
-			<!--[ for(var i = 0; i < arr.length; i++) { ]-->
-			<li>${ arr[i] }</li>
-			<!--[ } ]-->
-		</ul>
-		<ul>
-			<!--{loop arr value idx}-->
-			<li>${ value }</li>
-			<!--{/loop}-->
-		</ul>
-		<script type="text/javascript">
-			/*[loop arr value idx]*/
-			var a_${idx} = ${value};
-			/*[/loop]*/
-		</script>
-		${viewBag.name}
-		## "计算" ##
-		123123'"""#
-		"price" + "NIHAO"
-		#"""'
-		## "#计算" ##
-	</body>
-</html>