mm_tpl

超级美眉模板引擎模块，基于art-template模板引擎，提供强大的MVC模式视图渲染功能，支持钩子系统、主题切换和缓存机制。

English Documentation | 中文文档

目录

• 特性
• 安装
• 快速开始
• 高级特性
• API 参考
• 注意事项
• 开发
• 许可证

特性

• 🚀 基于art-template高性能模板引擎
• 🔧 支持多种模板语法规则
• 🎨 主题切换和模板文件优先级搜索
• ⚡ 内置缓存机制提升性能
• 🔌 强大的钩子系统支持
• 📁 灵活的目录结构支持
• 🛡️ 完善的错误处理机制

安装

npm install mm_tpl

快速开始

1. 安装依赖

npm install mm_tpl

2. 初始化模板引擎

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', // 缓存文件扩展名
    rules: [nativeRule, artRule, htmlRule, jsRule, pyRule, pyRule2] // 模板规则
});

3. 基础模板渲染

// 简单变量替换
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>

4. 循环渲染

// 数组循环
const arrayResult = tpl.render(`
    <ul>
        ${loop arr value idx}
            <li>${idx}: ${value}</li>
        ${/loop}
    </ul>
`, { 
    arr: [123, 234] 
});

// 对象循环
const objectResult = tpl.render(`
    <dl>
        ${loop obj value key}
            <dt>${key}</dt>
            <dd>${value}</dd>
        ${/loop}
    </dl>
`, { 
    obj: { name: "张三", age: 25 } 
});

// 传统for循环
const forResult = tpl.render(`
    <ul>
        <!--[ for(var i = 0; i < arr.length; i++){ ]-->
            <li>${arr[i]}</li>
        <!--[ } ]-->
    </ul>
`, {
    arr: [123, 234]
});

// each循环
const eachResult = tpl.render(`
    <ul>
        ${each arr}
            <li>${$value}</li>
        ${/each}
    </ul>
`, {
    arr: [123, 234]
});
// 输出: 
// <ul>
//     <li>123</li>
//     <li>234</li>
// </ul>

5. 视图渲染

// 设置全局变量
$.globalBag.siteName = "我的网站";

// 设置视图变量
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");

6. 缓存机制

// 使用缓存渲染视图
const html = tpl.view("./views/page", {
    data: someData
}, {
    cache: true,                // 是否使用缓存
    cache_filename: "./cache"   // 缓存文件名
});

// 清除缓存
tpl.clearCache('./views/mall'); // 清除指定目录缓存
// 或
tpl.clearCache(); // 清除所有缓存

7. 钩子系统

添加函数钩子

$.hook.addFunc('list', async function(viewBag, req, type) {
    // 处理列表逻辑
    var query = req.query;
    if (query.user_id) {
        viewBag.user_id = query.user_id;
    }
    return someData;
}, 100, 'listFunc'); // sort: 优先级, alias: 别名

添加动作钩子

$.hook.addAction('header', function(viewBag, param) {
    return "<header>网站头部</header>";
}, 1, "headerAction");

添加过滤器钩子

$.hook.addFilter('content', function(viewBag, content, param) {
    return content.replace("旧文本", "新文本");
}, 1, "contentFilter");

执行钩子

// 执行函数钩子
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.delFunc('list', 'listFunc');
$.hook.delAction('header', 'headerAction');
$.hook.delFilter('content', 'contentFilter');

// 清空所有钩子
$.hook.clear();

高级特性

1. 主题和目录支持

// 设置当前主题
tpl.current_theme = "dark";

// 模板文件查找顺序（优先级从高到低）：
// 1. diy目录（自定义目录）
// 2. 当前主题目录
// 3. 默认主题目录

2. 模板规则

模块内置支持多种模板规则，包括：

• nativeRule: 原生语法规则
• artRule: art-template语法规则
• htmlRule: HTML注释语法规则
• jsRule: JavaScript语法规则
• pyRule: Python风格语法规则

3. 错误处理

const html = tpl.view("./template.html", data);
if (tpl.error) {
    console.error("渲染错误:", tpl.error);
}

4. 字符转义

// 自动转义特殊字符
const escaped = tpl.escape("<div>${content}</div>");
// 输出: <div>·$·{content}</div>

// 还原转义字符
const restored = tpl.escape(escaped, true);
// 输出: <div>${content}</div>

5. 全局挂载

// 自动挂载到全局对象
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. 依赖要求: 需要安装 art-template 和 mm_expand 依赖包
2. 目录权限: 确保模板目录具有读写权限
3. 缓存管理: 及时清理过期缓存，避免内存泄漏
4. 钩子优先级: 数值越小优先级越高，执行顺序越靠前
5. 异步处理: 钩子函数支持异步操作，注意错误处理
6. 文件查找: 模板文件按优先级顺序查找，确保文件存在
7. 字符转义: 自动处理模板语法字符，避免冲突

开发

# 运行测试
npm test

# 查看代码覆盖率
npm run coverage

许可证

MIT License