xiangjsoncraft 1.2.0 → 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +388 -238
- package/bin/create.js +222 -0
- package/dist/xiangjsoncraft.umd.js +1 -82
- package/package.json +48 -25
- package/rollup.config.js +21 -0
- package/src/renderJson.js +111 -0
- package/template/config.json +234 -0
- package/template/index.html +53 -0
- package/config.json +0 -113
- package/renderJson.js +0 -133
package/README.md
CHANGED
|
@@ -1,61 +1,229 @@
|
|
|
1
|
-
# XiangJsonCraft
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
1
|
+
# XiangJsonCraft 2.0.0
|
|
2
|
+
|
|
3
|
+
**Write JSON, Get a Website.** | 零CSS、零JS、纯JSON驱动的轻量前端框架
|
|
4
|
+
|
|
5
|
+
一款从「JSON渲染工具」升级而来的完整前端微框架，无需编写任何CSS、JS代码，仅通过编辑JSON配置文件，即可快速构建美观、响应式、带交互的完整网页，大幅降低前端开发门槛，非前端开发者也能轻松上手。
|
|
6
|
+
|
|
7
|
+
## 📢 重大升级说明（从 1.x → 2.0.0）
|
|
8
|
+
|
|
9
|
+
XiangJsonCraft 2.0.0 是一次 **不兼容的重大版本升级** —— 从简单的「JSON渲染工具函数」，正式升级为「完整前端框架 + 官方脚手架」，保留1.x核心优势并全面强化，彻底改变使用方式、提升产品定位。
|
|
10
|
+
|
|
11
|
+
### 🔄 新旧版本核心差异
|
|
12
|
+
|
|
13
|
+
| 对比维度 | 1.x 版本（工具） | 2.0.0 版本（框架） |
|
|
14
|
+
| -------- | ----------------------------------- | ---------------------------------------------- |
|
|
15
|
+
| 产品定位 | JSON渲染工具函数 | 纯JSON驱动前端框架 |
|
|
16
|
+
| 使用方式 | 手动创建HTML/JS，引入工具包调用函数 | 脚手架一键创建完整项目，仅改JSON |
|
|
17
|
+
| 核心能力 | 基础JSON样式+内容渲染 | 样式+内容+交互+响应式+脚手架全支持 |
|
|
18
|
+
| 依赖管理 | 需手动引入、手动管理依赖 | 脚手架自动安装、自动引入，无需手动操作 |
|
|
19
|
+
| 项目结构 | 无固定结构，需手动搭建 | 标准化项目结构，自动生成所有必要文件 |
|
|
20
|
+
| 兼容性 | 仅支持模块化引入 | 兼容模块化/非模块化环境，适配所有现代浏览器 |
|
|
21
|
+
| 可维护性 | 需手动维护HTML/JS与JSON的关联 | HTML仅存骨架，所有配置集中在JSON，维护成本极低 |
|
|
22
|
+
### ✅ 保留的1.x核心功能（全部继承并优化）
|
|
23
|
+
|
|
24
|
+
- JSON与HTML解耦：HTML仅负责DOM骨架，样式、内容完全由JSON控制
|
|
25
|
+
|
|
26
|
+
- CSS属性驼峰转短横线：支持驼峰命名（如boxSizing），自动转换为CSS标准写法（box-sizing）
|
|
27
|
+
|
|
28
|
+
- 强容错性：过滤无效配置、空属性、不存在的选择器，单个错误不影响整体渲染
|
|
29
|
+
|
|
30
|
+
- 内容渲染支持：同时支持纯文本渲染（防XSS）和HTML片段渲染，满足复杂内容需求
|
|
31
|
+
|
|
32
|
+
- CSS全兼容：支持所有合法CSS选择器（类、ID、全局*）、伪类、属性，无额外学习成本
|
|
33
|
+
|
|
34
|
+
- 轻量无依赖：核心代码仅百行级，打包后体积极小，不占用多余项目资源
|
|
35
|
+
|
|
36
|
+
### 🔥 2.0.0 新增核心功能（框架级升级）
|
|
37
|
+
|
|
38
|
+
- 官方脚手架：支持 `npm create xiangjsoncraft@latest` 一键创建项目，零手动配置
|
|
39
|
+
|
|
40
|
+
- 多模板支持：内置「基础模板」「完整模板」「空模板」，适配不同使用场景（快速上手/复杂开发/自定义搭建）
|
|
41
|
+
|
|
42
|
+
- 交互能力强化：支持在JSON中直接配置JS原生事件（如onclick），无需编写额外JS即可实现简单交互
|
|
43
|
+
|
|
44
|
+
- 响应式优化：内置响应式示例配置，支持@media媒体查询，一键适配移动端/PC端
|
|
45
|
+
|
|
46
|
+
- 标准化项目结构：自动生成index.html、config.json、package.json、README.md，规范开发流程
|
|
47
|
+
|
|
48
|
+
- 自动依赖管理：脚手架自动安装框架依赖，自动完成框架引入，无需手动下载、引入文件
|
|
49
|
+
|
|
50
|
+
- 友好控制台日志：区分信息、成功、错误日志，清晰提示配置加载状态、渲染结果和问题原因，便于排查
|
|
51
|
+
|
|
52
|
+
- 全局变量暴露：兼容非模块化环境，CDN引入可直接全局调用，适配更多部署场景
|
|
53
|
+
|
|
54
|
+
- 部署简化：无需打包，直接上传项目文件即可上线，降低部署门槛
|
|
55
|
+
|
|
56
|
+
- 样式注入优化：样式块自动插入到head最前面，避免被其他样式覆盖，提升渲染稳定性
|
|
57
|
+
|
|
58
|
+
## 🚀 快速开始（2.0.0 唯一使用方式）
|
|
59
|
+
|
|
60
|
+
2.0.0 彻底废弃1.x的「手动引入工具包」用法，统一为脚手架一键创建，步骤极简：
|
|
61
|
+
|
|
62
|
+
### 方式1：使用 npm create（推荐）
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
# 快速创建项目（默认项目名：xiangjsoncraft-app）
|
|
66
|
+
npm create xiangjsoncraft@latest
|
|
67
|
+
|
|
68
|
+
# 指定项目名称创建（推荐）
|
|
69
|
+
npm create xiangjsoncraft@latest my-json-app
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### 方式2：使用 npx 直接调用
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
# 直接创建项目
|
|
76
|
+
npx create-xiangjsoncraft
|
|
77
|
+
|
|
78
|
+
# 指定项目名称
|
|
79
|
+
npx create-xiangjsoncraft my-json-app
|
|
16
80
|
```
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
81
|
+
|
|
82
|
+
### 方式3：全局安装后使用
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
# 全局安装脚手架
|
|
86
|
+
npm install -g xiangjsoncraft
|
|
87
|
+
|
|
88
|
+
# 创建项目
|
|
89
|
+
create-xiangjsoncraft my-json-app
|
|
20
90
|
```
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
document.addEventListener('DOMContentLoaded', () => {
|
|
50
|
-
XiangJsonCraft.renderJsonStyles();
|
|
51
|
-
});
|
|
52
|
-
</script>
|
|
53
|
-
</body>
|
|
54
|
-
</html>
|
|
91
|
+
|
|
92
|
+
### 项目启动步骤
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
# 1. 进入项目目录（替换为你的项目名）
|
|
96
|
+
cd my-json-app
|
|
97
|
+
|
|
98
|
+
# 2. 启动开发服务器（脚手架已自动配置脚本）
|
|
99
|
+
npm run start
|
|
100
|
+
|
|
101
|
+
# 3. 访问页面
|
|
102
|
+
# 打开浏览器访问 http://localhost:3000（默认端口，具体以终端提示为准）
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### 核心操作：自定义项目
|
|
106
|
+
|
|
107
|
+
启动项目后，**无需修改任何HTML/JS文件**，仅需编辑项目根目录的 `config.json`，即可自定义所有样式、内容和交互，修改后刷新浏览器即可生效。
|
|
108
|
+
|
|
109
|
+
## 📋 项目结构（2.0.0 标准化结构）
|
|
110
|
+
|
|
111
|
+
脚手架创建的项目结构清晰，所有可配置内容集中在`config.json`，无需关注其他文件：
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
my-json-app/ # 你的项目根目录
|
|
115
|
+
├─ index.html # DOM骨架（固定不变，无需修改）
|
|
116
|
+
├─ config.json # 核心配置文件（样式+内容+交互，唯一需要编辑的文件）
|
|
117
|
+
├─ package.json # 项目配置（自动生成，可修改脚本/依赖）
|
|
118
|
+
└─ README.md # 项目说明（自动生成，含使用指南）
|
|
55
119
|
```
|
|
56
|
-
|
|
120
|
+
|
|
121
|
+
### 各文件说明
|
|
122
|
+
|
|
123
|
+
- `index.html`：仅包含DOM骨架，定义页面基础结构（如容器、标题、按钮），选择器与config.json严格对应，无需修改
|
|
124
|
+
|
|
125
|
+
- `config.json`：框架核心配置文件，包含styles（样式）、content（内容）两个核心节点，所有自定义都在这里完成
|
|
126
|
+
|
|
127
|
+
- `package.json`：自动生成项目配置，包含启动脚本（npm run start）和框架依赖，可根据需求修改
|
|
128
|
+
|
|
129
|
+
- `README.md`：自动生成项目使用指南，包含启动命令、配置说明，便于团队协作和后续维护
|
|
130
|
+
|
|
131
|
+
## ⚙️ 核心配置详解（config.json）
|
|
132
|
+
|
|
133
|
+
config.json 是框架的核心，包含 `styles`（样式配置）和 `content`（内容配置）两个必填节点，语法遵循标准JSON规范（推荐用 [JSON.cn](https://www.json.cn/) 校验语法）。
|
|
134
|
+
|
|
135
|
+
### 1. 整体配置结构
|
|
136
|
+
|
|
57
137
|
```json
|
|
58
138
|
{
|
|
139
|
+
"framework": "XiangJsonCraft 2.0", // 框架标识（可选，仅用于识别）
|
|
140
|
+
"styles": { /* 样式配置（核心） */ }, // 所有CSS样式都在这里配置
|
|
141
|
+
"content": { /* 内容配置（核心） */ } // 所有页面内容都在这里配置
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### 2. styles 节点（样式配置）
|
|
146
|
+
|
|
147
|
+
用于定义所有页面CSS样式，完全兼容CSS语法，支持所有合法选择器和属性，仅需用JSON格式编写即可。
|
|
148
|
+
|
|
149
|
+
#### 核心规则
|
|
150
|
+
|
|
151
|
+
- 键（key）：CSS选择器（支持类、ID、全局*、伪类、媒体查询，如 `.app-title`、`#btn`、`.box:hover`、`@media (max-width: 768px)`）
|
|
152
|
+
|
|
153
|
+
- 值（value）：样式对象，键为CSS属性（支持驼峰命名），值为CSS属性值
|
|
154
|
+
|
|
155
|
+
- 容错机制：空选择器、非对象样式、空属性、无效属性值会被自动过滤，不影响整体渲染
|
|
156
|
+
|
|
157
|
+
- 驼峰转换：属性名支持驼峰（如fontSize、backgroundColor），框架会自动转换为CSS标准短横线写法（font-size、background-color）
|
|
158
|
+
|
|
159
|
+
#### 示例配置
|
|
160
|
+
|
|
161
|
+
```json
|
|
162
|
+
"styles": {
|
|
163
|
+
"*": { // 全局样式（所有元素生效）
|
|
164
|
+
"margin": 0,
|
|
165
|
+
"padding": 0,
|
|
166
|
+
"boxSizing": "border-box", // 驼峰命名，自动转为box-sizing
|
|
167
|
+
"fontFamily": "Segoe UI, Roboto, 微软雅黑, sans-serif"
|
|
168
|
+
},
|
|
169
|
+
"body": { // body标签样式
|
|
170
|
+
"backgroundColor": "#f0f4f8",
|
|
171
|
+
"color": "#334e68",
|
|
172
|
+
"lineHeight": "1.6",
|
|
173
|
+
"minHeight": "100vh"
|
|
174
|
+
},
|
|
175
|
+
".app-title": { // 类选择器样式
|
|
176
|
+
"fontSize": "2rem",
|
|
177
|
+
"color": "#2d3748",
|
|
178
|
+
"textAlign": "center",
|
|
179
|
+
"marginBottom": "1.5rem",
|
|
180
|
+
"transition": "color 0.3s ease"
|
|
181
|
+
},
|
|
182
|
+
".app-title:hover": { // 伪类样式
|
|
183
|
+
"color": "#4299e1"
|
|
184
|
+
},
|
|
185
|
+
"@media (max-width: 768px)": { // 响应式样式（移动端适配）
|
|
186
|
+
".app-title": {
|
|
187
|
+
"fontSize": "1.8rem"
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
### 3. content 节点（内容配置）
|
|
194
|
+
|
|
195
|
+
用于向HTML中的DOM节点注入文本或HTML内容，键为与HTML对应的选择器，值为内容配置对象，支持纯文本和HTML两种渲染方式。
|
|
196
|
+
|
|
197
|
+
#### 内容配置对象属性
|
|
198
|
+
|
|
199
|
+
| 属性名 | 类型 | 是否必选 | 默认值 | 说明 |
|
|
200
|
+
| ------ | -------- | -------- | ------ | ---------------------------------------------------------------------- |
|
|
201
|
+
| value | 任意类型 | 是 | - | 要注入的文本或HTML内容，框架会自动转为字符串处理 |
|
|
202
|
+
| isHtml | Boolean | 否 | false | true：以HTML格式渲染（支持标签和JS事件）；false：以纯文本渲染（防XSS） |
|
|
203
|
+
#### 示例配置
|
|
204
|
+
|
|
205
|
+
```json
|
|
206
|
+
"content": {
|
|
207
|
+
".app-title": { // 对应HTML中的 <h1 class="app-title"></h1>
|
|
208
|
+
"value": "XiangJsonCraft 2.0 示例",
|
|
209
|
+
"isHtml": false // 纯文本渲染
|
|
210
|
+
},
|
|
211
|
+
".app-desc": { // 对应HTML中的 <p class="app-desc"></p>
|
|
212
|
+
"value": "仅修改config.json，即可实现全页面自定义！",
|
|
213
|
+
"isHtml": false
|
|
214
|
+
},
|
|
215
|
+
".app-btn": { // 对应HTML中的 <a class="app-btn"></a>
|
|
216
|
+
"value": "<span onclick=\"alert('点击成功！')\">点击我</span>",
|
|
217
|
+
"isHtml": true // HTML渲染，支持JS事件
|
|
218
|
+
}
|
|
219
|
+
}
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
## 📌 完整配置示例（config.json）
|
|
223
|
+
|
|
224
|
+
```json
|
|
225
|
+
{
|
|
226
|
+
"framework": "XiangJsonCraft 2.0",
|
|
59
227
|
"styles": {
|
|
60
228
|
"*": {
|
|
61
229
|
"margin": 0,
|
|
@@ -70,239 +238,221 @@ your-project/
|
|
|
70
238
|
"minHeight": "100vh",
|
|
71
239
|
"padding": "2rem 1rem"
|
|
72
240
|
},
|
|
73
|
-
".
|
|
241
|
+
".app-container": {
|
|
74
242
|
"maxWidth": "1200px",
|
|
75
243
|
"margin": "0 auto",
|
|
76
|
-
"
|
|
244
|
+
"backgroundColor": "#ffffff",
|
|
245
|
+
"padding": "2rem",
|
|
246
|
+
"borderRadius": "12px",
|
|
247
|
+
"boxShadow": "0 4px 20px rgba(0,0,0,0.05)",
|
|
248
|
+
"transition": "all 0.3s ease"
|
|
249
|
+
},
|
|
250
|
+
".app-container:hover": {
|
|
251
|
+
"boxShadow": "0 8px 30px rgba(0,0,0,0.1)"
|
|
77
252
|
},
|
|
78
|
-
".
|
|
253
|
+
".app-title": {
|
|
79
254
|
"fontSize": "2.2rem",
|
|
80
255
|
"color": "#2d3748",
|
|
81
256
|
"textAlign": "center",
|
|
82
257
|
"marginBottom": "1.5rem",
|
|
83
|
-
"
|
|
258
|
+
"transition": "color 0.3s ease"
|
|
259
|
+
},
|
|
260
|
+
".app-title:hover": {
|
|
261
|
+
"color": "#4299e1"
|
|
84
262
|
},
|
|
85
|
-
".
|
|
263
|
+
".app-desc": {
|
|
86
264
|
"fontSize": "1.1rem",
|
|
87
|
-
"
|
|
265
|
+
"marginBottom": "2rem",
|
|
88
266
|
"textAlign": "center",
|
|
89
|
-
"maxWidth": "800px",
|
|
90
|
-
"margin": "0 auto 3rem",
|
|
91
|
-
"lineHeight": "1.8"
|
|
92
|
-
},
|
|
93
|
-
".feature-card": {
|
|
94
|
-
"backgroundColor": "#ffffff",
|
|
95
|
-
"borderRadius": "12px",
|
|
96
|
-
"padding": "2rem",
|
|
97
|
-
"boxShadow": "0 4px 12px rgba(0,0,0,0.05)",
|
|
98
267
|
"maxWidth": "600px",
|
|
99
|
-
"
|
|
100
|
-
"
|
|
101
|
-
},
|
|
102
|
-
".feature-card:hover": {
|
|
103
|
-
"transform": "translateY(-6px)",
|
|
104
|
-
"boxShadow": "0 8px 20px rgba(0,0,0,0.08)"
|
|
105
|
-
},
|
|
106
|
-
".feature-title": {
|
|
107
|
-
"fontSize": "1.4rem",
|
|
108
|
-
"color": "#4299e1",
|
|
109
|
-
"marginBottom": "1rem",
|
|
110
|
-
"fontWeight": 600
|
|
268
|
+
"marginLeft": "auto",
|
|
269
|
+
"marginRight": "auto"
|
|
111
270
|
},
|
|
112
|
-
".
|
|
113
|
-
"
|
|
114
|
-
"
|
|
271
|
+
".app-btn-group": {
|
|
272
|
+
"display": "flex",
|
|
273
|
+
"justifyContent": "center",
|
|
274
|
+
"gap": "1rem",
|
|
275
|
+
"flexWrap": "wrap"
|
|
115
276
|
},
|
|
116
|
-
".
|
|
117
|
-
"display": "block",
|
|
118
|
-
"
|
|
119
|
-
"height": "50px",
|
|
120
|
-
"lineHeight": "50px",
|
|
121
|
-
"textAlign": "center",
|
|
277
|
+
".app-btn": {
|
|
278
|
+
"display": "inline-block",
|
|
279
|
+
"padding": "12px 24px",
|
|
122
280
|
"backgroundColor": "#4299e1",
|
|
123
281
|
"color": "#ffffff",
|
|
124
|
-
"border": "none",
|
|
125
282
|
"borderRadius": "8px",
|
|
126
|
-
"
|
|
127
|
-
"fontSize": "1rem",
|
|
128
|
-
"fontWeight": 600,
|
|
283
|
+
"textDecoration": "none",
|
|
129
284
|
"cursor": "pointer",
|
|
130
|
-
"transition": "
|
|
131
|
-
"textDecoration": "none"
|
|
285
|
+
"transition": "all 0.3s ease"
|
|
132
286
|
},
|
|
133
|
-
".
|
|
287
|
+
".app-btn:hover": {
|
|
134
288
|
"backgroundColor": "#3182ce",
|
|
135
289
|
"transform": "translateY(-2px)"
|
|
136
290
|
},
|
|
137
|
-
".
|
|
138
|
-
"
|
|
139
|
-
|
|
291
|
+
".app-btn-secondary": {
|
|
292
|
+
"backgroundColor": "#718096"
|
|
293
|
+
},
|
|
294
|
+
".app-btn-secondary:hover": {
|
|
295
|
+
"backgroundColor": "#4a5568"
|
|
140
296
|
},
|
|
141
297
|
"@media (max-width: 768px)": {
|
|
142
|
-
".
|
|
143
|
-
"
|
|
298
|
+
".app-container": {
|
|
299
|
+
"padding": "1rem",
|
|
300
|
+
"margin": "0 0.5rem"
|
|
144
301
|
},
|
|
145
|
-
".
|
|
146
|
-
"
|
|
302
|
+
".app-title": {
|
|
303
|
+
"fontSize": "1.8rem"
|
|
147
304
|
},
|
|
148
|
-
".
|
|
149
|
-
"
|
|
305
|
+
".app-btn-group": {
|
|
306
|
+
"flexDirection": "column",
|
|
307
|
+
"alignItems": "center"
|
|
150
308
|
}
|
|
151
309
|
}
|
|
152
310
|
},
|
|
153
311
|
"content": {
|
|
154
|
-
".
|
|
155
|
-
"value": "XiangJsonCraft
|
|
312
|
+
".app-title": {
|
|
313
|
+
"value": "XiangJsonCraft 2.0 完整示例",
|
|
156
314
|
"isHtml": false
|
|
157
315
|
},
|
|
158
|
-
".
|
|
159
|
-
"value": "
|
|
316
|
+
".app-desc": {
|
|
317
|
+
"value": "纯JSON驱动的前端框架，无需写CSS/JS，修改JSON即可完成所有开发！",
|
|
160
318
|
"isHtml": false
|
|
161
319
|
},
|
|
162
|
-
".
|
|
163
|
-
"value": "
|
|
164
|
-
"isHtml":
|
|
165
|
-
},
|
|
166
|
-
".feature-desc": {
|
|
167
|
-
"value": "HTML仅负责搭建DOM骨架，样式、文本/HTML内容全由JSON控制，后期维护只需修改JSON，无需触碰HTML/JS代码，非前端开发者也能轻松使用。",
|
|
168
|
-
"isHtml": false
|
|
320
|
+
".app-btn": {
|
|
321
|
+
"value": "<span onclick=\"alert('主按钮被点击！')\">主按钮</span>",
|
|
322
|
+
"isHtml": true
|
|
169
323
|
},
|
|
170
|
-
".
|
|
171
|
-
"value": "<span onclick=\"
|
|
324
|
+
".app-btn-secondary": {
|
|
325
|
+
"value": "<span onclick=\"alert('次按钮被点击！')\">次按钮</span>",
|
|
172
326
|
"isHtml": true
|
|
173
327
|
}
|
|
174
328
|
}
|
|
175
329
|
}
|
|
176
330
|
```
|
|
177
|
-
#### 3. 运行项目
|
|
178
|
-
将两个文件放在同一文件夹，使用**VS Code Live Server**（或其他本地服务器）打开`index.html`（必须用服务器打开，避免浏览器跨域阻止加载本地JSON）。
|
|
179
331
|
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
- 每个选择器对应的值必须为**对象**（不能是数组/字符串/数字）；
|
|
219
|
-
- 空属性、无效属性值会被自动过滤，不影响整体渲染。
|
|
220
|
-
|
|
221
|
-
### 2. content 节点：内容配置
|
|
222
|
-
- 用于向DOM节点注入文本或HTML内容，**键为与HTML对应的选择器**，值为内容配置对象；
|
|
223
|
-
- 内容配置对象包含2个属性：
|
|
224
|
-
| 属性 | 类型 | 必选 | 默认值 | 说明 |
|
|
225
|
-
| ------ | ------- | ---- | ------ | ------------------------------------------ |
|
|
226
|
-
| value | 任意 | 是 | - | 要注入的文本/HTML内容 |
|
|
227
|
-
| isHtml | Boolean | 否 | false | 是否以HTML格式渲染，false为纯文本（防XSS） |
|
|
228
|
-
|
|
229
|
-
#### 关键规则
|
|
230
|
-
- 选择器需与HTML严格对应，不存在的选择器会被自动过滤；
|
|
231
|
-
- 必须包含`value`属性，否则该节点会被过滤；
|
|
232
|
-
- `isHtml: true`时，`value`支持HTML标签和原生JS事件（如`onclick`），适合实现简单交互。
|
|
233
|
-
|
|
234
|
-
## 核心函数说明
|
|
235
|
-
### renderJsonStyles()
|
|
236
|
-
- 核心渲染函数，无入参，调用后自动执行以下逻辑：
|
|
237
|
-
1. 优先加载**与HTML同级的本地config.json**，控制台打印`🔧 检测到本地config.json，优先加载用户自定义配置`；
|
|
238
|
-
2. 若本地无config.json，自动加载**CDN官方示例配置**，控制台打印`ℹ️ 本地未检测到config.json，加载CDN官方示例配置`；
|
|
239
|
-
3. 解析样式配置，生成格式化的CSS代码，注入到页面的`#dynamic-styles`样式块；
|
|
240
|
-
4. 解析内容配置，根据选择器向对应DOM节点注入文本/HTML内容；
|
|
241
|
-
5. 渲染成功打印`✅ XiangJsonCraft 渲染成功！样式+内容已全部加载`，失败则打印具体错误信息。
|
|
242
|
-
|
|
243
|
-
## 浏览器控制台日志说明
|
|
244
|
-
工具会打印清晰的日志，方便排查问题，日志分类如下：
|
|
245
|
-
| 日志级别 | 前缀 | 说明 |
|
|
246
|
-
| -------- | ---- | -------------------------- |
|
|
247
|
-
| 信息 | 🔧/ℹ️ | 配置加载状态提示 |
|
|
248
|
-
| 成功 | ✅ | 渲染成功提示 |
|
|
249
|
-
| 错误 | ❌ | 渲染失败（含具体错误原因） |
|
|
250
|
-
|
|
251
|
-
## 常见问题排查
|
|
252
|
-
### 1. 控制台报404错误：无法加载config.json
|
|
253
|
-
- 原因：未用本地服务器打开页面，浏览器跨域策略阻止加载本地文件；
|
|
254
|
-
- 解决：使用VS Code Live Server/Node.js Express等本地服务器打开，确保JSON文件可通过服务器访问。
|
|
255
|
-
|
|
256
|
-
### 2. 控制台报错：prop.replaceCamelCase is not a function
|
|
257
|
-
- 原因：styles节点中存在**非字符串类型的属性名**（如数字、null）；
|
|
258
|
-
- 解决：校验JSON语法，确保所有属性名为**双引号包裹的字符串**，删除无效属性。
|
|
259
|
-
|
|
260
|
-
### 3. 样式未渲染/内容未注入
|
|
261
|
-
- 检查选择器：HTML中的DOM选择器与JSON中的键**严格一致**（区分大小写、类名前缀`.`）；
|
|
262
|
-
- 检查JSON语法：确保无语法错误（如缺少引号、大括号，逗号结尾）；
|
|
263
|
-
- 检查日志：根据控制台日志判断配置文件是否被正确加载。
|
|
264
|
-
|
|
265
|
-
### 4. 浏览器标签页报favicon.ico 404
|
|
266
|
-
- 原因：浏览器默认在项目根目录找网站小图标，未找到则报404；
|
|
267
|
-
- 解决：下载`favicon.ico`图标放到项目根目录，或在HTML的`<head>`中通过`<link rel="icon">`指定PNG/SVG图标。
|
|
268
|
-
|
|
269
|
-
## 开发与打包
|
|
332
|
+
## 🔧 常见问题排查
|
|
333
|
+
|
|
334
|
+
### 1. 控制台报 404 错误：无法加载 config.json
|
|
335
|
+
|
|
336
|
+
- 原因：未使用本地服务器打开页面，浏览器跨域策略阻止加载本地JSON文件（直接双击HTML文件会触发此问题）
|
|
337
|
+
|
|
338
|
+
- 解决：使用 VS Code Live Server、Node.js Express 等本地服务器打开项目，确保JSON文件可通过服务器访问
|
|
339
|
+
|
|
340
|
+
### 2. 样式未渲染 / 内容未注入
|
|
341
|
+
|
|
342
|
+
- 检查选择器：HTML中的DOM选择器与config.json中的键必须**严格一致**（区分大小写、类名前缀`.`、ID前缀`#`）
|
|
343
|
+
|
|
344
|
+
- 检查JSON语法：确保config.json无语法错误（如缺少引号、大括号、逗号结尾），可通过JSON.cn校验
|
|
345
|
+
|
|
346
|
+
- 检查日志：查看浏览器控制台日志，确认框架是否渲染成功、配置是否被正确加载
|
|
347
|
+
|
|
348
|
+
### 3. 依赖安装失败
|
|
349
|
+
|
|
350
|
+
- 原因：网络问题、npm镜像问题，或本地npm版本过低
|
|
351
|
+
|
|
352
|
+
- 解决：手动进入项目目录，执行`npm install` 重新安装；或切换npm镜像（如`npm config set registry https://registry.npm.taobao.org`）
|
|
353
|
+
|
|
354
|
+
### 4. 控制台报错：prop.replaceCamelCase is not a function
|
|
355
|
+
|
|
356
|
+
- 原因：styles节点中存在非字符串类型的属性名（如数字、null、数组）
|
|
357
|
+
|
|
358
|
+
- 解决：校验config.json，确保styles节点下所有属性名均为双引号包裹的字符串，删除无效属性
|
|
359
|
+
|
|
360
|
+
### 5. 浏览器报 favicon.ico 404
|
|
361
|
+
|
|
362
|
+
- 原因：浏览器默认在项目根目录查找网站小图标，未找到则报404（不影响项目功能）
|
|
363
|
+
|
|
364
|
+
- 解决：下载favicon.ico图标放到项目根目录，或在HTML的<head>中通过<link rel="icon">指定PNG/SVG图标
|
|
365
|
+
|
|
366
|
+
## 📦 框架开发与打包（开发者指南）
|
|
367
|
+
|
|
368
|
+
若你需要修改框架核心逻辑、二次开发，可按照以下步骤操作：
|
|
369
|
+
|
|
270
370
|
### 1. 克隆源码
|
|
371
|
+
|
|
271
372
|
```bash
|
|
272
|
-
git clone https://github.com
|
|
373
|
+
git clone https://github.com/dxiangwiki/xiangjsoncraft.git
|
|
273
374
|
cd xiangjsoncraft
|
|
274
375
|
```
|
|
376
|
+
|
|
275
377
|
### 2. 安装开发依赖
|
|
378
|
+
|
|
276
379
|
```bash
|
|
277
380
|
npm install
|
|
278
381
|
```
|
|
279
|
-
|
|
280
|
-
|
|
382
|
+
|
|
383
|
+
### 3. 修改核心逻辑
|
|
384
|
+
|
|
385
|
+
- 框架核心渲染逻辑：`src/renderJson.js`
|
|
386
|
+
|
|
387
|
+
- 脚手架逻辑：`bin/create.js`
|
|
388
|
+
|
|
389
|
+
- 项目模板：`template/` 目录下的所有文件
|
|
390
|
+
|
|
391
|
+
- 打包配置：`rollup.config.js`
|
|
392
|
+
|
|
393
|
+
### 4. 打包框架核心
|
|
394
|
+
|
|
395
|
+
```bash
|
|
396
|
+
npm run build
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
打包后会在 `dist/` 目录生成 `xiangjsoncraft.umd.js`（UMD格式，兼容模块化/非模块化环境）。
|
|
400
|
+
|
|
401
|
+
### 5. 本地测试
|
|
402
|
+
|
|
403
|
+
打包后，将`dist/xiangjsoncraft.umd.js` 与 `template/` 目录下的文件放在一起，通过本地服务器测试渲染效果。
|
|
404
|
+
|
|
405
|
+
## 📤 发包步骤（2.0.0 正式发布）
|
|
406
|
+
|
|
281
407
|
```bash
|
|
408
|
+
# 1. 安装依赖（确保所有依赖已安装）
|
|
409
|
+
npm install
|
|
410
|
+
|
|
411
|
+
# 2. 打包框架核心（生成dist目录）
|
|
282
412
|
npm run build
|
|
413
|
+
|
|
414
|
+
# 3. 登录NPM（确保已注册NPM账号，且拥有包发布权限）
|
|
415
|
+
npm login
|
|
416
|
+
|
|
417
|
+
# 4. 发布2.0.0版本（--access public 确保公开可访问）
|
|
418
|
+
npm publish --access public
|
|
283
419
|
```
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
-
|
|
290
|
-
|
|
291
|
-
-
|
|
292
|
-
|
|
293
|
-
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
420
|
+
|
|
421
|
+
## 📜 版本更新日志
|
|
422
|
+
|
|
423
|
+
### v2.0.0（最新稳定版 | 重大升级）
|
|
424
|
+
|
|
425
|
+
- 定位升级：从「JSON渲染工具」升级为「纯JSON驱动的轻量前端框架」，版本号直接跳至2.0.0，不兼容1.x版本
|
|
426
|
+
|
|
427
|
+
- 新增功能：官方脚手架、多模板支持、自动依赖管理、友好控制台日志、全局变量暴露、部署简化
|
|
428
|
+
|
|
429
|
+
- 能力强化：交互支持优化、响应式示例完善、样式注入优化、容错机制升级
|
|
430
|
+
|
|
431
|
+
- 体验优化：标准化项目结构、自动生成使用文档、清晰的控制台提示、简化开发流程
|
|
432
|
+
|
|
433
|
+
- 继承保留：1.x版本的核心渲染能力、驼峰转短横线、强容错性、CSS全兼容等优势
|
|
434
|
+
|
|
435
|
+
### v1.1.1 ~ v1.2.0（工具版本）
|
|
436
|
+
|
|
437
|
+
- v1.2.0：优化本地/CDN配置加载优先级，新增容错机制，完善控制台日志，支持SVG/PNG网站小图标
|
|
438
|
+
|
|
439
|
+
- v1.1.1：首次正式发布，实现核心JSON样式+内容渲染，支持驼峰转短横线、CDN/本地引入，基本容错机制
|
|
440
|
+
|
|
441
|
+
## ⚖️ 开源协议
|
|
442
|
+
|
|
443
|
+
MIT License - 详见项目根目录 `LICENSE` 文件，可自由使用、修改、分发，无需授权，仅需保留开源协议声明。
|
|
444
|
+
|
|
445
|
+
## 🔗 官方地址
|
|
446
|
+
|
|
447
|
+
- NPM：[https://www.npmjs.com/package/xiangjsoncraft](https://www.npmjs.com/package/xiangjsoncraft)
|
|
448
|
+
|
|
449
|
+
- Github：[https://github.com/dxiangwiki/xiangjsoncraft](https://github.com/dxiangwiki/xiangjsoncraft)
|
|
450
|
+
|
|
451
|
+
## 💬 问题反馈
|
|
452
|
+
|
|
453
|
+
若使用过程中遇到问题、有功能建议，可在GitHub仓库提交Issue，或通过NPM包主页留言，会及时响应并修复。
|
|
454
|
+
|
|
455
|
+
## ✨ 框架口号
|
|
456
|
+
|
|
457
|
+
**Write JSON, Get a Website.** | 只写 JSON，就能得到一个完整网站。
|
|
458
|
+
> （注：文档部分内容可能由 AI 生成）
|