npm - xiangjsoncraft - Versions diffs - 1.1.2 → 1.2.0 - Mend

xiangjsoncraft 1.1.2 → 1.2.0

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.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -1,355 +1,308 @@
 # XiangJsonCraft
-![XiangJsonCraft Logo](https://picsum.photos/seed/xiangjsoncraft/200/200)
-XiangJsonCraft 是一个简单而强大的 JSON 配置与 HTML 页面渲染工具，由大学生董翔开发，专为前端开发者设计。通过简洁的 API，它允许你使用 JSON 配置文件来定义样式和内容，并将其应用到 HTML 页面中，实现动态页面的快速构建，做到样式、内容与代码的解耦管理。
-## 🚀 最新更新 (v1.1.1)
-基于 v1.1.0 核心功能完成**环境适配升级**，新增 CDN/本地双环境兼容能力，发布后可零成本实现本地开发、CDN 在线使用，同时优化渲染容错性，避免空配置、无效选择器导致的渲染异常。
-### 核心更新
-- **CDN/本地双环境适配**：自动识别运行环境，无需修改代码即可实现本地开发、CDN 在线调用
-- **渲染容错优化**：过滤空样式、无效选择器，新增样式块创建判空，控制台错误提示更友好
-- **打包格式完善**：提供 UMD/ES/CJS 三种打包格式，适配浏览器、前端框架、Node.js 全环境
-- **使用体验升级**：新增 npm dev 脚本，一键启动开发服务器，快速验证开发效果
-## ✨ 核心特性
-- **简单易用**：仅需一行 API 调用，即可完成整个页面的样式和内容渲染
-- **灵活配置**：通过单一 JSON 文件定义所有样式、文本、HTML 内容，支持按需修改
-- **轻量级无依赖**：原生 JavaScript 开发，无任何第三方依赖，体积小巧，加载速度快
-- **全面的 CSS 支持**：兼容所有 CSS 选择器（类、ID、伪类、伪元素、媒体查询等）
-- **响应式设计友好**：直接通过 JSON 配置媒体查询，轻松实现多屏幕尺寸适配
-- **双内容类型支持**：同时支持纯文本、HTML 片段动态注入，满足不同内容渲染需求
-- **多环境适配**：支持本地模块化引入、CDN 全局调用，适配所有现代浏览器
-- **高容错性**：自动过滤无效配置、空样式，避免单一配置错误导致整体渲染失败
-## 📦 安装使用
-### 1. npm 安装
-```bash
-# npm
-npm install xiangjsoncraft --save
-# yarn
-yarn add xiangjsoncraft
-# pnpm
-pnpm add xiangjsoncraft
-```
-### 2. CDN 在线使用（零安装）
-无需本地安装，一行脚本引入即可全局调用，适合快速原型开发、静态页面使用：
-```html
-<!-- 引入UMD包，自动挂载全局变量 XiangJsonCraft -->
-<script src="https://cdn.jsdelivr.net/npm/xiangjsoncraft@1.1.1/dist/xiangjsoncraft.umd.js"></script>
-<!-- 直接调用核心方法，零配置渲染 -->
-<script>
-  XiangJsonCraft.renderJsonStyles();
-</script>
+一款**以JSON解耦网页样式与内容**的轻量级前端工具，无需手写CSS/修改JS，仅通过编辑JSON配置文件即可快速定制网页，实现「HTML搭骨架、JSON定样式填内容」的开发模式，降低页面定制门槛，让非前端开发者也能轻松制作网页。
+## 核心特色
+✅ **JSON完全解耦**：样式、文本/HTML内容全由JSON配置，HTML仅负责搭建DOM骨架，后期维护只需改JSON
+✅ **双环境兼容**：本地引入/CDN在线引入均支持，**本地config.json永远最高优先级**，CDN提供官方示例配置兜底
+✅ **零门槛上手**：无需复杂配置，3个文件即可实现页面开发，支持驼峰属性自动转CSS标准短横线
+✅ **强容错性**：过滤无效配置、非标准属性，单个配置错误不影响整体渲染，控制台友好日志提示
+✅ **丰富样式支持**：兼容CSS全局样式、hover动效、过渡动画、媒体查询响应式，生成样式自动格式化
+✅ **轻量无依赖**：核心代码仅百行，无第三方依赖，打包后UMD格式体积极小，不占用项目资源
+## 快速开始
+### 方式1：CDN在线引入（推荐，零文件下载，快速体验/开发）
+仅需2个文件（`index.html` + 自定义`config.json`），一行脚本引入，无需打包/安装依赖。
+#### 项目目录
 ```
-## ⚡ 快速开始
-### 步骤1：创建 JSON 配置文件
-在项目根目录/HTML 同级目录创建 `config.json`，定义页面的样式、文本及 HTML 内容，支持所有 CSS 选择器和媒体查询：
-```json
-{
-  "styles": {
-    "*": {
-      "margin": "0",
-      "padding": "0",
-      "boxSizing": "border-box"
-    },
-    "body": {
-      "fontFamily": "Arial, sans-serif",
-      "lineHeight": "1.6",
-      "color": "#333",
-      "backgroundColor": "#f9f9f9",
-      "padding": "2rem"
-    },
-    ".header": {
-      "backgroundColor": "#2c3e50",
-      "color": "white",
-      "padding": "1.5rem",
-      "textAlign": "center",
-      "borderRadius": "8px",
-      "marginBottom": "2rem"
-    },
-    "nav ul": {
-      "display": "flex",
-      "listStyle": "none",
-      "justifyContent": "center",
-      "gap": "1.5rem",
-      "marginBottom": "2rem"
-    },
-    "nav a": {
-      "color": "#2c3e50",
-      "textDecoration": "none",
-      "fontSize": "1.1rem"
-    },
-    "nav a:hover": {
-      "color": "#f39c12",
-      "textDecoration": "underline"
-    },
-    ".card": {
-      "background": "white",
-      "padding": "2rem",
-      "borderRadius": "8px",
-      "boxShadow": "0 2px 8px rgba(0,0,0,0.1)"
-    },
-    "@media (max-width: 768px)": {
-      "body": {
-        "padding": "1rem"
-      },
-      "nav ul": {
-        "flexDirection": "column",
-        "alignItems": "center",
-        "gap": "1rem"
-      }
-    }
-  },
-  "content": {
-    ".header h1": {
-      "value": "XiangJsonCraft 演示页面",
-      "isHtml": false
-    },
-    ".card h2": {
-      "value": "<span style='color:#2c3e50;'>JSON 配置渲染</span> 就是这么简单",
-      "isHtml": true
-    },
-    ".card p": {
-      "value": "通过单个 JSON 文件定义所有样式和内容，一行代码完成页面渲染，实现代码与配置的解耦管理。",
-      "isHtml": false
-    }
-  }
-}
+your-project/
+├─ index.html  # 仅写DOM骨架，无手动CSS
+└─ config.json # 你的自定义配置文件（核心，样式+内容全在这里）
 ```
-### 步骤2：创建 HTML 页面
-创建 `index.html`，引入渲染容器并调用核心 API，无需手写任何 CSS 样式：
+#### 1. 编写index.html（DOM骨架，选择器与JSON严格对应）
 ```html
 <!DOCTYPE html>
-<html lang="en">
+<html lang="zh-CN">
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>XiangJsonCraft 快速开始</title>
-    <!-- 动态样式块，渲染后的CSS会注入到这里 -->
+    <title>XiangJsonCraft 示例</title>
+    <link rel="icon" href="./favicon.ico" type="image/x-icon">
+    <!-- 空样式块，由工具自动注入CSS，请勿手动添加样式 -->
     <style id="dynamic-styles"></style>
 </head>
 <body>
-    <!-- 页面渲染容器，与config.json中的选择器匹配 -->
-    <header class="header">
-        <h1></h1>
-    </header>
-    <nav>
-        <ul>
-            <li><a href="#">首页</a></li>
-            <li><a href="#">文档</a></li>
-            <li><a href="#">示例</a></li>
-        </ul>
-    </nav>
-    <div class="card">
-        <h2></h2>
-        <p></p>
+    <!-- DOM骨架：选择器与config.json严格对应 -->
+    <div class="welcome-container">
+        <h1 class="main-title"></h1>
+        <p class="subtitle"></p>
+        <div class="feature-card">
+            <h3 class="feature-title"></h3>
+            <p class="feature-desc"></p>
+        </div>
+        <a href="javascript:;" class="primary-btn"></a>
     </div>
-    <!-- 方式1：本地模块化引入（推荐，适合项目开发） -->
-    <script type="module">
-        import { renderJsonStyles } from './renderJson.js';
-        // 一行调用，完成所有样式和内容渲染
-        renderJsonStyles();
-    </script>
-    <!-- 方式2：CDN全局调用（注释方式1，打开此注释即可） -->
-    <!-- <script src="https://cdn.jsdelivr.net/npm/xiangjsoncraft@1.1.1/dist/xiangjsoncraft.umd.js"></script>
+    <!-- CDN引入最新版本，全局调用 -->
+    <script src="https://cdn.jsdelivr.net/npm/xiangjsoncraft@1.2.0/dist/xiangjsoncraft.umd.js"></script>
     <script>
-        XiangJsonCraft.renderJsonStyles();
-    </script> -->
+        // 页面加载完成后执行渲染，避免DOM未加载
+        document.addEventListener('DOMContentLoaded', () => {
+            XiangJsonCraft.renderJsonStyles();
+        });
+    </script>
 </body>
 </html>
 ```
-### 步骤3：开发运行
-```bash
-# 安装开发依赖（首次使用）
-npm install
-# 打包生成多格式文件（UMD/ES/CJS）
-npm run build
-# 启动开发服务器，一键预览效果
-npm run dev
-```
-在浏览器中访问 `http://localhost:3000`，即可看到由 JSON 配置渲染的完整页面。
-## 📚 API 文档
-### `renderJsonStyles()`
-**核心渲染方法**，无入参，执行后自动完成以下操作：
-1. 自动识别运行环境（本地/CDN），加载对应路径的 `config.json` 配置文件
-2. 解析配置中的 `styles` 节点，生成标准 CSS 样式并注入到页面头部的 `#dynamic-styles` 样式块
-3. 解析配置中的 `content` 节点，根据 `isHtml` 标识，向匹配的 DOM 节点注入纯文本/HTML 内容
-4. 控制台输出渲染成功提示，若配置异常则输出友好的错误信息
-#### 调用方式
-```javascript
-// 方式1：ES6模块化引入（本地开发/前端框架）
-import { renderJsonStyles } from 'xiangjsoncraft';
-renderJsonStyles();
-// 方式2：CDN全局调用（静态页面/快速开发）
-XiangJsonCraft.renderJsonStyles();
-```
-## ⚙️ 配置文件说明
-配置文件为标准 JSON 格式，核心包含 `styles` 和 `content` 两个一级节点，所有配置均支持按需扩展、修改。
-### 1. `styles` 节点
-用于定义页面所有 CSS 样式，**键为任意合法 CSS 选择器**，值为样式属性对象，样式属性支持**驼峰式命名**（会自动转换为 CSS 标准短横线命名）。
-- 支持选择器：类、ID、标签、伪类、伪元素、后代选择器、媒体查询等所有 CSS 合法选择器
-- 样式属性：所有 CSS 原生属性，驼峰式（`fontSize`）会自动转为短横线式（`font-size`）
-### 2. `content` 节点
-用于定义页面文本/HTML 内容，**键为 CSS 选择器**，值为内容配置对象，包含两个必选属性：
-- `value`：字符串类型，要渲染的内容（纯文本/HTML 片段）
-- `isHtml`：布尔类型，`true` 表示内容为 HTML 片段，`false` 表示内容为纯文本（默认）
-### 配置文件规范
-1. 配置文件必须命名为 `config.json`，与 HTML 页面同级目录（CDN 方式无需手动创建，自动加载官方配置）
-2. 选择器必须匹配 HTML 中的实际 DOM 节点，否则会被自动过滤
-3. 样式属性值需符合 CSS 规范（如单位、颜色值、尺寸值）
-4. HTML 片段需保证语法合法，避免 XSS 风险（建议仅在可信环境下使用 HTML 内容）
-## 🎨 配置示例
-### 完整配置示例
+#### 2. 编写config.json（自定义样式+内容，示例可直接复制使用）
 ```json
 {
   "styles": {
-    // 通配符选择器
     "*": {
-      "margin": "0",
-      "padding": "0",
-      "boxSizing": "border-box"
+      "margin": 0,
+      "padding": 0,
+      "boxSizing": "border-box",
+      "fontFamily": "Segoe UI, Roboto, 微软雅黑, sans-serif"
     },
-    // 标签选择器
     "body": {
-      "fontFamily": "Microsoft YaHei, sans-serif",
-      "lineHeight": "1.8",
-      "color": "#333",
-      "backgroundColor": "#f5f5f5"
+      "backgroundColor": "#f0f4f8",
+      "color": "#334e68",
+      "lineHeight": "1.6",
+      "minHeight": "100vh",
+      "padding": "2rem 1rem"
     },
-    // ID选择器
-    "#app": {
+    ".welcome-container": {
       "maxWidth": "1200px",
       "margin": "0 auto",
       "padding": "2rem"
     },
-    // 类选择器
-    ".btn": {
-      "padding": "0.8rem 1.5rem",
+    ".main-title": {
+      "fontSize": "2.2rem",
+      "color": "#2d3748",
+      "textAlign": "center",
+      "marginBottom": "1.5rem",
+      "fontWeight": 700
+    },
+    ".subtitle": {
+      "fontSize": "1.1rem",
+      "color": "#718096",
+      "textAlign": "center",
+      "maxWidth": "800px",
+      "margin": "0 auto 3rem",
+      "lineHeight": "1.8"
+    },
+    ".feature-card": {
+      "backgroundColor": "#ffffff",
+      "borderRadius": "12px",
+      "padding": "2rem",
+      "boxShadow": "0 4px 12px rgba(0,0,0,0.05)",
+      "maxWidth": "600px",
+      "margin": "0 auto 2rem",
+      "transition": "transform 0.3s ease, boxShadow 0.3s ease"
+    },
+    ".feature-card:hover": {
+      "transform": "translateY(-6px)",
+      "boxShadow": "0 8px 20px rgba(0,0,0,0.08)"
+    },
+    ".feature-title": {
+      "fontSize": "1.4rem",
+      "color": "#4299e1",
+      "marginBottom": "1rem",
+      "fontWeight": 600
+    },
+    ".feature-desc": {
+      "color": "#718096",
+      "lineHeight": "1.7"
+    },
+    ".primary-btn": {
+      "display": "block",
+      "width": "200px",
+      "height": "50px",
+      "lineHeight": "50px",
+      "textAlign": "center",
+      "backgroundColor": "#4299e1",
+      "color": "#ffffff",
       "border": "none",
-      "borderRadius": "4px",
+      "borderRadius": "8px",
+      "margin": "0 auto",
+      "fontSize": "1rem",
+      "fontWeight": 600,
       "cursor": "pointer",
-      "fontSize": "1rem"
+      "transition": "backgroundColor 0.3s ease, transform 0.2s ease",
+      "textDecoration": "none"
     },
-    // 伪类选择器
-    ".btn-primary": {
-      "backgroundColor": "#3498db",
-      "color": "white"
+    ".primary-btn:hover": {
+      "backgroundColor": "#3182ce",
+      "transform": "translateY(-2px)"
     },
-    ".btn-primary:hover": {
-      "backgroundColor": "#2980b9"
+    ".primary-btn:active": {
+      "transform": "translateY(0)",
+      "backgroundColor": "#2b6cb0"
     },
-    // 媒体查询
     "@media (max-width: 768px)": {
-      "#app": {
+      ".main-title": {
+        "fontSize": "1.8rem"
+      },
+      ".welcome-container": {
         "padding": "1rem"
       },
-      ".btn": {
-        "width": "100%",
-        "marginBottom": "1rem"
+      ".feature-card": {
+        "padding": "1.5rem"
       }
     }
   },
   "content": {
-    // 纯文本内容
-    "#app h1": {
-      "value": "XiangJsonCraft 配置示例",
+    ".main-title": {
+      "value": "XiangJsonCraft 快速示例",
       "isHtml": false
     },
-    // HTML 片段内容
-    ".desc": {
-      "value": "支持 <strong>HTML 片段</strong> 和 <em>纯文本</em> 两种渲染方式",
+    ".subtitle": {
+      "value": "基于JSON配置渲染的网页，无需手写CSS，修改JSON即可定制所有样式和内容！",
+      "isHtml": false
+    },
+    ".feature-title": {
+      "value": "核心特色：JSON完全解耦",
+      "isHtml": false
+    },
+    ".feature-desc": {
+      "value": "HTML仅负责搭建DOM骨架，样式、文本/HTML内容全由JSON控制，后期维护只需修改JSON，无需触碰HTML/JS代码，非前端开发者也能轻松使用。",
+      "isHtml": false
+    },
+    ".primary-btn": {
+      "value": "<span onclick=\"window.open('https://www.npmjs.com/package/xiangjsoncraft', '_blank')\">查看NPM官方文档</span>",
       "isHtml": true
     }
   }
 }
 ```
+#### 3. 运行项目
+将两个文件放在同一文件夹，使用**VS Code Live Server**（或其他本地服务器）打开`index.html`（必须用服务器打开，避免浏览器跨域阻止加载本地JSON）。
-## 🥚 彩蛋：工具背后的小插曲
-### “敢改包”的底气来源
-其实XiangJsonCraft的诞生，还藏着一段有趣的小场景——
-某天，朋友在Vue项目里用这个包时，遇到了个不符合自己编程习惯的小细节，对着node_modules里的代码犯愁：“老师说这地方不能随便改，容易牵一发而动全身。”
-我当时笑着回了句：“没事，改不坏。”朋友反问：“你怎么这么自信？难道你会用？”
-我故意顿了顿，笑着说：“哼？我会吗……”
-其实不是“会用”，是“会造”——整个包的每一行代码，都是我从0到1敲出来的。哪里是样式配置的核心逻辑，哪部分是内容渲染的关键节点，甚至每个变量命名的小心思，早就刻在脑子里了。
-对别人来说，改node_modules是“碰别人的代码”；但对我来说，改的是“自己写的工具”。知道怎么调整既不破坏核心功能，又能贴合朋友的习惯，这份底气，其实来自“开发者”这个身份最本质的掌控感。
-所以如果你用的时候也有小想法，不用怕“改坏”——工具本身就为“灵活适配”留足了空间，而作为作者，我也始终在背后，为它的稳定和好用托底。
-## 🌐 浏览器兼容性
-支持所有现代浏览器，无需额外引入 polyfill：
-- Chrome ≥ 61
-- Firefox ≥ 60
-- Edge ≥ 79
-- Safari ≥ 12.1
-- Opera ≥ 48
-- 移动端所有现代浏览器（微信浏览器、QQ浏览器、Safari 移动端等）
-## 🤝 贡献指南
-XiangJsonCraft 欢迎所有开发者的贡献和建议，如果你有以下想法，欢迎随时交流：
-- 新增功能需求
-- 性能优化建议
-- Bug 修复
-- 文档完善
-**贡献方式**：通过邮箱联系作者，提供你的想法、代码或问题描述，作者会第一时间回复。
-## 📄 许可证
-本项目基于 **MIT 开源许可证** 发布，你可以自由使用、修改、分发本项目，无需支付任何费用，只需保留版权声明。
+### 方式2：NPM安装（本地开发，集成到现有项目）
+#### 1. 安装包
+```bash
+npm install xiangjsoncraft --save
 ```
-MIT License
-Copyright (c) 2025 董翔
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+#### 2. 项目目录（集成到现有项目）
 ```
+your-project/
+├─ src/
+│  ├─ index.html  # 项目入口页面（DOM骨架）
+│  ├─ config.json # 自定义配置文件
+│  └─ main.js     # 入口JS，引入并调用渲染函数
+└─ package.json
+```
+#### 3. 编写main.js（模块化引入）
+```javascript
+// 模块化引入核心渲染函数
+import { renderJsonStyles } from 'xiangjsoncraft';
-## 📞 联系我们
-如果你有任何问题、建议或合作想法，欢迎通过以下方式联系作者：
-- **Email**：3631247406@qq.com
-- **作者**：董翔
----
-**感谢使用 XiangJsonCraft！**
-愿这个小工具能让你的前端开发更高效、更轻松 🚀
+// 页面加载完成后执行
+document.addEventListener('DOMContentLoaded', () => {
+  renderJsonStyles();
+});
+```
+#### 4. 运行项目
+通过项目的构建工具（Vite/Webpack/Parcel等）运行，确保本地服务器能正常访问`config.json`。
+## 配置文件说明（config.json）
+配置文件包含`styles`和`content`两个核心节点，**均为对象格式**，选择器需与HTML中的DOM严格对应，JSON语法需合法（推荐用[JSON.cn](https://www.json.cn/)校验）。
+### 1. styles 节点：样式配置
+- 用于定义所有CSS样式，**支持所有合法CSS选择器**（全局`*`、类、ID、伪类、媒体查询`@media`等）；
+- 样式属性名**支持驼峰命名**（如`boxSizing`），工具会自动转换为CSS标准短横线命名（`box-sizing`）；
+- 属性值为**CSS合法值字符串/数字**（如`"2rem"`、`100%`、`700`），工具会自动转字符串处理；
+- 支持**hover/active**等伪类、**transition**过渡动画、**@media**响应式布局，写法与CSS一致。
+#### 关键规则
+- 选择器不能为空，且必须为字符串；
+- 每个选择器对应的值必须为**对象**（不能是数组/字符串/数字）；
+- 空属性、无效属性值会被自动过滤，不影响整体渲染。
+### 2. content 节点：内容配置
+- 用于向DOM节点注入文本或HTML内容，**键为与HTML对应的选择器**，值为内容配置对象；
+- 内容配置对象包含2个属性：
+  | 属性   | 类型    | 必选 | 默认值 | 说明                                       |
+  | ------ | ------- | ---- | ------ | ------------------------------------------ |
+  | value  | 任意    | 是   | -      | 要注入的文本/HTML内容                      |
+  | isHtml | Boolean | 否   | false  | 是否以HTML格式渲染，false为纯文本（防XSS） |
+#### 关键规则
+- 选择器需与HTML严格对应，不存在的选择器会被自动过滤；
+- 必须包含`value`属性，否则该节点会被过滤；
+- `isHtml: true`时，`value`支持HTML标签和原生JS事件（如`onclick`），适合实现简单交互。
+## 核心函数说明
+### renderJsonStyles()
+- 核心渲染函数，无入参，调用后自动执行以下逻辑：
+  1. 优先加载**与HTML同级的本地config.json**，控制台打印`🔧 检测到本地config.json，优先加载用户自定义配置`；
+  2. 若本地无config.json，自动加载**CDN官方示例配置**，控制台打印`ℹ️  本地未检测到config.json，加载CDN官方示例配置`；
+  3. 解析样式配置，生成格式化的CSS代码，注入到页面的`#dynamic-styles`样式块；
+  4. 解析内容配置，根据选择器向对应DOM节点注入文本/HTML内容；
+  5. 渲染成功打印`✅ XiangJsonCraft 渲染成功！样式+内容已全部加载`，失败则打印具体错误信息。
+## 浏览器控制台日志说明
+工具会打印清晰的日志，方便排查问题，日志分类如下：
+| 日志级别 | 前缀 | 说明                       |
+| -------- | ---- | -------------------------- |
+| 信息     | 🔧/ℹ️  | 配置加载状态提示           |
+| 成功     | ✅    | 渲染成功提示               |
+| 错误     | ❌    | 渲染失败（含具体错误原因） |
+## 常见问题排查
+### 1. 控制台报404错误：无法加载config.json
+- 原因：未用本地服务器打开页面，浏览器跨域策略阻止加载本地文件；
+- 解决：使用VS Code Live Server/Node.js Express等本地服务器打开，确保JSON文件可通过服务器访问。
+### 2. 控制台报错：prop.replaceCamelCase is not a function
+- 原因：styles节点中存在**非字符串类型的属性名**（如数字、null）；
+- 解决：校验JSON语法，确保所有属性名为**双引号包裹的字符串**，删除无效属性。
+### 3. 样式未渲染/内容未注入
+- 检查选择器：HTML中的DOM选择器与JSON中的键**严格一致**（区分大小写、类名前缀`.`）；
+- 检查JSON语法：确保无语法错误（如缺少引号、大括号，逗号结尾）；
+- 检查日志：根据控制台日志判断配置文件是否被正确加载。
+### 4. 浏览器标签页报favicon.ico 404
+- 原因：浏览器默认在项目根目录找网站小图标，未找到则报404；
+- 解决：下载`favicon.ico`图标放到项目根目录，或在HTML的`<head>`中通过`<link rel="icon">`指定PNG/SVG图标。
+## 开发与打包
+### 1. 克隆源码
+```bash
+git clone https://github.com/你的GitHub用户名/xiangjsoncraft.git
+cd xiangjsoncraft
+```
+### 2. 安装开发依赖
+```bash
+npm install
+```
+### 3. 打包构建
+使用Rollup打包为**UMD格式**（兼容模块化、CDN全局调用、CommonJS），打包后输出到`dist`目录：
+```bash
+npm run build
+```
+### 4. 本地测试
+打包后，可将`dist`目录中的`xiangjsoncraft.umd.js`与示例`index.html`、`config.json`放在一起，通过本地服务器测试。
+## 版本更新日志
+### v1.2.0（最新稳定版）
+- 核心优化：**本地config.json永远最高优先级**，兼容CDN/本地引入两种方式；
+- 全量容错：过滤无效选择器、非字符串属性名、空属性值，单个配置错误不影响整体渲染；
+- 样式优化：生成的CSS自动格式化（带缩进），易调试，样式块插入到head最前面避免被覆盖；
+- 体验优化：新增友好控制台日志，区分配置加载状态、渲染成功/失败；
+- 细节完善：支持SVG/PNG网站小图标，解决favicon.ico 404问题；
+- 兼容优化：暴露全局变量`window.XiangJsonCraft`，CDN引入可直接全局调用。
+### v1.1.1
+- 首次正式发布，实现核心JSON解耦渲染功能；
+- 支持CDN/本地引入，基本样式和内容渲染；
+- 支持驼峰属性自动转换，媒体查询、伪类样式。
+## 开源协议
+MIT License - 详见项目根目录`LICENSE`文件，可自由使用、修改、分发，无需授权。
+## 官方地址
+- NPM：https://www.npmjs.com/package/xiangjsoncraft
+- Github:https://github.com/dxiangwiki/xiangjsoncraft
+## 问题反馈
+若使用过程中遇到问题，可在GitHub仓库提交Issue，或通过NPM包主页留言，会及时响应并修复。

package/config.json CHANGED Viewed

@@ -1,218 +1,113 @@
 {
     "styles": {
         "*": {
-            "margin": "0",
-            "padding": "0",
+            "margin": 0,
+            "padding": 0,
             "boxSizing": "border-box",
-            "fontFamily": "'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif"
+            "fontFamily": "Segoe UI, Roboto, 微软雅黑, sans-serif"
         },
         "body": {
             "backgroundColor": "#f0f4f8",
             "color": "#334e68",
             "lineHeight": "1.6",
-            "transition": "backgroundColor 0.5s ease",
-            "minHeight": "100vh"
+            "minHeight": "100vh",
+            "padding": "2rem 1rem"
         },
         ".welcome-container": {
             "maxWidth": "1200px",
             "margin": "0 auto",
-            "padding": "20px"
-        },
-        ".welcome-header": {
-            "textAlign": "center",
-            "padding": "60px 20px",
-            "marginBottom": "40px",
-            "borderRadius": "12px",
-            "background": "linear-gradient(135deg, #4299e1, #63b3ed)",
-            "color": "white",
-            "boxShadow": "0 10px 25px -5px rgba(66, 153, 225, 0.3)",
-            "transition": "transform 0.5s ease, boxShadow 0.5s ease"
-        },
-        ".welcome-header:hover": {
-            "transform": "translateY(-5px)",
-            "boxShadow": "0 15px 30px -8px rgba(66, 153, 225, 0.4)"
-        },
-        ".logo-container": {
-            "marginBottom": "30px"
-        },
-        ".logo": {
-            "width": "120px",
-            "height": "120px",
-            "margin": "0 auto",
-            "backgroundColor": "white",
-            "borderRadius": "50%",
-            "display": "flex",
-            "alignItems": "center",
-            "justifyContent": "center",
-            "fontSize": "48px",
-            "color": "#4299e1",
-            "boxShadow": "0 4px 12px rgba(0, 0, 0, 0.1)"
-        },
-        ".logo::after": {
-            "content": "'J'",
-            "fontWeight": "bold"
+            "padding": "2rem"
         },
         ".main-title": {
-            "fontSize": "2.5rem",
-            "marginBottom": "15px",
-            "textShadow": "0 2px 4px rgba(0, 0, 0, 0.1)"
-        },
-        "@media (maxWidth: 768px)": {
-            ".main-title": {
-                "fontSize": "2rem"
-            }
+            "fontSize": "2.2rem",
+            "color": "#2d3748",
+            "textAlign": "center",
+            "marginBottom": "1.5rem",
+            "fontWeight": 700
         },
         ".subtitle": {
             "fontSize": "1.1rem",
-            "opacity": "0.9",
-            "maxWidth": "600px",
-            "margin": "0 auto"
-        },
-        ".features-section": {
-            "display": "grid",
-            "gridTemplateColumns": "repeat(auto-fit, minmax(300px, 1fr))",
-            "gap": "30px",
-            "marginBottom": "60px"
+            "color": "#718096",
+            "textAlign": "center",
+            "maxWidth": "800px",
+            "margin": "0 auto 3rem",
+            "lineHeight": "1.8"
         },
         ".feature-card": {
-            "backgroundColor": "white",
+            "backgroundColor": "#ffffff",
             "borderRadius": "12px",
-            "padding": "30px",
-            "boxShadow": "0 4px 12px rgba(0, 0, 0, 0.05)",
+            "padding": "2rem",
+            "boxShadow": "0 4px 12px rgba(0,0,0,0.05)",
+            "maxWidth": "600px",
+            "margin": "0 auto 2rem",
             "transition": "transform 0.3s ease, boxShadow 0.3s ease"
         },
         ".feature-card:hover": {
-            "transform": "translateY(-8px)",
-            "boxShadow": "0 12px 20px rgba(0, 0, 0, 0.08)"
-        },
-        ".feature-icon": {
-            "width": "60px",
-            "height": "60px",
-            "borderRadius": "12px",
-            "backgroundColor": "#ebf8ff",
-            "color": "#4299e1",
-            "display": "flex",
-            "alignItems": "center",
-            "justifyContent": "center",
-            "fontSize": "24px",
-            "marginBottom": "20px"
+            "transform": "translateY(-6px)",
+            "boxShadow": "0 8px 20px rgba(0,0,0,0.08)"
         },
         ".feature-title": {
-            "fontSize": "1.3rem",
-            "marginBottom": "15px",
-            "color": "#2d3748"
+            "fontSize": "1.4rem",
+            "color": "#4299e1",
+            "marginBottom": "1rem",
+            "fontWeight": 600
         },
-        ".feature-description": {
+        ".feature-desc": {
             "color": "#718096",
             "lineHeight": "1.7"
         },
-        ".action-section": {
+        ".primary-btn": {
+            "display": "block",
+            "width": "200px",
+            "height": "50px",
+            "lineHeight": "50px",
             "textAlign": "center",
-            "marginBottom": "80px"
-        },
-        ".primary-button": {
             "backgroundColor": "#4299e1",
-            "color": "white",
+            "color": "#ffffff",
             "border": "none",
             "borderRadius": "8px",
-            "padding": "14px 32px",
+            "margin": "0 auto",
             "fontSize": "1rem",
-            "fontWeight": "600",
+            "fontWeight": 600,
             "cursor": "pointer",
-            "transition": "all 0.3s ease",
-            "boxShadow": "0 4px 6px rgba(66, 153, 225, 0.2)"
+            "transition": "backgroundColor 0.3s ease, transform 0.2s ease"
         },
-        ".primary-button:hover": {
+        ".primary-btn:hover": {
             "backgroundColor": "#3182ce",
-            "transform": "translateY(-2px)",
-            "boxShadow": "0 6px 10px rgba(66, 153, 225, 0.3)"
+            "transform": "translateY(-2px)"
         },
-        ".additional-info": {
-            "marginTop": "15px",
-            "color": "#718096",
-            "fontSize": "0.95rem"
-        },
-        ".page-footer": {
-            "textAlign": "center",
-            "paddingTop": "30px",
-            "borderTop": "1px solid #e2e8f0",
-            "color": "#718096"
-        },
-        ".copyright": {
-            "marginBottom": "15px",
-            "fontSize": "0.9rem"
-        },
-        ".social-links": {
-            "display": "flex",
-            "justifyContent": "center",
-            "gap": "15px"
-        },
-        ".social-icon": {
-            "color": "#718096",
-            "fontSize": "1.2rem",
-            "transition": "color 0.3s ease"
-        },
-        ".social-icon:hover": {
-            "color": "#4299e1"
-        },
-        "body:not(.loaded) .welcome-header": {
-            "opacity": "0",
-            "transform": "translateY(20px)"
-        },
-        "body.loaded .welcome-header": {
-            "opacity": "1",
-            "transform": "translateY(0)",
-            "transition": "opacity 0.8s ease, transform 0.8s ease"
-        },
-        "body:not(.loaded) .feature-card": {
-            "opacity": "0",
-            "transform": "scale(0.95)"
-        },
-        "body.loaded .feature-card": {
-            "opacity": "1",
-            "transform": "scale(1)",
-            "transition": "opacity 0.6s ease, transform 0.6s ease"
-        },
-        "body.loaded .feature-card:nth-child(1)": { "transitionDelay": "0.2s" },
-        "body.loaded .feature-card:nth-child(2)": { "transitionDelay": "0.4s" },
-        "body.loaded .feature-card:nth-child(3)": { "transitionDelay": "0.6s" }
-    },
-    "content": {
-        ".main-title": "Welcome to xiangjsoncraft",
-        ".subtitle": "Create beautiful web pages with simple JSON configuration",
-        ".primary-button": "Get Started",
-        ".additional-info": "Join thousands of developers using our JSON configuration system",
-        ".copyright": "© 2025 Dong Xiang. All rights reserved."
-    },
-    "features": {
-        "selectorPrefix": "#feature",
-        "items": [
-            {
-                "iconClass": "fas fa-code",
-                "title": "Simple Configuration",
-                "description": "Define your entire page style and content with easy-to-understand JSON"
+        "@media (max-width: 768px)": {
+            ".main-title": {
+                "fontSize": "1.8rem"
             },
-            {
-                "iconClass": "fas fa-paint-brush",
-                "title": "Beautiful Designs",
-                "description": "Create stunning interfaces without writing complex CSS code"
+            ".welcome-container": {
+                "padding": "1rem"
             },
-            {
-                "iconClass": "fas fa-mobile-alt",
-                "title": "Responsive by Default",
-                "description": "Your pages will look great on all devices with built-in responsiveness"
+            ".feature-card": {
+                "padding": "1.5rem"
             }
-        ]
+        }
     },
-    "icons": {
-        "selector": ".social-links",
-        "items": [
-            { "class": "fab fa-github", "url": "#" },
-            { "class": "fab fa-twitter", "url": "#" },
-            { "class": "fab fa-linkedin", "url": "#" },
-            { "class": "fab fa-instagram", "url": "#" }
-        ]
+    "content": {
+        ".main-title": {
+            "value": "XiangJsonCraft 测试页面",
+            "isHtml": false
+        },
+        ".subtitle": {
+            "value": "基于JSON配置渲染的页面，无需手写CSS，修改JSON即可定制样式和内容！",
+            "isHtml": false
+        },
+        ".feature-title": {
+            "value": "核心特色：JSON解耦",
+            "isHtml": false
+        },
+        ".feature-desc": {
+            "value": "HTML仅负责搭建DOM骨架，样式、内容全由JSON控制，后期维护只需修改JSON，无需触碰HTML/JS代码。",
+            "isHtml": false
+        },
+        ".primary-btn": {
+            "value": "<span onclick=\"window.open('https://www.npmjs.com/package/xiangjsoncraft', '_blank')\">点我查看 NPM 包地址</span>",
+            "isHtml": true
+        }
     }
-}
+}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "xiangjsoncraft",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "简单而强大的JSON配置与HTML页面渲染工具，支持任意CSS选择器、响应式设计、HTML内容动态注入，轻量无依赖",
   "main": "dist/xiangjsoncraft.cjs.js",
   "module": "dist/xiangjsoncraft.esm.js",

package/renderJson.js CHANGED Viewed

@@ -1,82 +1,133 @@
-// 封装通用JSON样式渲染函数，支持任意CSS选择器、HTML内容、媒体查询（v1.1.0核心功能）
+// 为String原型扩展驼峰转短横线方法，用于CSS属性名转换
+String.prototype.replaceCamelCase = function (separator = '-') {
+    // 容错：如果是纯数字/无驼峰的字符串，直接返回
+    return this.replace(/[A-Z]/g, (match) => `${separator}${match.toLowerCase()}`);
+};
+// 创建样式块并添加到文档头部，确保唯一且不重复创建
+function createStyleBlock() {
+    const style = document.createElement('style');
+    style.id = 'dynamic-styles';
+    // 把样式块插入到head最前面，避免被其他样式覆盖
+    document.head.insertBefore(style, document.head.firstChild);
+    return style;
+}
+// 核心渲染函数：本地config.json最高优先级，CDN配置兜底，全量容错
 export function renderJsonStyles() {
-    // 核心原则：本地config.json永远最高优先级，加载失败再用CDN官方配置
-    const localConfigUrl = './config.json'; // 本地用户自定义配置
-    const cdnConfigUrl = 'https://cdn.jsdelivr.net/npm/xiangjsoncraft@1.1.1/config.json'; // CDN兜底配置
-    // 先尝试加载本地config.json
-    fetch(localConfigUrl)
-        .then(response => {
-            // 本地配置存在（状态码200），则使用本地配置
-            if (response.ok) {
+    // 配置地址：本地自定义（最高优先级） + CDN官方兜底
+    const LOCAL_CONFIG = './config.json';
+    const CDN_CONFIG = 'https://cdn.jsdelivr.net/npm/xiangjsoncraft@1.1.1/config.json';
+    // 统一错误处理函数，避免单个错误中断整体渲染
+    const handleError = (msg) => {
+        console.error(`❌ XiangJsonCraft 错误: ${msg}`);
+    };
+    // 核心逻辑：先加载本地配置，失败则加载CDN兜底配置
+    fetch(LOCAL_CONFIG)
+        .then(async (res) => {
+            // 本地配置存在（状态码200-299），使用本地配置
+            if (res.ok) {
                 console.log('🔧 检测到本地config.json，优先加载用户自定义配置');
-                return response.json();
+                return res.json();
             }
-            // 本地配置不存在/加载失败，切换到CDN兜底配置
+            // 本地配置不存在/加载失败，切换到CDN配置
             console.log('ℹ️  本地未检测到config.json，加载CDN官方示例配置');
-            return fetch(cdnConfigUrl).then(res => {
-                if (!res.ok) throw new Error('CDN官方配置加载失败');
-                return res.json();
-            });
+            const cdnRes = await fetch(CDN_CONFIG);
+            if (!cdnRes.ok) throw new Error('CDN官方配置加载失败，请检查网络');
+            return cdnRes.json();
         })
-        .then(config => {
-            // 获取或创建样式块，避免重复创建
+        .then((config) => {
+            // 容错：如果配置不是对象，直接终止渲染
+            if (typeof config !== 'object' || config === null || Array.isArray(config)) {
+                return handleError('配置文件格式错误，必须是标准JSON对象');
+            }
+            // 获取/创建样式块，确保渲染容器存在
             const styleBlock = document.getElementById('dynamic-styles') || createStyleBlock();
-            if (!styleBlock) return console.error('❌ 样式块创建失败，无法渲染样式');
+            if (!styleBlock) return handleError('样式块创建失败，无法渲染CSS');
-            // 生成CSS规则
+            // 生成CSS规则：处理styles节点，全量容错+格式美化
             let cssRules = '';
+            const { styles = {} } = config; // 解构赋值，避免styles未定义
-            // 处理所有选择器样式（支持任意CSS选择器、媒体查询）
-            if (config.styles && typeof config.styles === 'object' && Object.keys(config.styles).length > 0) {
-                // 遍历所有选择器（类、ID、伪类、媒体查询等）
-                Object.entries(config.styles).forEach(([selector, styles]) => {
-                    // 过滤空样式，避免无效CSS
-                    if (!styles || typeof styles !== 'object') return;
-                    // 生成该选择器的所有样式属性
-                    const styleProperties = Object.entries(styles)
-                        .map(([prop, value]) => {
-                            // 过滤空属性，驼峰式属性名转换为CSS标准格式
-                            if (!prop || value === undefined || value === null) return '';
-                            const cssProp = prop.replaceCamelCase();
-                            return `${cssProp}: ${value};`;
-                        })
-                        .filter(Boolean) // 移除空属性
-                        .join('\n    ');
-                    // 仅当有样式属性时，添加到CSS规则
-                    if (styleProperties) {
-                        cssRules += `${selector} {\n    ${styleProperties}\n}\n\n`;
-                    }
-                });
-            }
+            // 遍历所有CSS选择器（支持类、ID、媒体查询等所有合法选择器）
+            Object.entries(styles).forEach(([selector, styleObj]) => {
+                // 容错1：选择器为空/非字符串，跳过
+                const selectorStr = String(selector).trim();
+                if (!selectorStr) return;
+                // 容错2：选择器对应的不是样式对象，跳过
+                if (typeof styleObj !== 'object' || styleObj === null || Array.isArray(styleObj)) return;
+                // 处理单个选择器下的所有样式属性
+                const styleProps = Object.entries(styleObj)
+                    .map(([prop, value]) => {
+                        // 容错3：属性名强制转字符串+去空格，空属性直接跳过
+                        const propStr = String(prop).trim();
+                        if (!propStr) return '';
+                        // 容错4：属性值为空/无效，直接跳过
+                        if (value === undefined || value === null || String(value).trim() === '') return '';
+                        // 驼峰属性名转CSS标准短横线（如fontSize → font-size）
+                        const cssProp = propStr.replaceCamelCase();
+                        // 属性值强制转字符串，避免数字/布尔值渲染异常
+                        const cssValue = String(value).trim();
+                        // 返回合法的CSS属性行
+                        return `${cssProp}: ${cssValue};`;
+                    })
+                    .filter(Boolean) // 过滤所有空字符串，只留合法属性
+                    .join('\n    '); // 拼接成带缩进的整洁CSS
+                // 只有当有合法样式属性时，才生成CSS规则，避免空选择器
+                if (styleProps) {
+                    cssRules += `${selectorStr} {\n    ${styleProps}\n}\n\n`;
+                }
+            });
-            // 应用生成的CSS规则到样式块
+            // 将生成的CSS注入到样式块，覆盖原有内容（避免重复渲染）
             if (cssRules) {
                 styleBlock.innerHTML = cssRules;
             }
-            // 处理内容配置（支持纯文本/HTML内容，通过isHtml标识）
-            if (config.content && typeof config.content === 'object' && Object.keys(config.content).length > 0) {
-                Object.entries(config.content).forEach(([selector, content]) => {
-                    // 过滤无效选择器和内容
-                    if (!selector || !content || !content.hasOwnProperty('value')) return;
-                    const elements = document.querySelectorAll(selector);
-                    elements.forEach(el => {
-                        if (!el) return;
-                        // 支持HTML内容或纯文本，默认纯文本
-                        if (content.isHtml) {
-                            el.innerHTML = content.value;
-                        } else {
-                            el.textContent = content.value;
-                        }
-                    });
+            // 渲染内容：处理content节点，向DOM注入文本/HTML
+            const { content = {} } = config; // 解构赋值，避免content未定义
+            Object.entries(content).forEach(([selector, contentObj]) => {
+                // 容错1：选择器为空/非字符串，跳过
+                const selectorStr = String(selector).trim();
+                if (!selectorStr) return;
+                // 容错2：内容配置不是对象，跳过
+                if (typeof contentObj !== 'object' || contentObj === null || Array.isArray(contentObj)) return;
+                // 容错3：缺少核心的value属性，跳过
+                if (!contentObj.hasOwnProperty('value')) return;
+                // 获取要注入内容的DOM节点，容错：节点不存在则跳过
+                const targetNodes = document.querySelectorAll(selectorStr);
+                if (targetNodes.length === 0) return;
+                // 解析内容配置：isHtml默认为false（纯文本）
+                const { value, isHtml = false } = contentObj;
+                const contentValue = String(value).trim(); // 内容强制转字符串，避免异常
+                // 向所有匹配的DOM节点注入内容
+                targetNodes.forEach((node) => {
+                    if (isHtml) {
+                        node.innerHTML = contentValue; // HTML片段渲染
+                    } else {
+                        node.textContent = contentValue; // 纯文本渲染（防XSS）
+                    }
                 });
-            }
+            });
-            console.log('✅ XiangJsonCraft v1.1.1 渲染成功！');
+            // 渲染成功，打印友好提示
+            console.log('✅ XiangJsonCraft 渲染成功！样式+内容已全部加载');
         })
-        .catch(error => {
-            console.error('❌ XiangJsonCraft 处理配置时出错:', error.message);
+        .catch((err) => {
+            // 捕获所有异步错误，统一处理
+            handleError(err.message);
         });
+}
+// 兼容UMD打包：暴露全局变量，方便CDN引入调用
+if (typeof window !== 'undefined') {
+    window.XiangJsonCraft = { renderJsonStyles };
 }