@yeihizhi/dynamic-html
v0.1.3
Published
A lightweight, framework-agnostic JSON template rendering engine with component system support
Maintainers
yeihizhiReadme
Dynamic HTML
一个基于 JSON 模板的动态 HTML 渲染引擎，支持组件化开发、响应式数据绑定、虚拟 DOM 和多种模块格式（UMD / ESM / CJS）。
✨ 功能特性
- JSON 模板渲染 — 通过 JSON 配置定义页面结构，编译为虚拟 DOM 并渲染真实 DOM
- 组件系统 — 可复用组件，支持 props 传递、插槽机制和完整生命周期
- 响应式数据绑定 — 基于 Proxy 的响应式系统，数据变化自动同步到 DOM
- 虚拟 DOM — 自定义 vNode 实现，高效的 DOM 差异更新
- 事件总线 — 发布-订阅模式，全局单例或独立实例
- 异步请求队列 — 带并发控制和重试机制的 HTTP 请求队列
- HTML 转模板 — HtmlToTemplate 工具，将 HTML 字符串转为模板 JSON
- 多格式构建 — 支持 UMD（浏览器直接引用）、ESM、CommonJS
📦 安装
npm
npm install @yeihizhi/dynamic-htmlCDN / 纯 HTML
<script src="https://unpkg.com/@yeihizhi/dynamic-html/dist/main.umd.js"></script>🚀 快速开始
纯 HTML 使用（零依赖）
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>DynamicHtml 示例</title>
</head>
<body>
<div id="container" data-template="/templates/my-page.json"></div>
<script src="index.umd.js"></script>
<script>
document.addEventListener('DOMContentLoaded', function() {
var container = document.getElementById('container');
var src = container.getAttribute('data-template');
var template = new DynamicHtml.templateComplie(src);
template.render();
});
</script>
</body>
</html>ES Module
import { templateComplie, EVENT_MANAGEMENT } from '@yeihizhi/dynamic-html';
// 方式一：传入 JSON 对象
const template = new templateComplie({
el: "div",
type: "dom",
renderType: "append",
conf: { attrs: { id: "app" } },
childs: [
{ el: "span", type: "dom", conf: { attrs: {}, innerText: "Hello World" } }
]
});
template.render();
// 方式二：传入远程模板路径
const template2 = new templateComplie('/templates/my-page.json');
// 监听渲染完成
EVENT_MANAGEMENT.on('render_success', () => {
console.log('渲染完成');
});CommonJS
const { templateComplie, HtmlToTemplate } = require('@yeihizhi/dynamic-html');🎨 可视化模板编辑器
项目提供了一套所见即所得的模板编辑器，无需手写 JSON 即可搭建复杂页面。
# 启动开发服务器后访问
npm run dev
# 编辑器：http://localhost:5173/editor/ （editorPlugin 挂载）
# 编辑器集成示例：http://localhost:5173/example/editor.html
# 模板渲染示例：http://localhost:5173/example/其他项目接入：安装 npm 包后在 vite.config.js 中加入 editorPlugin() 一行接入，访问 /editor/；或直接复制 src/etl/（npm 包内为 dist/editor/）目录。详见 可视化模板编辑器使用与集成指南。
| 功能 | 说明 | |------|------| | 拖拽面板 | 布局 / 基础 / 表单 / 特殊 50+ 控件，含 Grid、Flex、图片背景、Cover 等 | | 表单控件 | Form / Input（16 种类型）/ Textarea / Select 等 25+ 表单控件，Checkbox / Radio 选项组一键生成 | | 画布渲染 | 实时显示 flex/grid/absolute CSS 布局效果 | | 属性搜索 | 120+ CSS 属性 + 50+ DOM 属性，输入关键字搜索，枚举值下拉选择 | | 图层树 | 左侧图层面板，hover 联动画布高亮，点击选中节点 | | 图片浮动 | absolute 满铺图片 + 文字/按钮叠加层 | | 导出模板 | 一键导出 JSON / CSS / JS，兼容 templateComplie 编译器 |
布局模式
| 控件 | 效果 |
|------|------|
| 🖼 图片背景 | div 设 background-image:cover，子元素浮动在图上 |
| CSS 定位 | 父 position:relative，img position:absolute 铺满，文字 position:absolute 叠加 |
| ⊞ Grid | 网格布局，属性面板预设 2×2 / 3×3 / 侧边栏等 |
| ⊟ Flex | 弹性布局，支持 row/column 方向切换 |
| Cover | position 定位 + img 满铺 + overlay 浮层 |
🤖 AI 助手
编辑器内置 AI 对话面板，通过自然语言描述自动生成页面布局。
# 1. 复制 .env.example 为 .env，填入 LLM API 配置
cp .env.example .env
# 编辑 .env：
# VITE_AI_TARGET=https://api.openai.com/v1
# VITE_AI_KEY=sk-your-key
# 2. 启动开发服务器
npm run dev| 功能 | 说明 |
|------|------|
| 对话生成 | 描述想要的布局，AI 直接生成树状 JSON（el / conf / childs）并渲染 |
| 渐进搭建 | 先建 nav → 再建 hero → 逐步完善，不会丢失已有内容 |
| 树状 JSON 输出 | 一次生成整页 DOM 树，支持 clear 清空重建 |
| 服务端配置 | API Key 放在 .env 服务端，浏览器不暴露密钥 |
| 模型选择 | 自动从 API 获取可用模型列表，下拉切换 |
使用方式：右侧面板「AI助手」tab → 选模型 → 输入描述 → 发送。
示例描述：「生成腾讯首页布局：nav(flex白底,Logo,6链接), Hero(flex column居中,蓝渐变,h1科技向善,副标题,2按钮), 新闻(grid 1.5fr+1fr), Footer(grid 4列深色)」
📖 模板 JSON 结构
{
"el": "div",
"type": "dom",
"renderType": "append",
"conf": {
"attrs": { "class": "container", "id": "app" },
"style": { "padding": "20px", "color": "#333" },
"event": {},
"onload": [],
"inject": [],
"innerText": "",
"innerHtml": ""
},
"childs": [
{
"el": "h1",
"type": "dom",
"renderType": "append",
"conf": {
"attrs": {},
"style": {},
"event": {},
"onload": [],
"inject": [],
"innerText": "标题",
"innerHtml": ""
}
},
{
"el": "style",
"type": "inline",
"conf": { "code": "#app { font-family: sans-serif; }" }
},
{
"el": "script",
"type": "inline",
"conf": { "code": "console.log('页面已渲染');" }
},
{
"el": "script",
"type": "external",
"conf": [
{ "src": "/assets/js/app.js" },
{ "src": "/assets/js/module.js", "type": "module" }
]
}
]
}📚 API 参考
templateComplie
模板编译器，JSON 模板 → 虚拟 DOM → 真实 DOM。
const template = new templateComplie(templateTxt);templateTxt：Object（JSON 对象，同步渲染）或string（远程 URL，异步加载）
| 方法 | 说明 |
|------|------|
| render() | 编译并渲染到 DOM |
| getvNodes() | 返回虚拟节点数组（不渲染） |
| checkNode(node) | 检查/补全节点必需字段 |
| component(name, definition) | 全局注册组件（静态方法） |
vNode
虚拟 DOM 节点类，表示 DOM 树中的一个节点。
import { vNode } from '@yeihizhi/dynamic-html';
const node = new vNode('div', 'dom', 'append', { attrs: { class: 'box' } });| 方法 | 说明 |
|------|------|
| appendChild(node) | 添加子节点 |
| dom_element() | 获取关联的真实 DOM 元素 |
| render() | 渲染节点及子节点 |
reactive
响应式数据类，基于 Proxy 实现。
const state = new reactive({ count: 0 }, { id: node.id, el: node.el });
state.count = 1; // 自动更新 DOM| 方法 | 说明 |
|------|------|
| addDep(k, func) | 添加依赖回调 |
| notify(prop) | 通知更新 |
| getBindDom(id) | 获取绑定的 DOM 元素 |
ComponentInstance / ComponentRegistry
组件系统，支持生命周期钩子。
import { ComponentInstance, ComponentRegistry } from '@yeihizhi/dynamic-html';
templateComplie.component('my-modal', {
props: ['title', 'content'],
template: { el: 'div', type: 'dom', conf: { attrs: { class: 'modal' } }, childs: [] },
data: { visible: false },
methods: { toggle() { this.visible = !this.visible; } },
lifecycle: {
created() { console.log('组件已创建'); },
mounted() { console.log('组件已挂载'); }
}
});生命周期钩子：beforeCreate → created → beforeMount → mounted → beforeUpdate → updated → beforeDestroy → destroyed
event / EVENT_MANAGEMENT
发布-订阅事件总线。
import { event, EVENT_MANAGEMENT } from '@yeihizhi/dynamic-html';
// 全局单例
EVENT_MANAGEMENT.on('customEvent', (data) => console.log(data));
EVENT_MANAGEMENT.emit('customEvent', { key: 'value' });
// 独立实例
const bus = new event();
bus.on('myEvent', (msg) => console.log(msg));FetchQueue
带并发控制和重试的 HTTP 请求队列。
import { FetchQueue } from '@yeihizhi/dynamic-html';
const queue = new FetchQueue({ maxConcurrency: 5, timeout: 10000, retryCount: 3 });
queue.add(
{ url: '/api/data' },
(data) => console.log('成功:', data),
(err) => console.error('失败:', err)
);HtmlToTemplate
HTML 字符串转模板 JSON 工具。
import { HtmlToTemplate } from '@yeihizhi/dynamic-html';
const converter = new HtmlToTemplate();
const result = converter.convert('<div class="box"><h1>标题</h1><button onclick="handleClick()">点击</button></div>');
console.log(result.json); // 模板 JSON 对象
console.log(result.css); // CSS 资源路径数组
console.log(result.js); // JS 资源路径数组📁 项目结构
├── src/
│ ├── lib/
│ │ ├── index.js # 库入口，导出所有模块
│ │ └── core/
│ │ ├── el_compile.js # 模板编译器
│ │ ├── el_vNode.js # 虚拟 DOM + 响应式系统
│ │ ├── component.js # 组件系统
│ │ ├── event.js # 事件总线
│ │ ├── fetch.js # 请求队列
│ │ └── html_to_template.js # HTML 转模板 JSON
│ ├── etl/ # 可视化模板编辑器（构建时复制到 dist/editor）
│ │ ├── editor.html # 编辑器页面
│ │ ├── css/editor.css # 编辑器样式
│ │ └── js/ # 编辑器逻辑 + 属性字典
│ └── editor-plugin.js # 编辑器 Vite 插件（一行接入）
├── example/ # 示例项目（不发布到 npm）
│ ├── index.html # 模板渲染示例页
│ ├── editor.html # 编辑器集成示例（iframe 嵌入 /editor/）
│ ├── main.js # 示例渲染入口
│ └── public/ # 示例静态资源
│ ├── templates/ # 示例模板 JSON（apple-cn 等）
│ └── assets/ # 示例资源（CSS/JS/图片）
├── dist/ # 构建产物（库 main.* + 编辑器 editor/，npm 发布）
├── unitTest/ # 单元测试
├── docs/ # 使用文档
│ ├── editor-usage.md # 可视化编辑器使用与集成指南
│ ├── html-usage.md # 纯 HTML 环境使用方法
│ ├── nodejs-usage.md # Node.js 环境使用方法
│ ├── template-spec.md # 模板 JSON 规范
│ └── vue-react-usage.md # Vue/React 环境使用方法
├── vite.config.js # 构建配置
└── package.json🛠 开发
# 安装依赖
npm install
# 启动开发服务器
npm run dev
# 构建库（UMD / ESM / CJS）
npm run build
# 运行测试
npm run test