xiangjsoncraft

v2.0.5

Published

a month ago

XiangJsonCraft 2.0 - 纯JSON驱动的轻量级前端框架

Downloads

0High
0Medium
0Low

dongxiang678

XiangJsonCraft 2.0.4

Write JSON, Get a Website. | 零CSS、零JS、纯JSON驱动的轻量前端框架

由董翔开发的一款从「JSON渲染工具」升级而来的完整前端微框架，无需编写任何CSS、JS代码，仅通过编辑JSON配置文件，即可快速构建美观、响应式、带交互的完整网页，大幅降低前端开发门槛，非前端开发者也能轻松上手。

📢 重大升级说明（从 1.x → 2.0.0）

XiangJsonCraft 2.0.0 是一次 不兼容的重大版本升级 —— 从简单的「JSON渲染工具函数」，正式升级为「完整前端框架 + 官方脚手架」，保留1.x核心优势并全面强化，彻底改变使用方式、提升产品定位。

🔄 新旧版本核心差异

| 对比维度 | 1.x 版本（工具） | 2.0.0 版本（框架） | | -------- | ----------------------------------- | ---------------------------------------------- | | 产品定位 | JSON渲染工具函数 | 纯JSON驱动前端框架 | | 使用方式 | 手动创建HTML/JS，引入工具包调用函数 | 脚手架一键创建完整项目，仅改JSON | | 核心能力 | 基础JSON样式+内容渲染 | 样式+内容+交互+响应式+脚手架全支持 | | 依赖管理 | 需手动引入、手动管理依赖 | 脚手架自动安装、自动引入，无需手动操作 | | 项目结构 | 无固定结构，需手动搭建 | 标准化项目结构，自动生成所有必要文件 | | 兼容性 | 仅支持模块化引入 | 兼容模块化/非模块化环境，适配所有现代浏览器 | | 可维护性 | 需手动维护HTML/JS与JSON的关联 | HTML仅存骨架，所有配置集中在JSON，维护成本极低 |

✅ 保留的1.x核心功能（全部继承并优化）

JSON与HTML解耦：HTML仅负责DOM骨架，样式、内容完全由JSON控制
CSS属性驼峰转短横线：支持驼峰命名（如boxSizing），自动转换为CSS标准写法（box-sizing）
强容错性：过滤无效配置、空属性、不存在的选择器，单个错误不影响整体渲染
内容渲染支持：同时支持纯文本渲染（防XSS）和HTML片段渲染，满足复杂内容需求
CSS全兼容：支持所有合法CSS选择器（类、ID、全局*）、伪类、属性，无额外学习成本
轻量无依赖：核心代码仅百行级，打包后体积极小，不占用多余项目资源

🔥 2.0.0 新增核心功能（框架级升级）

官方脚手架：支持 npm create xiangjsoncraft@latest 一键创建项目，零手动配置
多模板支持：内置「基础模板」「完整模板」「空模板」，适配不同使用场景（快速上手/复杂开发/自定义搭建）
交互能力强化：支持在JSON中直接配置JS原生事件（如onclick），无需编写额外JS即可实现简单交互
响应式优化：内置响应式示例配置，支持@media媒体查询，一键适配移动端/PC端
标准化项目结构：自动生成index.html、config.json、package.json、README.md，规范开发流程
自动依赖管理：脚手架自动安装框架依赖，自动完成框架引入，无需手动下载、引入文件
友好控制台日志：区分信息、成功、错误日志，清晰提示配置加载状态、渲染结果和问题原因，便于排查
全局变量暴露：兼容非模块化环境，CDN引入可直接全局调用，适配更多部署场景
部署简化：无需打包，直接上传项目文件即可上线，降低部署门槛
样式注入优化：样式块自动插入到head最前面，避免被其他样式覆盖，提升渲染稳定性

🚀 快速开始（2.0.0 唯一使用方式）

2.0.0 彻底废弃1.x的「手动引入工具包」用法，统一为脚手架一键创建，步骤极简：

方式1：使用 npm create（推荐）

# 快速创建项目（默认项目名：xiangjsoncraft-app）
npm create xiangjsoncraft@latest

# 指定项目名称创建（推荐）
npm create xiangjsoncraft@latest my-json-app

方式2：使用 npx 直接调用

# 直接创建项目
npx create-xiangjsoncraft

# 指定项目名称
npx create-xiangjsoncraft my-json-app

方式3：全局安装后使用

# 全局安装脚手架
npm install -g xiangjsoncraft

# 创建项目
create-xiangjsoncraft my-json-app

项目启动步骤

# 1. 进入项目目录（替换为你的项目名）
cd my-json-app

# 2. 启动开发服务器（脚手架已自动配置脚本）
npm run start

# 3. 访问页面
# 打开浏览器访问 http://localhost:3000（默认端口，具体以终端提示为准）

核心操作：自定义项目

启动项目后，无需修改任何HTML/JS文件，仅需编辑项目根目录的 config.json，即可自定义所有样式、内容和交互，修改后刷新浏览器即可生效。

📋 项目结构（2.0.0 标准化结构）

脚手架创建的项目结构清晰，所有可配置内容集中在config.json，无需关注其他文件：

my-json-app/          # 你的项目根目录
├─ index.html         # DOM骨架（固定不变，无需修改）
├─ config.json        # 核心配置文件（样式+内容+交互，唯一需要编辑的文件）
├─ package.json       # 项目配置（自动生成，可修改脚本/依赖）
└─ README.md          # 项目说明（自动生成，含使用指南）

各文件说明

index.html：仅包含DOM骨架，定义页面基础结构（如容器、标题、按钮），选择器与config.json严格对应，无需修改
config.json：框架核心配置文件，包含styles（样式）、content（内容）两个核心节点，所有自定义都在这里完成
package.json：自动生成项目配置，包含启动脚本（npm run start）和框架依赖，可根据需求修改
README.md：自动生成项目使用指南，包含启动命令、配置说明，便于团队协作和后续维护

⚙️ 核心配置详解（config.json）

config.json 是框架的核心，包含 styles（样式配置）和 content（内容配置）两个必填节点，语法遵循标准JSON规范（推荐用 JSON.cn 校验语法）。

1. 整体配置结构

{
  "framework": "XiangJsonCraft 2.0",  // 框架标识（可选，仅用于识别）
  "styles": { /* 样式配置（核心） */ },  // 所有CSS样式都在这里配置
  "content": { /* 内容配置（核心） */ }  // 所有页面内容都在这里配置
}

2. styles 节点（样式配置）

用于定义所有页面CSS样式，完全兼容CSS语法，支持所有合法选择器和属性，仅需用JSON格式编写即可。

核心规则

键（key）：CSS选择器（支持类、ID、全局*、伪类、媒体查询，如 .app-title、#btn、.box:hover、@media (max-width: 768px)）
值（value）：样式对象，键为CSS属性（支持驼峰命名），值为CSS属性值
容错机制：空选择器、非对象样式、空属性、无效属性值会被自动过滤，不影响整体渲染
驼峰转换：属性名支持驼峰（如fontSize、backgroundColor），框架会自动转换为CSS标准短横线写法（font-size、background-color）

示例配置

"styles": {
  "*": {  // 全局样式（所有元素生效）
    "margin": 0,
    "padding": 0,
    "boxSizing": "border-box",  // 驼峰命名，自动转为box-sizing
    "fontFamily": "Segoe UI, Roboto, 微软雅黑, sans-serif"
  },
  "body": {  // body标签样式
    "backgroundColor": "#f0f4f8",
    "color": "#334e68",
    "lineHeight": "1.6",
    "minHeight": "100vh"
  },
  ".app-title": {  // 类选择器样式
    "fontSize": "2rem",
    "color": "#2d3748",
    "textAlign": "center",
    "marginBottom": "1.5rem",
    "transition": "color 0.3s ease"
  },
  ".app-title:hover": {  // 伪类样式
    "color": "#4299e1"
  },
  "@media (max-width: 768px)": {  // 响应式样式（移动端适配）
    ".app-title": {
      "fontSize": "1.8rem"
    }
  }
}

3. content 节点（内容配置）

用于向HTML中的DOM节点注入文本或HTML内容，键为与HTML对应的选择器，值为内容配置对象，支持纯文本和HTML两种渲染方式。

内容配置对象属性

| 属性名 | 类型 | 是否必选 | 默认值 | 说明 | | ------ | -------- | -------- | ------ | ---------------------------------------------------------------------- | | value | 任意类型 | 是 | - | 要注入的文本或HTML内容，框架会自动转为字符串处理 | | isHtml | Boolean | 否 | false | true：以HTML格式渲染（支持标签和JS事件）；false：以纯文本渲染（防XSS） |

示例配置

"content": {
  ".app-title": {  // 对应HTML中的 <h1 class="app-title"></h1>
    "value": "XiangJsonCraft 2.0 示例",
    "isHtml": false  // 纯文本渲染
  },
  ".app-desc": {  // 对应HTML中的 <p class="app-desc"></p>
    "value": "仅修改config.json，即可实现全页面自定义！",
    "isHtml": false
  },
  ".app-btn": {  // 对应HTML中的 <a class="app-btn"></a>
    "value": "<span onclick=\"alert('点击成功！')\">点击我</span>",
    "isHtml": true  // HTML渲染，支持JS事件
  }
}

📌 完整配置示例（config.json）

{
  "framework": "XiangJsonCraft 2.0",
  "styles": {
    "*": {
      "margin": 0,
      "padding": 0,
      "boxSizing": "border-box",
      "fontFamily": "Segoe UI, Roboto, 微软雅黑, sans-serif"
    },
    "body": {
      "backgroundColor": "#f0f4f8",
      "color": "#334e68",
      "lineHeight": "1.6",
      "minHeight": "100vh",
      "padding": "2rem 1rem"
    },
    ".app-container": {
      "maxWidth": "1200px",
      "margin": "0 auto",
      "backgroundColor": "#ffffff",
      "padding": "2rem",
      "borderRadius": "12px",
      "boxShadow": "0 4px 20px rgba(0,0,0,0.05)",
      "transition": "all 0.3s ease"
    },
    ".app-container:hover": {
      "boxShadow": "0 8px 30px rgba(0,0,0,0.1)"
    },
    ".app-title": {
      "fontSize": "2.2rem",
      "color": "#2d3748",
      "textAlign": "center",
      "marginBottom": "1.5rem",
      "transition": "color 0.3s ease"
    },
    ".app-title:hover": {
      "color": "#4299e1"
    },
    ".app-desc": {
      "fontSize": "1.1rem",
      "marginBottom": "2rem",
      "textAlign": "center",
      "maxWidth": "600px",
      "marginLeft": "auto",
      "marginRight": "auto"
    },
    ".app-btn-group": {
      "display": "flex",
      "justifyContent": "center",
      "gap": "1rem",
      "flexWrap": "wrap"
    },
    ".app-btn": {
      "display": "inline-block",
      "padding": "12px 24px",
      "backgroundColor": "#4299e1",
      "color": "#ffffff",
      "borderRadius": "8px",
      "textDecoration": "none",
      "cursor": "pointer",
      "transition": "all 0.3s ease"
    },
    ".app-btn:hover": {
      "backgroundColor": "#3182ce",
      "transform": "translateY(-2px)"
    },
    ".app-btn-secondary": {
      "backgroundColor": "#718096"
    },
    ".app-btn-secondary:hover": {
      "backgroundColor": "#4a5568"
    },
    "@media (max-width: 768px)": {
      ".app-container": {
        "padding": "1rem",
        "margin": "0 0.5rem"
      },
      ".app-title": {
        "fontSize": "1.8rem"
      },
      ".app-btn-group": {
        "flexDirection": "column",
        "alignItems": "center"
      }
    }
  },
  "content": {
    ".app-title": {
      "value": "XiangJsonCraft 2.0 完整示例",
      "isHtml": false
    },
    ".app-desc": {
      "value": "纯JSON驱动的前端框架，无需写CSS/JS，修改JSON即可完成所有开发！",
      "isHtml": false
    },
    ".app-btn": {
      "value": "<span onclick=\"alert('主按钮被点击！')\">主按钮</span>",
      "isHtml": true
    },
    ".app-btn-secondary": {
      "value": "<span onclick=\"alert('次按钮被点击！')\">次按钮</span>",
      "isHtml": true
    }
  }
}

🔧 常见问题排查

1. 控制台报 404 错误：无法加载 config.json

原因：未使用本地服务器打开页面，浏览器跨域策略阻止加载本地JSON文件（直接双击HTML文件会触发此问题）
解决：使用 VS Code Live Server、Node.js Express 等本地服务器打开项目，确保JSON文件可通过服务器访问

2. 样式未渲染 / 内容未注入

检查选择器：HTML中的DOM选择器与config.json中的键必须严格一致（区分大小写、类名前缀.、ID前缀#）
检查JSON语法：确保config.json无语法错误（如缺少引号、大括号、逗号结尾），可通过JSON.cn校验
检查日志：查看浏览器控制台日志，确认框架是否渲染成功、配置是否被正确加载

3. 依赖安装失败

原因：网络问题、npm镜像问题，或本地npm版本过低
解决：手动进入项目目录，执行npm install 重新安装；或切换npm镜像（如npm config set registry https://registry.npm.taobao.org）

4. 控制台报错：prop.replaceCamelCase is not a function

原因：styles节点中存在非字符串类型的属性名（如数字、null、数组）
解决：校验config.json，确保styles节点下所有属性名均为双引号包裹的字符串，删除无效属性

5. 浏览器报 favicon.ico 404

原因：浏览器默认在项目根目录查找网站小图标，未找到则报404（不影响项目功能）
解决：下载favicon.ico图标放到项目根目录，或在HTML的中通过指定PNG/SVG图标

📦 框架开发与打包（开发者指南）

若你需要修改框架核心逻辑、二次开发，可按照以下步骤操作：

1. 克隆源码

git clone https://github.com/dxiangwiki/xiangjsoncraft.git
cd xiangjsoncraft

2. 安装开发依赖

npm install

3. 修改核心逻辑

框架核心渲染逻辑：src/renderJson.js
脚手架逻辑：bin/create.js
项目模板：template/ 目录下的所有文件
打包配置：rollup.config.js

4. 打包框架核心

npm run build

打包后会在 dist/ 目录生成 xiangjsoncraft.umd.js（UMD格式，兼容模块化/非模块化环境）。

5. 本地测试

打包后，将dist/xiangjsoncraft.umd.js 与 template/ 目录下的文件放在一起，通过本地服务器测试渲染效果。

📤 发包步骤（2.0.0 正式发布）

# 1. 安装依赖（确保所有依赖已安装）
npm install

# 2. 打包框架核心（生成dist目录）
npm run build

# 3. 登录NPM（确保已注册NPM账号，且拥有包发布权限）
npm login

# 4. 发布2.0.0版本（--access public 确保公开可访问）
npm publish --access public

📜 版本更新日志

v2.0.0（最新稳定版 | 重大升级）

定位升级：从「JSON渲染工具」升级为「纯JSON驱动的轻量前端框架」，版本号直接跳至2.0.0，不兼容1.x版本
新增功能：官方脚手架、多模板支持、自动依赖管理、友好控制台日志、全局变量暴露、部署简化
能力强化：交互支持优化、响应式示例完善、样式注入优化、容错机制升级
体验优化：标准化项目结构、自动生成使用文档、清晰的控制台提示、简化开发流程
继承保留：1.x版本的核心渲染能力、驼峰转短横线、强容错性、CSS全兼容等优势

v1.1.1 ~ v1.2.0（工具版本）

v1.2.0：优化本地/CDN配置加载优先级，新增容错机制，完善控制台日志，支持SVG/PNG网站小图标
v1.1.1：首次正式发布，实现核心JSON样式+内容渲染，支持驼峰转短横线、CDN/本地引入，基本容错机制

⚖️ 开源协议

MIT License - 详见项目根目录 LICENSE 文件，可自由使用、修改、分发，无需授权，仅需保留开源协议声明。

🔗 官方地址

NPM：https://www.npmjs.com/package/xiangjsoncraft
Github：https://github.com/dxiangwiki/xiangjsoncraft

💬 问题反馈

若使用过程中遇到问题、有功能建议，可在GitHub仓库提交Issue，或通过NPM包主页留言，会及时响应并修复。

✨ 框架口号

Write JSON, Get a Website. | 只写 JSON，就能得到一个完整网站。

注意事项

live-server依赖存在部分老旧包警告，仅影响开发阶段，不影响框架核心渲染；
生产环境建议使用npm run start:clean或替换为 vite/nginx。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

XiangJsonCraft 2.0.4

📢 重大升级说明（从 1.x → 2.0.0）

🔄 新旧版本核心差异

✅ 保留的1.x核心功能（全部继承并优化）

🔥 2.0.0 新增核心功能（框架级升级）

🚀 快速开始（2.0.0 唯一使用方式）

方式1：使用 npm create（推荐）

方式2：使用 npx 直接调用

方式3：全局安装后使用

项目启动步骤

核心操作：自定义项目

📋 项目结构（2.0.0 标准化结构）

各文件说明

⚙️ 核心配置详解（config.json）

1. 整体配置结构

2. styles 节点（样式配置）

核心规则

示例配置

3. content 节点（内容配置）

内容配置对象属性

示例配置

📌 完整配置示例（config.json）

🔧 常见问题排查

1. 控制台报 404 错误：无法加载 config.json

2. 样式未渲染 / 内容未注入

3. 依赖安装失败

4. 控制台报错：prop.replaceCamelCase is not a function

5. 浏览器报 favicon.ico 404

📦 框架开发与打包（开发者指南）

1. 克隆源码

2. 安装开发依赖

3. 修改核心逻辑

4. 打包框架核心

5. 本地测试

📤 发包步骤（2.0.0 正式发布）

📜 版本更新日志

v2.0.0（最新稳定版 | 重大升级）

v1.1.1 ~ v1.2.0（工具版本）

⚖️ 开源协议

🔗 官方地址

💬 问题反馈

✨ 框架口号

注意事项