vv-template-html

轻量级的 HTML 模板加载与渲染库（TemplateHTML）。

特性

• 全局单例：TemplateHTML
• 按需加载并缓存模板（.html）
• 简单的渲染 API：getTemplate / render
• 支持多种 baseUrl 格式
• 提供 TypeScript 类型定义

快速开始

在页面中引入构建产物：

<script src="template-html.min.js"></script>
<!-- 或使用 CDN 引入 -->
<script src="https://cdn.jsdelivr.net/npm/vv-template-html@latest/template-html.min.js"></script>
<script src="https://unpkg.com/vv-template-html@latest/template-html.min.js"></script>
<script>
  (async function () {
    console.log(TemplateHTML.VERSION);
    TemplateHTML.baseUrl = "/template/"; // 可选
    await TemplateHTML.render("main", {}, document.body, (main) => {
      console.log(main);
    });
  })();
</script>

示例文件：index.html

API 概览

• TemplateHTML.VERSION: string（只读）
• TemplateHTML.AUTHOR: string（只读）
• TemplateHTML.baseUrl: string（可读写，支持多种格式）
• TemplateHTML.templates: { [key: string]: HTMLElement }（只读缓存）
• TemplateHTML.getTemplate(templateName: string, params: object): Promise<HTMLElement>
• TemplateHTML.customProtocol(protocol: string): void
• TemplateHTML.render(templateName: string, params: object, element: HTMLElement, callback?: (element: HTMLElement) => void): Promise<void>

自定义错误类：TemplateHTMLError（继承自 Error）

baseUrl 支持格式

• file:// 协议路径
• 以 /、./、../ 开头的相对路径（会基于 location.origin 解析）
• http:// 或 https:// 完整 URL

设置示例：

TemplateHTML.baseUrl = "file:///C:/templates/";
TemplateHTML.baseUrl = "/template/";
TemplateHTML.baseUrl = "https://cdn.example.com/templates/";
TemplateHTML.baseUrl = "template://";

错误处理

• 无效模板名、无法加载、模板空等情况会抛出 TemplateHTMLError，请在调用处捕获处理。

TypeScript

项目包含类型定义文件 template-html.d.ts，在 TypeScript 项目中可直接使用全局 TemplateHTML 和 TemplateHTMLError 类型。

贡献与许可

• 作者：IFTC
• 许可证：MIT

欢迎提交 issue 或 PR 以改进功能或修复 Bug。