@zenweb/template 5.2.0 → 5.4.0

package/dist/index.js

@@ -36,8 +36,8 @@ function contextTemplate(template_or_option) {
 }
 function setup(option) {
     return async function template(setup) {
-        if (!option.engineName) {
-            option.engineName = option.engine.name;
+        if (!option.renderName) {
+            option.renderName = option.render.name;
         }
         setup.debug('option: %o', option);
         setup.assertModuleExists('result', '@zenweb/result');

package/dist/render.js

@@ -13,8 +13,8 @@ class TemplateRender {
         const opt = ctx.templateOption;
         if (opt) {
             // 匹配引擎
-            if (opt.engine === this._option.engineName) {
-                (0, utils_1.debug)('matchEngine: %o', this._option.engineName);
+            if (opt.render === this._option.renderName) {
+                (0, utils_1.debug)('matchRender: %o', this._option.renderName);
                 return true;
             }
             // 指定模版
@@ -49,7 +49,7 @@ class TemplateRender {
                 return true;
             }
         }
-        return false;
+        return this._option.default || false;
     }
     render(ctx, data) {
         const opt = ctx.templateOption || {};
@@ -60,13 +60,16 @@ class TemplateRender {
                 template = opt.failTemplate || this._option.failTemplate || template;
             }
         }
-        if (!template) {
-            template = ctx.path.slice(1);
+        if (!template && ctx.controller) {
+            template = `${ctx.controller.key}/${ctx.mapping.key}`;
             if (this._option.templateAffix) {
                 template += this._option.templateAffix;
             }
         }
-        return this._option.engine(template, data);
+        if (!template) {
+            throw new Error('No template specified');
+        }
+        return this._option.render(ctx, template, data);
     }
 }
 exports.TemplateRender = TemplateRender;

package/dist/types.d.ts

@@ -1,8 +1,9 @@
+import { Context } from "zenweb";
 /**
  * 渲染引擎的渲染方法
  * - 方法名作为默认的引擎名称
  */
-export type TemplateEngine = (template: string, data?: any) => any;
+export type TemplateRender = (ctx: Context, template: string, data?: any) => any;
 export interface TemplateSetupOption {
     /**
      * 输出类型
@@ -21,6 +22,12 @@ export interface TemplateSetupOption {
      * 匹配 Accept Type 头信息
      */
     matchAccept?: string[];
+    /**
+     * 默认使用
+     * - 设置为 true 的情况下在没有匹配任何规则下默认启用
+     * @default false
+     */
+    default?: boolean;
     /**
      * 模版名后缀
      * - 例如 '.html'
@@ -37,16 +44,16 @@ export interface TemplateSetupOption {
     /**
      * 渲染引擎
      */
-    engine: TemplateEngine;
+    render: TemplateRender;
     /**
      * 设置渲染引擎名称
-     * - 引擎名称默认取 `engine.name` 可以设置此项改名，可用于多模块切换
+     * - 引擎名称默认取 `render.name` 可以设置此项改名，可用于多模块切换
      */
-    engineName?: string;
+    renderName?: string;
 }
 export interface TemplateOption {
     /**
-     * 指定模版名，不指定取 `ctx.path`
+     * 指定模版名，不指定则自动根据 `控制器文件名/方法名` 生成
      */
     template?: string;
     /**
@@ -57,7 +64,7 @@ export interface TemplateOption {
     failTemplate?: string | false;
     /**
      * 使用的渲染引擎
-     * - 对应的是 `TemplateSetupOption.engineName`
+     * - 对应的是 `TemplateSetupOption.renderName`
      */
-    engine?: string;
+    render?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenweb/template",
-  "version": "5.2.0",
+  "version": "5.4.0",
   "description": "zenweb template render module",
   "exports": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -10,7 +10,6 @@
     "dev": "cd example && node --env-file=.env -r ts-node/register app.ts"
   },
   "files": [
-    "AGENTS.md",
     "dist"
   ],
   "author": {
@@ -26,6 +25,7 @@
   "homepage": "https://zenweb.node.ltd",
   "devDependencies": {
     "@types/node": "^16.18.126",
+    "@zenweb/controller": "^6.7.0",
     "@zenweb/inject": "^5.4.0",
     "@zenweb/template-handlebars": "^4.1.0",
     "@zenweb/template-nunjucks": "^4.1.0",

package/AGENTS.md

@@ -1,187 +0,0 @@
-# @zenweb/template - AI API Reference
-
-AI 专用 API 参考文档，随 npm 包发布，供 AI 编程助手使用。
-
-## 模块概述
-
-`@zenweb/template` 是 ZenWeb 框架的服务端模版渲染模块。集成模版引擎（如 Nunjucks、Handlebars）并根据请求条件（路径匹配、Accept 头、控制器显式指定）按需渲染输出。支持多个模版引擎实例共存。
-
-## 导出
-
-```ts
-export default function setup(option: TemplateSetupOption): SetupFunction;
-export { $template, TemplateSetupOption, TemplateOption, TemplateEngine };
-```
-
-## 类型
-
-```ts
-/**
- * 渲染引擎方法签名
- * - 函数名 (name) 作为默认引擎名称
- */
-type TemplateEngine = (template: string, data?: any) => any;
-
-interface TemplateSetupOption {
-  /** 输出类型，默认 'html' */
-  type?: string;
-  /** 匹配路径，例如 [/\.html$/i] */
-  matchPath?: RegExp[];
-  /** 忽略路径，例如 [/^\/api\//i] */
-  ignorePath?: RegExp[];
-  /** 匹配 Accept 头类型 */
-  matchAccept?: string[];
-  /**
-   * 模版名后缀，例如 '.html'
-   * 在不指定 TemplateOption.template 时有效
-   */
-  templateAffix?: string;
-  /**
-   * ctx.fail 操作使用的模版（全局）
-   * 不指定则使用 TemplateOption.template 值
-   * 控制器中可设置 TemplateOption.failTemplate = false 关闭
-   */
-  failTemplate?: string;
-  /** 渲染引擎 */
-  engine: TemplateEngine;
-  /**
-   * 自定义引擎名称
-   * 默认取 engine.name，多引擎共存时用于区分
-   */
-  engineName?: string;
-}
-
-interface TemplateOption {
-  /** 指定模版名，不指定取 ctx.path */
-  template?: string;
-  /**
-   * 失败模版
-   * 默认使用全局 failTemplate
-   * 设为 false 强制使用 template
-   */
-  failTemplate?: string | false;
-  /** 使用的引擎名称，对应 TemplateSetupOption.engineName */
-  engine?: string;
-}
-```
-
-## setup(option) (default export)
-
-模块安装函数，用于 `app.setup(modTemplate({ ... }))`。
-
-**处理流程：**
-1. 设置引擎名称（默认取 `option.engine.name`）
-2. 断言 `@zenweb/result` 模块已安装
-3. 创建 `TemplateRender` 实例并注册到 `RenderManager`
-4. 扩展 Context，挂载 `ctx.template()` 方法
-
-**基本用法：**
-```ts
-import { create } from 'zenweb';
-import modTemplate from '@zenweb/template';
-import nunjucks from '@zenweb/template-nunjucks';
-
-create()
-.setup(modTemplate({
-  matchPath: [/\.html$/i],
-  engine: nunjucks(),
-}))
-.start();
-```
-
-**多引擎配置：**
-```ts
-create()
-.setup(modTemplate({
-  matchPath: [/\.html$/i],
-  engine: nunjucks(),
-}))
-.setup(modTemplate({
-  type: 'xml',
-  matchAccept: ['xml'],
-  templateAffix: '.xml',
-  engine: handlebars(),
-  engineName: 'xml',
-}))
-.start();
-```
-
-## $template(template_or_option?)
-
-全局方法，在控制器或服务中使用，基于 `@zenweb/core` 的 `$getContext()` 获取当前请求上下文。
-
-```ts
-$template()                              // 启用模版渲染（使用默认匹配）
-$template('detail.html')                 // 指定模版文件
-$template({ failTemplate: 'error.html' }) // 指定失败模版
-$template({ engine: 'xml' })             // 切换引擎
-$template(false)                         // 关闭当前请求的模版渲染
-```
-
-**控制器示例：**
-```ts
-import { Context, mapping } from 'zenweb';
-import { $template } from '@zenweb/template';
-
-export class Controller {
-  @mapping({ path: '/user.html' })
-  user(ctx: Context) {
-    $template();              // 启用渲染
-    return { name: 'test' };  // 渲染 user.html 模版
-  }
-
-  @mapping({ path: '/api/data' })
-  data() {
-    $template(false);         // 禁用渲染，返回 JSON
-    return { name: 'test' };
-  }
-}
-```
-
-## Context 挂载
-
-```ts
-interface Context {
-  /** 当前请求的模版渲染选项 */
-  templateOption?: TemplateOption;
-
-  /**
-   * 启用并设置模版渲染
-   * 不传参数: 启用
-   * false: 关闭模版渲染
-   * string: 设置模版文件名
-   * TemplateOption: 详细设置
-   */
-  template(template_or_option?: false | string | TemplateOption): void;
-}
-```
-
-## 匹配规则
-
-`TemplateRender.match()` 按以下优先级判断请求是否需要模版渲染：
-
-1. **引擎名匹配** — `ctx.templateOption.engine === option.engineName` 时直接匹配
-2. **模版后缀匹配** — `ctx.templateOption.template` 以 `templateAffix` 结尾时匹配
-3. **忽略路径** — `ignorePath` 中任一正则匹配 `ctx.path` 时返回 `false`
-4. **路径匹配** — `matchPath` 中任一正则匹配 `ctx.path` 时匹配
-5. **Accept 头匹配** — `matchAccept` 包含请求 Accept 类型时匹配
-6. 以上均不满足则不匹配，回退到 JSON 渲染
-
-## 渲染流程
-
-`TemplateRender.render()` 按以下逻辑确定模版名：
-
-1. 若数据为 `ResultFail` 实例，包装为 `{ fail: data }`，并使用 `failTemplate`
-2. 模版名优先级：`opt.template` → `ctx.path.slice(1) + templateAffix`
-3. 调用 `engine(template, data)` 渲染输出
-
-## 依赖模块
-
-- `@zenweb/result` — 必须在此之前安装，提供 `RenderManager` 和 `ResultRender` 接口
-
-## 已知模版引擎适配器
-
-| 包名 | 引擎 |
-|------|------|
-| `@zenweb/template-nunjucks` | Nunjucks |
-| `@zenweb/template-handlebars` | Handlebars |