mm_tpl 2.7.1 → 2.7.2

package/lib/engine.js

@@ -0,0 +1,1256 @@
+const engine = require('art-template');
+const {
+  Base
+} = require('mm_expand');
+const Hook = require('./hook.js');
+const {
+  nativeRule,
+  artRule,
+  htmlRule,
+  jsRule,
+  pyRule,
+  pyRule2
+} = require('./tpl_rule.js');
+const {
+  TplUtil
+} = require('./util.js');
+const {
+  Template
+} = require('./template.js');
+const {
+  Css
+} = require('./css.js');
+const {
+  Js
+} = require('./js.js');
+const {
+  Lang
+} = require('./lang.js');
+const {
+  Memory
+} = require('./memory.js');
+
+/**
+ * 模板引擎类
+ * 单个引擎实例的渲染封装，负责渲染以及主题、风格、语言的编排
+ * 渲染结果不做页面级缓存，页面缓存交由 web 中间件按完整请求上下文负责
+ * @class
+ */
+class Engine extends Base {
+  /**
+   * 配置参数
+   */
+  static config = {
+    /**
+     * 应用根目录，目录结构见 doc/目录结构.md
+     */
+    root: $.run_path + '',
+    /**
+     * 主题目录，相对应用根目录
+     */
+    theme_dir: './static/template/',
+    /**
+     * 风格目录，相对主题目录
+     */
+    style_dir: './style/',
+    /**
+     * 组件目录，相对主题目录，存放可被功能页面复用的公共片段
+     * 为空则不启用组件，模板内 $component 将取不到文件
+     */
+    component_dir: './component/',
+    /**
+     * 用户自定义覆盖目录，相对应用根目录，优先级最高
+     */
+    diy_dir: './static/diy/',
+    /**
+     * 应用级语言包目录，相对应用根目录，按文件名识别语言，为空则不启用文件语言包
+     */
+    lang_dir: './static/lang/',
+    /**
+     * 主题级语言包目录，相对主题目录，覆盖应用级语言包的相同词条
+     */
+    theme_lang_dir: './lang/',
+    /**
+     * 应用级脚本目录，相对应用根目录，存放各主题共用的公共脚本
+     */
+    js_dir: './static/js/',
+    /**
+     * 主题级脚本目录，相对主题目录，覆盖应用级脚本目录的同名脚本
+     * 脚本不按风格分层：风格是视觉变体，脚本不因颜色明暗而变
+     */
+    theme_js_dir: './js/',
+    /**
+     * 默认主题
+     */
+    default_theme: 'default',
+    /**
+     * 默认风格，为主题内的变体
+     */
+    default_style: 'light',
+    /**
+     * 基础风格目录名，作为各风格共享的公共样式层
+     * 仅作用于样式：优先级低于当前风格、高于默认主题，公共样式放此处即可被各风格复用；为空则不启用
+     */
+    base_style: 'base',
+    /**
+     * 默认语言，语言代码统一用小写下划线，与语言包文件名一致
+     */
+    default_lang: 'zh_cn',
+    /**
+     * 共享语言包字典，优先级高于语言包文件
+     */
+    langs: {},
+    /**
+     * 用户偏好存储，留空则用进程内存的 Memory
+     * 通过 user_id 映射用户的风格与语言，需实现 getUser / setUser / delUser / hasUser / listUsers / clear
+     * 六个同步方法，便于替换为文件、数据库或缓存服务；派生实例会复用同一存储
+     */
+    user_store: null,
+    /**
+     * 模板文件扩展名，可自行设定，如 .html、.art
+     */
+    extname: '.html',
+    /**
+     * 模板规则
+     */
+    rules: [nativeRule, artRule, htmlRule, jsRule, pyRule, pyRule2],
+    /**
+     * 复数规则，键为语言代码，语言代码统一用小写下划线（如 zh_cn、en_us）
+     * mm_expand 的 Lang 已内置 zh_cn、en 规则，其他语言代码需在此登记才能按语言取复数形式
+     */
+    plural_rules: {
+      'en_us': function (count) {
+        return count === 1 ? 0 : 1;
+      }
+    },
+    /**
+     * 变换字符串
+     */
+    change_str: ['\\#', '\\<', '\\${', '\\*', '\\"""'],
+  };
+  /**
+   * 语言包文件缓存
+   * 按语言包目录组缓存，形如 {目录组: {fingerprint, dict}}，文件未变化时复用解析结果
+   */
+  static lang_cache = {};
+  /**
+   * 创建引擎实例
+   * @param {Object} config - 配置选项
+   */
+  constructor(config) {
+    super(config);
+
+    /**
+     * 模板引擎
+     */
+    this.engine = engine;
+
+    /**
+     * 视图数据
+     */
+    this.viewBag = {};
+
+    /**
+     * 模板根目录，即应用根目录
+     */
+    this.dir = this.config.root;
+
+    /**
+     * 当前主题
+     */
+    this.current_theme = this.config.default_theme;
+
+    /**
+     * 当前风格
+     */
+    this.current_style = this.config.default_style;
+
+    /**
+     * 当前语言实例
+     */
+    this.lang = null;
+
+    /**
+     * 错误提示
+     */
+    this.error = null;
+
+    /**
+     * 字符转义规则
+     */
+    this.escape_rule = TplUtil.buildEscapeRule(this.config.change_str);
+
+    /**
+     * 模板文件加载器
+     */
+    this.template = new Template(this);
+
+    /**
+     * 样式文件加载器
+     */
+    this.css = new Css(this);
+
+    /**
+     * 脚本文件加载器
+     */
+    this.js = new Js(this);
+
+    /**
+     * 语言包加载器
+     */
+    this.lang_loader = new Lang(this);
+
+    /**
+     * 用户偏好存储
+     */
+    this.store = null;
+
+    /**
+     * 初始化用户偏好存储
+     */
+    this.setStore(this.config.user_store);
+
+    /**
+     * 实例级模板函数表，由 setFunc 注册，渲染时注入模型
+     */
+    this.funcs = {};
+
+    /**
+     * 实例级钩子，仅作用于当前实例；与全局 $.hook 一起参与执行，全局先执行、实例级后执行
+     */
+    this.hook = new Hook();
+
+    /**
+     * 初始化
+     */
+    this._init();
+  }
+}
+
+/**
+ * 初始化模板
+ */
+Engine.prototype._initTpl = function () {
+  var cg = this.config;
+  // 引擎默认值为全局配置，仅主实例写入，避免多实例互相覆盖
+  if (!cg.is_fork) {
+    for (var key in cg) {
+      this.engine.defaults[key] = cg[key];
+    }
+  }
+};
+
+/**
+ * 设置配置参数
+ * 支持 config.js 的 { defaults: { theme, style, lang } } 写法
+ * @param {Object} config - 配置参数
+ */
+Engine.prototype._setConfig = function (config) {
+  if (!config) {
+    return;
+  }
+  Object.assign(this.config, this._normalizeConfig(config));
+};
+
+/**
+ * 规范化配置
+ * 将 defaults 展开为 default_* 配置项，并移除 defaults，避免派生实例重复展开
+ * 显式传入的 default_* 配置优先于 defaults
+ * @param {Object} config - 配置参数
+ * @returns {Object} 规范化后的配置
+ */
+Engine.prototype._normalizeConfig = function (config) {
+  if (!config || typeof (config.defaults) !== 'object' || !config.defaults) {
+    return config;
+  }
+  var d = config.defaults;
+  var cg = Object.assign({}, config);
+  if (cg.default_theme === undefined && d.theme !== undefined) {
+    cg.default_theme = d.theme;
+  }
+  if (cg.default_style === undefined && d.style !== undefined) {
+    cg.default_style = d.style;
+  }
+  if (cg.default_lang === undefined && d.lang !== undefined) {
+    cg.default_lang = d.lang;
+  }
+  delete cg.defaults;
+  return cg;
+};
+
+/**
+ * 获取主题根目录
+ * @param {string} theme - 主题名称
+ * @returns {string} 主题根目录全路径
+ */
+Engine.prototype.getThemeDir = function (theme) {
+  var cg = this.config;
+  return theme.fullname(cg.theme_dir.fullname(this.dir));
+};
+
+/**
+ * 获取风格目录
+ * @param {string} theme - 主题名称
+ * @param {string} style - 风格名称，为空时取主题下的风格目录本身
+ * @returns {string} 风格目录全路径
+ */
+Engine.prototype.getStyleDir = function (theme, style) {
+  var dir = this.config.style_dir.fullname(this.getThemeDir(theme));
+  if (!style) {
+    return dir;
+  }
+  return style.fullname(dir);
+};
+
+/**
+ * 获取模板目录列表
+ * 优先级从高到低：自定义覆盖目录、当前主题、默认主题
+ * 模板按功能划分目录，直接放主题目录下（如 static/template/{主题}/article/list.html）
+ * 模板不按风格分层：风格是视觉变体，只影响样式，不改变模板结构
+ * @param {string} theme - 主题名称，不传时取当前主题
+ * @returns {Array<string>} 模板目录列表
+ */
+Engine.prototype.getTemplateDirs = function (theme) {
+  var cg = this.config;
+  var cur_theme = theme || this.current_theme;
+  var dirs = [];
+  if (cg.diy_dir) {
+    dirs.push(cg.diy_dir.fullname(this.dir));
+  }
+  if (cur_theme) {
+    dirs.push(this.getThemeDir(cur_theme));
+  }
+  if (cg.default_theme && cg.default_theme !== cur_theme) {
+    dirs.push(this.getThemeDir(cg.default_theme));
+  }
+  return dirs;
+};
+
+/**
+ * 获取组件目录列表
+ * 优先级从高到低：自定义覆盖目录下的组件目录、当前主题组件目录、默认主题组件目录
+ * 与模板链同构，只是每级都多一个固定的组件子目录前缀
+ * @param {string} theme - 主题名称，不传时取当前主题
+ * @returns {Array<string>} 组件目录列表
+ */
+Engine.prototype.getComponentDirs = function (theme) {
+  var cg = this.config;
+  if (!cg.component_dir) {
+    return [];
+  }
+  var cur_theme = theme || this.current_theme;
+  var dirs = [];
+  if (cg.diy_dir) {
+    dirs.push(cg.component_dir.fullname(cg.diy_dir.fullname(this.dir)));
+  }
+  if (cur_theme) {
+    dirs.push(cg.component_dir.fullname(this.getThemeDir(cur_theme)));
+  }
+  if (cg.default_theme && cg.default_theme !== cur_theme) {
+    dirs.push(cg.component_dir.fullname(this.getThemeDir(cg.default_theme)));
+  }
+  return dirs;
+};
+
+/**
+ * 获取样式目录列表
+ * 优先级从高到低：自定义覆盖目录、（当前主题、默认主题）各自按「当前风格、基础风格」两级展开
+ * 即：diy → 当前主题+当前风格 → 当前主题+基础风格 → 默认主题+当前风格 → 默认主题+基础风格
+ * 样式按风格分层，因此比模板多了风格与基础风格两级；只回退主题，不回退风格
+ * @param {string} theme - 主题名称，不传时取当前主题
+ * @param {string} style - 风格名称，不传时取当前风格；显式传空字符串表示用主题下的风格目录本身
+ * @returns {Array<string>} 样式目录列表
+ */
+Engine.prototype.getStyleDirs = function (theme, style) {
+  var cg = this.config;
+  var cur_theme = theme || this.current_theme;
+  // 风格取自入参或当前值，为空时以默认风格兜底，不做跨风格回退
+  var cur_style = (style === undefined || style === null) ? (this.current_style || cg.default_style || '') : style;
+  var themes = [];
+  if (cur_theme) {
+    themes.push(cur_theme);
+  }
+  if (cg.default_theme && cg.default_theme !== cur_theme) {
+    themes.push(cg.default_theme);
+  }
+  // 基础风格作为公共层，与当前风格重合时无需重复
+  var base = cg.base_style || '';
+  var dirs = [];
+  if (cg.diy_dir) {
+    dirs.push(cg.diy_dir.fullname(this.dir));
+  }
+  for (var i = 0; i < themes.length; i++) {
+    dirs.push(this.getStyleDir(themes[i], cur_style));
+    if (base && base !== cur_style) {
+      dirs.push(this.getStyleDir(themes[i], base));
+    }
+  }
+  return dirs;
+};
+
+/**
+ * 获取脚本目录列表
+ * 优先级从高到低：自定义覆盖目录、当前主题、默认主题、应用级
+ * 脚本不按风格分层，因此没有风格与基础风格两级
+ * @param {string} theme - 主题名称，不传时取当前主题
+ * @returns {Array<string>} 脚本目录列表
+ */
+Engine.prototype.getJsDirs = function (theme) {
+  var cg = this.config;
+  var cur_theme = theme || this.current_theme;
+  var dirs = [];
+  if (cg.diy_dir) {
+    dirs.push(cg.diy_dir.fullname(this.dir));
+  }
+  if (cur_theme && cg.theme_js_dir) {
+    dirs.push(cg.theme_js_dir.fullname(this.getThemeDir(cur_theme)));
+  }
+  if (cg.default_theme && cg.default_theme !== cur_theme && cg.theme_js_dir) {
+    dirs.push(cg.theme_js_dir.fullname(this.getThemeDir(cg.default_theme)));
+  }
+  if (cg.js_dir) {
+    dirs.push(cg.js_dir.fullname(this.dir));
+  }
+  return dirs;
+};
+
+/**
+ * 预设值
+ * @param {boolean} force - 是否跳过语言包缓存强制重新加载
+ */
+Engine.prototype._preset = function (force) {
+  // 基类构造期间会触发一次预设，此时加载器尚未就绪
+  if (!this.lang_loader) {
+    return;
+  }
+  this.lang = this.lang_loader.create(this.config, force);
+};
+
+/**
+ * 获取当前语言
+ * @returns {string} 语言代码
+ */
+Engine.prototype.getLang = function () {
+  if (this.lang) {
+    return this.lang.now;
+  }
+  return this.config.default_lang;
+};
+
+/**
+ * 设置当前语言
+ * @param {string} lang - 语言代码
+ * @returns {string} 设置后的语言代码
+ */
+Engine.prototype.setLang = function (lang) {
+  if (typeof (lang) !== 'string' || !lang) {
+    this.log('warn', '语言参数无效，保持当前语言：' + this.getLang());
+    return this.getLang();
+  }
+  return this.lang.setLang(lang);
+};
+
+/**
+ * 获取翻译文本
+ * 与模板中的 $t 等价，供服务端代码取词
+ * 参数为单个对象时按 {name} 命名占位符替换，否则按 {0}、{1} 位置占位符替换
+ * @param {string} key - 词条键名，支持 a.b 形式的层级键
+ * @param {...any} args - 替换参数，对象按命名占位符，其余按位置占位符
+ * @returns {string} 翻译后的文本
+ */
+Engine.prototype.t = function (key, ...args) {
+  return this._translate(key, args);
+};
+
+/**
+ * 翻译词条
+ * @param {string} key - 词条键名
+ * @param {Array<any>} args - 替换参数
+ * @returns {string} 翻译后的文本
+ */
+Engine.prototype._translate = function (key, args) {
+  var val = this.lang.get(key);
+  if (typeof (val) !== 'string' || !args.length) {
+    return val;
+  }
+  var first = args[0];
+  // 参数为普通对象时按命名占位符替换，可读性优于位置参数
+  if (first && typeof (first) === 'object' && !Array.isArray(first)) {
+    return this._fillNamed(val, first);
+  }
+  return this.lang.get(key, ...args);
+};
+
+/**
+ * 按命名占位符填充文本
+ * 值为空时保留占位符原样，便于发现漏配的词条
+ * @param {string} text - 原始文本
+ * @param {Object} data - 键值对
+ * @returns {string} 填充后的文本
+ */
+Engine.prototype._fillNamed = function (text, data) {
+  for (var key in data) {
+    var val = data[key];
+    if (val === undefined || val === null) {
+      continue;
+    }
+    // 键名来自调用方，转义后构造正则，避免特殊字符影响匹配
+    var rx = new RegExp('\\{' + key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\}', 'g');
+    text = text.replace(rx, val);
+  }
+  return text;
+};
+
+/**
+ * 获取带复数形式的翻译文本
+ * @param {string} key - 词条键名，支持 a.b 形式的层级键
+ * @param {number} count - 数量，用于确定复数形式
+ * @param {...any} args - 额外替换参数，依次替换 {1}、{2} 等占位符
+ * @returns {string} 翻译后的文本
+ */
+Engine.prototype.tc = function (key, count, ...args) {
+  return this.lang.tc(key, count, ...args);
+};
+
+/**
+ * 获取支持的语言列表
+ * 过滤掉无词条的语言，Lang 内置的 zh_cn、en 空字典不计入
+ * @returns {Array<string>} 语言代码数组
+ */
+Engine.prototype.getLangs = function () {
+  if (!this.lang) {
+    return [];
+  }
+  var langs = this.lang.getLangs();
+  var list = [];
+  for (var i = 0; i < langs.length; i++) {
+    var dict = this.lang.config[langs[i]];
+    if (dict && Object.keys(dict).length) {
+      list.push(langs[i]);
+    }
+  }
+  return list;
+};
+
+/**
+ * 重新加载全部语言包
+ * 语言包文件新增或修改后调用，重建语言包并保持当前语言
+ * 默认按文件指纹判断是否需要重新读取，force 为 true 时强制读取
+ * @param {boolean} force - 是否跳过缓存强制重新读取语言包文件
+ * @returns {Array<string>} 重新加载后的语言列表
+ */
+Engine.prototype.reloadLangs = function (force) {
+  var lang = this.getLang();
+  this._preset(force);
+  this.setLang(lang);
+  return this.getLangs();
+};
+
+/**
+ * 重新加载指定语言的语言包
+ * @param {string} lang - 语言代码
+ * @returns {Object|null} 语言包对象，不存在时返回null
+ */
+Engine.prototype.loadLang = function (lang) {
+  if (typeof (lang) !== 'string' || !lang) {
+    this.log('warn', '语言参数无效：' + lang);
+    return null;
+  }
+  this.reloadLangs();
+  var dict = this.lang ? this.lang.config[lang] : null;
+  if (!dict) {
+    this.log('warn', '语言包不存在：' + lang);
+    return null;
+  }
+  return dict;
+};
+
+/**
+ * 设置用户偏好存储
+ * 传入对象需实现 getUser / setUser / delUser / hasUser / listUsers / clear 六个同步方法
+ * 留空或接口不完整时回退为内置内存存储（Memory）
+ * @param {Object} store - 存储对象
+ * @returns {Engine} 当前实例
+ */
+Engine.prototype.setStore = function (store) {
+  if (!store || !this._isStore(store)) {
+    if (store) {
+      this.log('warn', 'user_store 接口不完整，回退为内置内存存储');
+    }
+    this.store = new Memory();
+    return this;
+  }
+  this.store = store;
+  return this;
+};
+
+/**
+ * 获取用户偏好存储
+ * 派生实例复用该对象即可共享同一份用户偏好
+ * @returns {Object} 存储对象
+ */
+Engine.prototype.getStore = function () {
+  return this.store;
+};
+
+/**
+ * 判断是否为可用的用户偏好存储
+ * @param {Object} store - 存储对象
+ * @returns {boolean} 六个同步方法是否齐备
+ */
+Engine.prototype._isStore = function (store) {
+  var methods = ['getUser', 'setUser', 'delUser', 'hasUser', 'listUsers', 'clear'];
+  for (var i = 0; i < methods.length; i++) {
+    if (typeof (store[methods[i]]) !== 'function') {
+      return false;
+    }
+  }
+  return true;
+};
+
+/**
+ * 规范化用户偏好
+ * 只保留 style 与 lang 两个字段，其余字段不写入存储
+ * @param {Object} prefs - 用户偏好，形如 { style, lang }
+ * @returns {Object} 规范化后的偏好
+ */
+Engine.prototype._prefs = function (prefs) {
+  if (!prefs || typeof (prefs) !== 'object') {
+    throw new TypeError('用户偏好必须是对象');
+  }
+  var obj = {};
+  if (prefs.style !== undefined) {
+    if (typeof (prefs.style) !== 'string') {
+      throw new TypeError('风格必须是字符串');
+    }
+    obj.style = prefs.style;
+  }
+  if (prefs.lang !== undefined) {
+    if (typeof (prefs.lang) !== 'string') {
+      throw new TypeError('语言必须是字符串');
+    }
+    obj.lang = prefs.lang;
+  }
+  return obj;
+};
+
+/**
+ * 写入用户偏好
+ * 通过 user_id 映射用户的风格与语言，同一用户重复写入时按字段合并
+ * @param {string|number} user_id - 用户标识
+ * @param {Object} prefs - 用户偏好，形如 { style, lang }，只取这两个字段
+ * @returns {Object} 保存后的用户偏好
+ */
+Engine.prototype.setUser = function (user_id, prefs) {
+  return this.store.setUser(user_id, this._prefs(prefs));
+};
+
+/**
+ * 获取用户偏好
+ * @param {string|number} user_id - 用户标识
+ * @returns {Object|null} 用户偏好，未登记时返回 null
+ */
+Engine.prototype.getUser = function (user_id) {
+  return this.store.getUser(user_id);
+};
+
+/**
+ * 删除用户偏好
+ * @param {string|number} user_id - 用户标识
+ * @returns {boolean} 是否删除成功
+ */
+Engine.prototype.removeUser = function (user_id) {
+  return this.store.delUser(user_id);
+};
+
+/**
+ * 获取已登记的用户标识列表
+ * @returns {Array<string>} 用户标识数组
+ */
+Engine.prototype.getUsers = function () {
+  return this.store.listUsers();
+};
+
+/**
+ * 获取用户的渲染参数
+ * 已登记的用户取其映射的风格与语言，未登记的用户回退到当前实例的风格与语言
+ * 结果可直接传给 view / render，实现单实例按用户渲染
+ * @param {string|number} user_id - 用户标识
+ * @param {Object} options - 其他渲染参数，可省略
+ * @returns {Object} 渲染参数，含 style 与 lang
+ */
+Engine.prototype.userOptions = function (user_id, options) {
+  var opt = Object.assign({}, options);
+  var record = this.store.getUser(user_id);
+  opt.style = (record && record.style !== undefined) ? record.style : this.current_style;
+  opt.lang = (record && record.lang !== undefined) ? record.lang : this.getLang();
+  return opt;
+};
+
+/**
+ * 执行函数钩子
+ * 全局钩子与实例级钩子都执行，实例级排在后面且返回值优先
+ * @param {string} name - 钩子名称
+ * @param {Object} req - 请求参数
+ * @param {...any} args - 附加参数
+ * @returns {Promise<any>} 执行结果
+ */
+Engine.prototype.runFunc = async function (name, req, ...args) {
+  var ret = await $.hook.runFunc(name, this.viewBag, req, ...args);
+  var ret_inst = await this.hook.runFunc(name, this.viewBag, req, ...args);
+  return ret_inst || ret;
+};
+
+/**
+ * 执行函数钩子
+ * @param {string} name - 钩子名称
+ * @param {Object} req - 请求参数
+ * @param {...any} args - 附加参数
+ * @returns {Promise<any>} 执行结果
+ */
+Engine.prototype.runHook = Engine.prototype.runFunc;
+
+/**
+ * 初始化前处理
+ * @param {Object} config - 配置参数
+ */
+Engine.prototype._initBefore = function (config) { };
+
+/**
+ * 初始化主处理
+ * @param {Object} config - 配置参数
+ */
+Engine.prototype._initMain = function (config) {
+  this.setConfig(config);
+  this._initTpl();
+};
+
+/**
+ * 初始化后处理
+ * 构建字符转义规则，供渲染前后转义与还原使用
+ * @param {Object} config - 配置参数
+ */
+Engine.prototype._initAfter = function (config) {
+  this.escape_rule = TplUtil.buildEscapeRule(this.config.change_str);
+};
+
+/**
+ * 初始化模板
+ * @param {Object} config - 配置参数
+ */
+Engine.prototype._init = function (config) {
+  this._initBefore(config);
+  this._initMain(config);
+  this._initAfter(config);
+};
+
+/**
+ * 获取当前主题
+ * @returns {string} 主题名称
+ */
+Engine.prototype.getTheme = function () {
+  return this.current_theme;
+};
+
+/**
+ * 设置当前主题
+ * 主题为部署级配置，正常运行中不应由用户切换
+ * 主题变更后会重新加载语言包，使主题级语言包生效
+ * @param {string} theme - 主题名称
+ * @param {boolean} force - 是否跳过目录校验
+ * @returns {string} 设置后的主题名称
+ */
+Engine.prototype.setTheme = function (theme, force) {
+  if (typeof (theme) !== 'string' || !theme) {
+    this.log('warn', '主题参数无效，保持当前主题：' + this.current_theme);
+    return this.current_theme;
+  }
+  if (!force && !this.template.hasTheme(theme)) {
+    this.log('warn', '主题目录不存在，保持当前主题：' + theme);
+    return this.current_theme;
+  }
+  if (theme === this.current_theme) {
+    return this.current_theme;
+  }
+  this.current_theme = theme;
+  // 主题级语言包随主题变化，重新加载语言包并保持当前语言
+  this.reloadLangs();
+  return this.current_theme;
+};
+
+/**
+ * 获取当前风格
+ * @returns {string} 风格名称，未设置时返回空字符串
+ */
+Engine.prototype.getStyle = function () {
+  return this.current_style;
+};
+
+/**
+ * 设置当前风格
+ * @param {string} style - 风格名称，空字符串表示不启用风格
+ * @param {boolean} force - 是否跳过目录校验
+ * @returns {string} 设置后的风格名称
+ */
+Engine.prototype.setStyle = function (style, force) {
+  if (typeof (style) !== 'string') {
+    this.log('warn', '风格参数无效，保持当前风格：' + this.current_style);
+    return this.current_style;
+  }
+  if (style && !force && !this.template.hasStyle(style)) {
+    this.log('warn', '风格目录不存在，保持当前风格：' + style);
+    return this.current_style;
+  }
+  this.current_style = style;
+  return this.current_style;
+};
+
+/**
+ * 转义字符
+ * @param {string} body 字符串
+ * @param {boolean} restore 是否还原转义字符
+ * @returns {string} 转义后的字符串
+ */
+Engine.prototype.escape = function (body, restore) {
+  return TplUtil.escape(body, this.escape_rule, restore);
+};
+
+/**
+ * 注入全局函数前处理
+ * @param {Object} m - 模型对象
+ * @returns {Object} 处理后的模型
+ */
+Engine.prototype._loadFuncBefore = function (m) {
+  // m.$i18n = function(key) {
+  //   return $.i18n(key);
+  // }
+  return m;
+};
+
+/**
+ * 加载函数到模型
+ * @param {Object} m 模型对象
+ * @returns {Object} 处理后的模型
+ */
+Engine.prototype.loadFunc = function (m) {
+  this._loadFuncBefore(m);
+  var _this = this;
+  m.view = function (file, model, options) {
+    return _this.view(file, Object.assign({}, m, model), options);
+  };
+  m.render = function (body, model, options) {
+    return _this.render(body, Object.assign({}, m, model), options);
+  };
+  // 同时提供 $ 前缀别名，避免与用户 model 中的同名字段冲突
+  m.$view = m.view;
+  m.$render = m.render;
+  m.component = function (name, model, options) {
+    return _this.component(name, Object.assign({}, m, model), options);
+  };
+  m.$component = m.component;
+  m.$css = function (name, theme, style) {
+    return _this.getCssFile(name, theme, style);
+  };
+  m.$js = function (name, theme) {
+    return _this.getJsFile(name, theme);
+  };
+  m.hookAction = function (name, ...args) {
+    // 全局动作钩子先输出，实例级动作钩子后输出
+    return $.hook.runAction(name, m, ...args) + _this.hook.runAction(name, m, ...args);
+  };
+  m.hookFilter = function (name, content, ...args) {
+    if (!content) {
+      content = '';
+    }
+    var ret = $.hook.runFilter(name, m, content, ...args);
+    return _this.hook.runFilter(name, m, ret, ...args);
+  };
+  if (this.lang) {
+    m.$t = function (key, ...args) {
+      return _this.t(key, ...args);
+    };
+  }
+  // 合并已注册的模板函数，内置函数与本次 model 中的同名字段优先
+  for (var key in this.funcs) {
+    if (m[key] === undefined) {
+      m[key] = this.funcs[key];
+    }
+  }
+  return m;
+};
+
+/**
+ * 设置模板函数
+ * 注册后每次渲染都注入模型，供模板内直接调用，如 ${$markdown(text)}
+ * 内置函数与本次 model 中的同名字段优先，注册的函数无法覆盖内置函数
+ * @param {string} name - 函数名，建议以 $ 开头以避免与 model 字段冲突
+ * @param {Function} func - 函数
+ * @returns {boolean} 是否设置成功
+ */
+Engine.prototype.setFunc = function (name, func) {
+  if (typeof (name) !== 'string' || !name) {
+    this.log('warn', '模板函数名无效：' + name);
+    return false;
+  }
+  if (typeof (func) !== 'function') {
+    this.log('warn', '模板函数必须是函数：' + name);
+    return false;
+  }
+  this.funcs[name] = func;
+  return true;
+};
+
+/**
+ * 删除模板函数
+ * @param {string} name - 函数名
+ * @returns {boolean} 是否存在并删除成功
+ */
+Engine.prototype.removeFunc = function (name) {
+  if (this.funcs[name] === undefined) {
+    return false;
+  }
+  delete this.funcs[name];
+  return true;
+};
+
+/**
+ * 获取模板函数表
+ * @returns {Object} 模板函数表
+ */
+Engine.prototype.getFuncs = function () {
+  return this.funcs;
+};
+
+/**
+ * 渲染主处理
+ * @param {string} body - 模板内容
+ * @param {Object} model - 数据模型
+ * @param {Object} options - 配置参数
+ * @returns {string} 渲染结果
+ */
+Engine.prototype._renderMain = function (body, model, options) {
+  var ret = '';
+  if (body) {
+    var m = Object.assign({}, {
+      viewBag: this.viewBag,
+      globalBag: $.globalBag
+    }, model);
+    this.loadFunc(m);
+    ret = this.engine.render(body, m, options);
+  }
+  return ret;
+};
+
+/**
+ * 套用本次渲染的临时选项
+ * options.style 与 options.lang 只对当前这次渲染生效，由 _restoreTempOptions 恢复
+ * 适用于单实例按传参渲染不同组合，无需为每个组合派生实例
+ * @param {Object} options - 渲染参数
+ * @returns {Object|null} 原风格与原语言，未涉及临时选项时返回 null
+ */
+Engine.prototype._applyTempOptions = function (options) {
+  if (!options) {
+    return null;
+  }
+  var has_style = options.style !== undefined;
+  var has_lang = typeof (options.lang) === 'string' && options.lang !== '';
+  if (!has_style && !has_lang) {
+    return null;
+  }
+  var prev = {
+    style: this.current_style,
+    lang: this.getLang()
+  };
+  if (has_style) {
+    this.current_style = typeof (options.style) === 'string' ? options.style : '';
+  }
+  if (has_lang && this.lang) {
+    this.lang.setLang(options.lang);
+  }
+  return prev;
+};
+
+/**
+ * 恢复临时选项
+ * @param {Object|null} prev - _applyTempOptions 返回的原值
+ */
+Engine.prototype._restoreTempOptions = function (prev) {
+  if (!prev) {
+    return;
+  }
+  this.current_style = prev.style;
+  if (this.lang) {
+    this.lang.now = prev.lang;
+  }
+};
+
+/**
+ * 渲染模板
+ * options.style 与 options.lang 仅对本次渲染生效，渲染结束后自动恢复
+ * @param {string} body - 模板内容
+ * @param {Object} model - 数据模型
+ * @param {Object} options - 配置参数
+ * @returns {string} 渲染结果
+ */
+Engine.prototype.render = function (body, model, options) {
+  var prev = this._applyTempOptions(options);
+  try {
+    body = this.escape(body);
+    body = this._renderMain(body, model, options);
+    return this.escape(body, true);
+  } finally {
+    this._restoreTempOptions(prev);
+  }
+};
+
+/**
+ * 编译模板
+ * @param {string} body - 模板内容
+ * @param {Object} options - 配置参数
+ * @returns {Function} 渲染函数
+ */
+Engine.prototype.compile = function (body, options) {
+  return this.engine.compile(body, options);
+};
+
+/**
+ * 获取模板文件
+ * @param {string} file - 模板文件路径
+ * @param {Object} options - 配置参数，dir 为指定的查找目录
+ * @returns {string} 模板文件路径
+ */
+Engine.prototype.getFile = function (file, options) {
+  return this.template.getFile(file, options);
+};
+
+/**
+ * 获取样式文件路径列表
+ * 按目录优先级收集各级目录下的全部 css，同名文件只保留优先级最高的一份
+ * 结果按优先级升序排列：基础风格在前打底，当前风格与自定义目录在后覆盖
+ * @returns {Array<string>} 样式文件全路径列表
+ */
+Engine.prototype.getCssFiles = function () {
+  return this.css.getFiles();
+};
+
+/**
+ * 匹配样式文件
+ * 与 getCssFile 传入通配符等价，语义更明确
+ * @param {string} pattern - 样式文件名通配符，如 *.css、blue*，为空时等同于 *.css
+ * @param {string} theme - 主题名称，不传时取当前主题
+ * @param {string} style - 风格名称，不传时取当前风格
+ * @returns {Array<string>} 命中的样式文件全路径列表，顺序即引用顺序
+ */
+Engine.prototype.matchCssFiles = function (pattern, theme, style) {
+  return this.css.matchFiles(pattern, theme, style);
+};
+
+/**
+ * 获取样式文件路径
+ * 按目录优先级查找，名称支持 * 通配，用于模板中引用样式
+ * 含通配符时返回命中的全部路径数组，否则返回第一个命中的路径
+ * @param {string} name - 样式文件名或通配符，如 main.css、*.css、blue*
+ * @param {string} theme - 主题名称，不传时取当前主题
+ * @param {string} style - 风格名称，不传时取当前风格
+ * @returns {string|Array<string>|null} 样式文件全路径；无通配符且不存在时返回 null
+ */
+Engine.prototype.getCssFile = function (name, theme, style) {
+  if (!name || typeof (name) !== 'string') {
+    return null;
+  }
+  var list = this.css.matchFiles(name, theme, style);
+  // 通配符用于批量引用，单名用于精确引用
+  if (name.indexOf('*') !== -1) {
+    return list;
+  }
+  return list.length ? list[0] : null;
+};
+
+/**
+ * 按通配符匹配脚本文件
+ * @param {string} pattern - 脚本文件名通配符，如 *.js、app*，为空时等同于 *.js
+ * @param {string} theme - 主题名称，不传时取当前主题
+ * @returns {Array<string>} 命中的脚本文件全路径列表，顺序即执行顺序
+ */
+Engine.prototype.matchJsFiles = function (pattern, theme) {
+  return this.js.matchFiles(pattern, theme);
+};
+
+/**
+ * 获取全部脚本文件路径列表
+ * 按目录优先级收集各级目录下的全部 js，同名文件只保留优先级最高的一份
+ * 结果按优先级升序排列：应用级公共脚本在前，主题脚本与自定义目录在后
+ * @returns {Array<string>} 脚本文件全路径列表
+ */
+Engine.prototype.getJsFiles = function () {
+  return this.js.getFiles();
+};
+
+/**
+ * 获取脚本文件路径
+ * 按目录优先级查找，名称支持 * 通配，用于模板中引用脚本
+ * 含通配符时返回命中的全部路径数组，否则返回第一个命中的路径
+ * @param {string} name - 脚本文件名或通配符，如 app.js、*.js、app*
+ * @param {string} theme - 主题名称，不传时取当前主题
+ * @returns {string|Array<string>|null} 脚本文件全路径；无通配符且不存在时返回 null
+ */
+Engine.prototype.getJsFile = function (name, theme) {
+  if (!name || typeof (name) !== 'string') {
+    return null;
+  }
+  var list = this.js.matchFiles(name, theme);
+  // 通配符用于批量引用，单名用于精确引用
+  if (name.indexOf('*') !== -1) {
+    return list;
+  }
+  return list.length ? list[0] : null;
+};
+
+/**
+ * 获取组件文件
+ * @param {string} name - 组件名称，如 bar、article/card
+ * @param {Object} options - 配置参数，dir 为指定的查找目录
+ * @returns {string} 组件文件路径
+ */
+Engine.prototype.getComponentFile = function (name, options) {
+  return this.template.getComponent(name, options);
+};
+
+/**
+ * 渲染组件
+ * 组件沿组件目录链查找：static/diy/component → 当前主题/component → 默认主题/component
+ * 组件名相对组件目录解析，不带 ./component/ 前缀，省略扩展名时自动补全
+ * @param {string} name - 组件名称，如 bar、article/card
+ * @param {Object} model - 数据模型
+ * @param {Object} options - 配置参数
+ * @returns {string} 渲染结果
+ */
+Engine.prototype.component = function (name, model, options) {
+  var dirs = this.getComponentDirs();
+  if (!dirs.length) {
+    this.error = {
+      code: 10001,
+      message: '组件目录未启用！'
+    };
+    return '';
+  }
+  var f = this.getComponentFile(name, options);
+  if (!f.hasFile()) {
+    this.error = {
+      code: 10000,
+      message: f + '组件不存在！'
+    };
+    return '';
+  }
+  var body = f.loadText();
+  if (!body) {
+    return '';
+  }
+  body = this.escape(body);
+  body = this._renderMain(body, model, options);
+  return this.escape(body, true);
+};
+
+/**
+ * 渲染模板文件
+ * options.style 与 options.lang 仅对本次渲染生效，渲染结束后自动恢复
+ * options.dir 指定时只在该目录查找模板
+ * @param {string} file - 模板文件路径
+ * @param {Object} model - 数据模型
+ * @param {Object} options - 配置参数
+ * @returns {string} 渲染结果
+ */
+Engine.prototype.view = function (file, model, options) {
+  var prev = this._applyTempOptions(options);
+  try {
+    var f = this.getFile(file, options);
+    if (!f.hasFile()) {
+      this.error = {
+        code: 10000,
+        message: f + '文件不存在！'
+      };
+    }
+    else {
+      var body = f.loadText();
+      if (body) {
+        body = this.escape(body);
+        body = this._renderMain(body, model, options);
+        body = this.escape(body, true);
+        return body;
+      }
+    }
+    return '';
+  } finally {
+    this._restoreTempOptions(prev);
+  }
+};
+
+/**
+ * 设置视图数据
+ * @param {Object} obj - 要设置的数据对象
+ */
+Engine.prototype.set = function (obj) {
+  $.push(this.viewBag, obj, true);
+};
+
+/**
+ * 删除视图数据
+ * @param {Array|string} keys - 要删除的键或键数组
+ */
+Engine.prototype.del = function (keys) {
+  if (typeof (keys) == 'string') {
+    delete this.viewBag[keys];
+  } else {
+    keys.map(function (k) {
+      delete this.viewBag[k];
+    });
+  }
+};
+
+/**
+ * 获取视图数据
+ * @param {string} key - 数据键名
+ * @returns {any} 数据值
+ */
+Engine.prototype.get = function (key) {
+  return this.viewBag[key];
+};
+
+/**
+ * 派生引擎实例
+ * 复用当前实例的配置，主题、风格、语言、视图数据各自独立
+ * 派生实例不登记到任何列表，由调用方自行管理
+ * @param {Object} config - 派生配置
+ * @param {string} config.theme - 主题名称
+ * @param {string} config.style - 风格名称
+ * @param {string} config.lang - 语言代码
+ * @returns {Engine} 派生出的引擎实例
+ */
+Engine.prototype.fork = function (config) {
+  var cg = config || {};
+  var lang = (cg.lang && this.lang.isSupported(cg.lang)) ? cg.lang : this.getLang();
+  var cfg = Object.assign({}, this.config, {
+    is_fork: true,
+    default_theme: this.current_theme,
+    default_style: this.current_style,
+    default_lang: lang,
+    // 用户偏好属于用户而非实例，派生实例复用同一份存储
+    user_store: this.getStore()
+  });
+  var tpl = new Engine(cfg);
+  tpl.dir = this.dir;
+  if (cg.theme) {
+    tpl.setTheme(cg.theme);
+  }
+  if (cg.style) {
+    tpl.setStyle(cg.style);
+  }
+  $.push(tpl.viewBag, this.viewBag, true);
+  // 模板函数属于站点级扩展，派生实例继承同一份
+  tpl.funcs = Object.assign({}, this.funcs);
+  return tpl;
+};
+
+module.exports = {
+  Engine
+};