# z-data

**Repository Path**: funlang/z-data

## Basic Information

- **Project Name**: z-data
- **Description**: Z-data is an extremely lightweight zero configuration embedded mini front-end js framework.
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://www.funlang.org/z-data
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-15
- **Last Updated**: 2026-10-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# z-data

> 超轻量级、零配置、零依赖、无虚拟 DOM 的嵌入式前端框架。
> 无需编译, 直接写 H5 DOM, 用模板指令驱动视图, 用原子化 CSS 以内联方式完成全部样式。

[English](./README.md) | **简体中文**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![GitHub Repo](https://img.shields.io/badge/GitHub-Funlang%2Fz--data-blue.svg)](https://github.com/Funlang/z-data)

---

## 目录

- [项目简介](#项目简介)
- [特性](#特性)
- [快速开始](#快速开始)
- [安装](#安装)
- [在线示例与 Demo](#在线示例与-demo)
- [作用域 Scope](#作用域-scope)
- [模板指令 Template](#模板指令-template)
- [数据绑定 Data Binding](#数据绑定-data-binding)
- [class / style 语法糖](#class--style-语法糖)
- [原子化 CSS (Atomic CSS)](#原子化-css-atomic-css)
- [事件 Event](#事件-event)
- [动态属性 / 事件与自定义指令](#动态属性--事件与自定义指令)
- [变量 Variables](#变量-variables)
- [函数与 API](#函数与-api)
- [组件 Component (z-comp)](#组件-component-z-comp)
- [z-json 工具](#z-json-工具)
- [z-data studio (z-pen)](#z-data-studio-z-pen)
- [浏览器兼容性](#浏览器兼容性)
- [项目结构](#项目结构)
- [性能](#性能)
- [加入我们](#加入我们)
- [许可证](#许可证)

---

## 项目简介

z-data 是一个**极简的前端响应式框架**, 核心理念是:

- **没有虚拟 DOM**, 直接操作 H5 DOM, 性能极高。
- **零配置、零依赖、无需编译**, 一个 JS 文件即插即用。
- **嵌入式**, 可以与其他框架 (如 Vue、Alpine) 无缝共存。
- **模板指令**, 支持 `for / if / else / use` 等。
- **原子化 CSS**, 类 Tailwind 的规则引擎, 无需构建即可内联生成样式。
- **极致语法糖**, 对 `class` 和 `style` 特别友好。

z-data 通过 HTML 属性 (directive) 驱动视图与数据, 使用 `<template>` 标签做循环与条件分支, 配合一套完整的
`!`、`#`、`.`、`..`、`:`、`::`、`@` 等简洁标记完成绑定、样式、事件, 让开发者专注于 H5 DOM 本身。

项目主页: <https://funlang.org/z-data/>

---

## 特性

- 无虚拟 DOM, 直接操作 DOM, 性能优秀
- 零配置、零依赖、无需编译
- 极简超轻量: minify 约 8K, gzip 后小于 5K
- H5 模板技术, 支持 `for / if / else / use`
- 模板支持多根节点
- 支持双向数据绑定与事件
- 嵌入式, 可与 Vue、Alpine 等其他框架共存
- 丰富的语法糖, 对 `class` 和 `style` 特别友好
- **内置原子化 CSS (Atomic CSS) 引擎**, 无需 Tailwind / 构建工具即可内联使用
- 以 H5 DOM 为中心, 可直接在 HTML 中开发生产级应用

---

## 快速开始

```html
<script src="//cdn.jsdelivr.net/gh/Funlang/z-data@main/dist/z-data.min.js"></script>

<div z-data="{name:'hello-world.html',items:{i:1,j:2,k:3}}"
     #background=`silver`
>
    <template for='k:v,i in items' key=k>
        <template if=!i>
            <div :text=name
                 :style={fontSize:`200%`}
                 #color=`#fa0a`
            ></div>
            <div class=t0
                 :class={t1:true}
                 .t2
                 :k=k
            >[if !i] i=${i}</div>
        </template>
        <template else if='k=="j"'>
            <div :css.font-size=`120%`>[if k=="j"] k=${k}</div>
        </template>
        <template else>
            <div #font-weight=`bold`>[else] k=${k}</div>
        </template>
    </template>
</div>
```

> 说明: `#xxx=...`、`!xxx=...`、`..xxx=...` 等是内置的 style / class 语法糖, 详见下文。

---

## 安装

### CDN

```html
<script src="//cdn.jsdelivr.net/gh/Funlang/z-data@main/dist/z-data.min.js"></script>
```

构建产物位于 `dist/` 目录:

| 文件 | 说明 |
| --- | --- |
| `z-data.min.js` | 核心框架, 面向现代浏览器 |
| `z-data.js` | 核心框架 (未压缩) |
| `z-data.min.es2015.js` | 兼容 ES2015 环境 |
| `z-data.min.all.js` | 核心 + `z-json` 工具 + 原子化 CSS 完整能力 |

---

## 在线示例与 Demo

- **在线 demo (hello-world)**: <https://codepen.io/funlang/pen/NWdOQye>
- **TodoMVC**: <https://codepen.io/funlang/pen/ExZOGJy>
- **复杂数据绑定**: <https://codepen.io/funlang/pen/OJWrJep>
- **表单示例**: <https://funlang.org/z-data/?url=./test/z-data-form-demo.html>
- **组件示例**: <https://codepen.io/funlang/pen/ExZBPJL>、<https://codepen.io/funlang/pen/RwKzaOo>

### z-cloak 示例

防止 z-data 初始化前的闪烁, 配合 CSS `[z-cloak] { display: none }` 使用:

```html
z-data
<div z-cloak :z-cloak.attr=false>z-cloak example</div>

<style>
  [z-cloak] {
    display: none;
  }
</style>
```

---

## 作用域 Scope

- `z-data` 属性创建一个 ZData 作用域:

  ```html
  <tag z-data=...></tag>
  ```

- `z-data` 支持 `init` 函数, 在组件初始化时执行:

  ```html
  <tag z-data=... init=...></tag>
  ```

- `z-data` 表达式可以是一个函数表达式:

  ```html
  <tag z-data="(args=>{
      // some codes ...
      return {
        // some props ...
      }
    })()"></tag>

  <tag z-data="args=>{
      // some codes ...
      return {
        // some props ...
      }
    }"></tag>
  ```

- **z-data HTML 模块文件**: 文件以 `z-data` 开头, 内部 `<script>` 中 `return {...}` 即数据:

  ```html
  z-data
  <tag init=...></tag>

  <script>
    // some codes ...
    return {
      // some props ...
    }
  </script>
  ```

- `z-none` 关闭 ZData 作用域, 其内部节点会被 ZData 跳过:

  ```html
  <tag z-none>
    ...
  </tag>
  ```

- **与其他框架共存**: 在 ZData 根节点加 `x-ignore` (或目标框架关闭作用域的属性名) 即可与 Alpine 等共存;
  在其他框架根节点加 `z-none` 则跳过 ZData 处理:

  ```html
  <tag z-data=... x-ignore></tag>
  ```

---

## 模板指令 Template

### `for`

```html
<template for='k:v,i in ...' key=...></template>
```

ZData 依赖 `key` 做 diff。未指定 `key` 时, 优先用 `k`, 否则用 `v` 作为 key。`k : v , i` 均可部分省略:

```html
<template for='k:v,i in items'></template>
<template for='  v   in items'></template>
<template for='k:    in items'></template>
<template for='   ,i in items'></template>
<template for='k:v   in items'></template>
<template for='  v,i in items'></template>
<template for=items></template>
```

### `if / else`

```html
<template if=...></template>
<template else if=...></template>
<template else></template>
```

### `use`

复用模板片段:

```html
<z z-none>
    <template id=t1>
        <div>template id = t1</div>
    </template>
</z>

<template use=#t1></template>
```

---

## 数据绑定 Data Binding

`:` 做属性绑定, `::` 做双向绑定 (类似其他框架的 `v-model`):

```html
<tag :attr-name1=... ::attr-name2=...></tag>
```

### `:text` `:html`

分别对应 `textContent` 和 `innerHTML`。

### `:class`

支持 `[]`、`{}` 和字符串三种形式, 会按顺序合并到 classList:

```html
<div :class="['a', {b: true}, 'c d']"></div>
```

### `:class` 简写 (`.name`)

```html
<tag :class.name1.name2=...></tag>
```

可简写为 `.name1.name2=...`。若 classname 以 `-` 结尾且返回值不是 boolean, 会把值拼接到 classname,
例如 `.p-=1` 会给 classList 增加 `p-1`。

### `:style`

支持 `:css` 别名, 支持 `{}` 和字符串, 字符串按顺序覆盖:

```html
<tag :style="{fontSize: '20px'}"></tag>
<tag :css="'color:red'"></tag>
```

### `:style` 简写 (`..name` `#name` `!name`)

```html
<tag :style.name.value=...></tag>
```

- `:style.name=value` / `:css.name=value`
- `:style.name.value=条件` / `:css.name.value=...`
- 简写为 `..name`、`#name`, 以及 `!name=字符串值`:

  ```
  ..width=`100px`
  #border-width=`4px`
  !border-width=4px
  #--a-css-var=`'${theCssVarValue}'`
  ```

> `..` 和 `#` 的值为 JS 表达式; `!` 的值被当作字符串。

### `ZData.ss(s)`

style 缩写映射表, `ZData.ss` 返回某个缩写对应的完整属性名:

```js
ZData.ss = (s) => AShorthandMap[s] || s;
```

### 特别注意

- `: :: @ . .. #` 后面的值全部都是 JS 表达式, 可以是变量或字符串, 字符串必须用 `' " \`` 套住。
- 非绑定的属性值中含有 `${...}` 会自动解析成字符串, 相当于 `` `...${...}...` ``。
- `!` 与含 `${}` 的属性值类似, 会自动解析成 `:css.style-name=\`string-value\``。

### `attr` 修饰符

`:xxx.attr` 表示为可视的 attribute 属性, 否则默认为不可见的 prop 属性:

```html
<tag :title.attr='...'></tag>
```

`:xxx.attr === false` 表示 boolean attribute。attr 简写:

```
:!tag-attr  -> :tag-attr.attr
::!tag-attr -> ::tag-attr.attr
```

### `camel` 修饰符

`:xxx.camel` 支持驼峰式属性 / 属性名:

```
::value=propName, ::style.value=propName, ::css.value=propName
```

- `propName` 只支持驼峰表示法, DOM 属性 (包括 style) 可加 `.camel` 修饰符。
- 双向绑定默认在 `change` 事件中回写, 只有 `input type=text` 同时在 `input` 中回写。
- 可用 `.input` / `.change` 强制在对应事件中回写。
- 支持 `.trim` / `.number` 修饰符。
- 某些属性 (如 `style.value`) 修改后不会自动触发响应式, 需在当前执行上下文中调用 `el.fireChange()`。

### `input type='radio'`

```html
::checked=opt==this.value
```

> `opt` 是 data 内的属性变量名。

---

## class / style 语法糖

| 标记 | 含义 |
| --- | --- |
| `:xxx` | 属性绑定 |
| `::xxx` | 双向绑定 |
| `.name` | `:class.name` 简写 |
| `..name` | `:style.name` 简写 |
| `#name` | `:style.name` 简写 (JS 表达式) |
| `!name` | `:style.name` 简写 (字符串值) |
| `@event` | 事件绑定 |
| `:*={...}` | 动态属性 |
| `@*={...}` | 动态事件 |
| `z-d-...` | 自定义指令 |

---

## 原子化 CSS (Atomic CSS)

> 这是 z-data 的特色能力: 内嵌一套**类 Tailwind 的原子化 CSS 规则引擎**, 零依赖、零构建。
> 规则定义与编译器位于仓库 `css/` 目录, 生成产物并入 `z-data.min.all.js`。

### 为什么需要它

传统方式要么写大量 CSS 类, 要么引入 Tailwind 需要构建工具。z-data 提供一套**缩写规则**,
把类似 `p1`、`m2`、`h3`、`d-flex`、`c#f00`、`s:p0`、`hover=b#ff0` 的原子化标记
编译成 CSS 选择器并自动注入 `<style id="z-data-ss">`, 开箱即用。

### 内联使用 (推荐)

在元素上用 `ZData.ss(name, value)` 对应的简写属性即可, 无需写 JS:

```html
<div p1 hover=p2 a-hover=p3 a^hover=p4 a+hover=p5px a~not-hover=m6pt after=p7 m8 mt9%></div>
```

- 空属性 (如 `p1`) 表示"样式 = 值"。
- `hover=...`、`after=...` 等后修饰符对应 `:hover`、`:after` 伪类。
- `a-hover=...`、`a^hover=...`、`a+hover=...`、`a~not-hover=...` 等前修饰符对应父 / 前 / 兄弟伪类。
- `s:p0` 表示 `@media (min-width: 640px)` 媒体查询。

### 规则速查表

| 分组 | 规则 | 示例 |
| --- | --- | --- |
| padding / margin | `pm` | `p0, m.1, pl2, mt3px, px4%`, 变量 `m--varname, py--sm, px--lg` |
| max/min、尺寸、行高 | `h/w/xh/nw/font/lh/gap/brad` | `h1, w2, xh100%, nw4%, font12px, lh2, gap2, brad2` |
| left/top/right/bottom | `l/t/r/b` | `l0, t1, r2pt, b3px` |
| opacity/order/z-index | `op/ord/z` | `op.1, ord2, z3` |
| position/display/... | `pos/d/cs/v/ws/us/pe` | `pos-absolute, d-block, cs-pointer, ws-nowrap` |
| overflow | `o/ox/oy` | `o-scroll, ox-visible, oy-hidden` |
| content/color/background | `content/c/b` | `content-x, c#000, b#fff` |
| media 媒体查询 | `sm/md/lg/xl/2xl/print` | `s:p0` |
| state 状态伪类 | `hover/focus/active/after/before/(first|last)` | `hover=b#ff0, m:focus=c#f50, l:after="content-x cs-move"` |
| 前修饰伪类 | `a- / a^ / a+ / a~ / not-` | `a-hover=m1, parent^active=b#000, elder~hover=b#fff, prev+hover=c#fff` |
| group 分组 | `bd/bl/bt/br/bb/bg/a/al/font/flex/grid/mask` | `bd="style:bold; width:1px; color:red"` |

### 编程式 API

```js
// 直接注入一组 CSS
ZDataStyle.add({ '.foo': { color: '#f00' } });

// 简写映射
ZData.ss('pos'); // "position"
ZData.ss('brad'); // "border-radius"
```

完整的规则定义见 [`css/atomic-css-rules.txt`](./css/atomic-css-rules.txt),
编译与生成代码见 [`css/rule-compiler.fun`](./css/rule-compiler.fun),
运行时实现见 [`css/z-css.js`](./css/z-css.js)。

---

## 事件 Event

`@` 绑定事件, 支持 modifiers:

```html
<tag @click="doSomething()"></tag>
```

### 全局修饰符

```
camel     事件名驼峰表示法: a-camel-name -> aCamelName
prevent   preventDefault
stop      stopPropagation
debounce  防抖, 可带时间: debounce.750ms, debounce.2s, 默认 250ms
capture   捕获模式
once      只执行一次
passive   passive 模式
```

### 作用域修饰符

```
self      tag only
out       tag not
window
document
```

### 键鼠修饰符

```
shift
ctrl
alt
meta      or cmd
```

### 键盘修饰符

```
<key>     enter, escape, space, f1 等, 详见
          https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values
alias:  space: " ", slash: /, gt: >, eq: =
```

### 鼠标修饰符

```
<button>  left, mid, right
```

---

## 动态属性 / 事件与自定义指令

### 动态属性

```html
:*={...}
:*.attr={...}
```

例如:

```html
<tag :*="{
  min: '1',
  max: '100'
}"></tag>
```

### 动态事件

```html
@*={...}
```

例如:

```html
<tag @*="{
  input: 'console.log(event)',
  keydown: 'console.log(event)'
}"></tag>
```

### 自定义指令

```html
z-d-...=...
```

例如 `z-d-rules-of-validate`, 会被翻译成调用 `rulesOfValidate({e: el, v: val, m: modifiers})`:

```html
<tag z-d-rules-of-validate="[
  val => !!val || 'Name is required!',
  val => val.length > 5 || 'The field need 5 or more characters',
]"></tag>
```

```js
rulesOfValidate({
  e: el,
  v: val, // attr value of z-d-rules-of-validate
  m: modifiers
})
```

---

## 变量 Variables

### `$el`

组件根节点。

### `$el.$data`

组件的包装 data 对象。

### `ZData.nobserve` (默认 false)

关闭对 DOM 的自动 observe (动态创建 z-data 节点时, 使用 `ZData.loadHTML()`, 因此通常不需要 observe):

```js
ZData.nobserve = true;
```

---

## 函数与 API

### `ZData.proxy()`

在 z-data 获取 data 数据时, 用 `ZData.proxy()` 包装返回, 使数据获得响应式:

```js
return ZData.proxy({
  // some reactive data
});
```

### `ZData.loadHTML(html, p, before, args)`

动态加载 html, `p` 为父节点 (默认 body), `before` 为插入位置:

- html 内含 `<script>` 时, 必须用此方式加载; 否则可用 `:html=...` 加载。

```js
ZData.loadHTML(html, parentElement, beforeElement, args);
```

### `el.fireChange()`

在 z-data 之外修改节点 style 且为双向绑定时, 需调用该节点的 `.fireChange()` 触发更新。

### `$emit(el, name, detail)`

向 DOM 节点 `el` 发出名为 `name` 的事件, 携带 `detail` 参数。

```js
$emit(el, 'my-event', { any: 'detail' });
```

### `ZData.deb(fn, ms)`

防抖函数。

```js
ZData.deb(fn, 250);
```

### 其他

- `ZData.start()`: 手动启动。
- `ZData.on(name, fn)` / `ZData.call(name, args)`: 插件式事件钩子。

---

## 组件 Component (z-comp)

### 定义

```html
<tag z-comp=...></tag>
```

### 组件地址

`z-comp` 可以是 `./` 相对路径或 `http(s):` 网络路径:

```html
<tag z-comp=./z-comp-2.html></tag>
<tag z-comp=https://funlang.org/zdata/test/z-comp-2.html></tag>
```

也可以是一个返回组件代码的 Promise 函数:

```html
<tag z-comp="load_z_comp('z-comp-2')"></tag>
```

### 组件加载器 `ZData.get` (z:// 协议)

当 `ZData.get` 存在时, `z://` 协议插件生效。`ZData.get` 是一个 Promise 函数,
返回类似 `fetch(url).then(res => res.text())` 之后的部分:

```js
document.addEventListener("DOMContentLoaded", () => setTimeout(() => ZData.get = ...));
```

```html
<z- z-comp=z://table-v1.5.2></z->
```

### 组件占位符

`z-comp` 可以选择保留或删除组件占位符。`z-xxx` 标签或含 `del` 属性的占位符会被删除:

```html
<z-comp z-comp=https://funlang.org/zdata/test/z-comp-2.html></z-comp>
<div del z-comp=https://funlang.org/zdata/test/z-comp-2.html></div>
```

保留占位符:

```html
<div z-comp=https://funlang.org/zdata/test/z-comp-2.html></div>
```

### 组件参数

```html
<tag z-comp=... args=...></tag>
```

在组件内部用 `args.xxx` 获取传入参数:

```html
<div z-data @mouseover.document=$el.textContent=event.target&&(event.target.title||(event.target.closest('[title]')||{}).title)||''
#color=args.color #background=args.bgcolor !height=100% !padding=8px
></div>
```

### 组件 Demo

- <https://codepen.io/funlang/pen/ExZBPJL>
- <https://codepen.io/funlang/pen/RwKzaOo>

---

## z-json 工具

`z-data.min.all.js` 额外内置了一套 JSON / CSS 互转工具 (来自 `css/z-css.js`):

- `qs2json(str, dot, defValue, regex)`: 查询串 / 键值串转 JSON。
- `json2qs(obj, and, eq, dot, cb)`: JSON 转查询串。
- `css2json(str)`: CSS 字符串转 JSON。
- `json2css(obj, level)`: JSON 转 CSS, 支持嵌套 (含 `@media` 等 at-rule)。
- `ZJson.onStringify`: 序列化钩子。

这些工具非常适合做配置化、可视化设计器与样式数据的序列化。

---

## z-data studio (z-pen)

在线 IDE, 用于创建 / 调试 / 预览 z-data 代码、应用与组件:

- <https://funlang.org/z-data/>

---

## 浏览器兼容性

- `z-data.js`, `z-data.min.js`
  ```
  2017: Chrome 61, Firefox 55, Opera 48, Safari 11, iOS 11, Android 8
  ```

- `z-data.min.es2015.js`, `z-data.min.all.js`
  ```
  2016: Chrome 49, Firefox 44, Opera 36, Safari 10, iOS 10, Android 7
  ```

---

## 项目结构

```
z-data/
├── README.md            # 英文说明 (默认)
├── README-cn.md         # 本说明 (中文)
├── hello-world.html     # 最小示例
├── src/
│   └── z-data.js        # 核心框架源码
├── css/                 # 原子化 CSS 子系统
│   ├── README.md        # 原子化 CSS 规则说明
│   ├── atomic-css-rules.txt  # 规则定义 (BNF / 正则)
│   ├── rule-compiler.fun     # 规则编译器 (funlang 编写)
│   └── z-css.js         # 运行时实现 (ZData.ss / ZDataStyle)
├── www/                 # z-data studio 站点资源
├── z-pen/               # studio 构建与工具脚本
├── dist/                # 构建产物
├── CHANGE.txt           # 变更日志
├── package.json
└── LICENSE
```

---

## 性能

z-data 无虚拟 DOM, 直接操作 H5 DOM, 配合 `template for` 的 key 复用机制,
在大量列表插入 / 更新场景下性能优秀 (项目早期即参与过 js-framework-benchmark 对比)。

---

## 加入我们

欢迎加入 z-data 项目, 一起工作, Enjoy!

---

## 许可证

[MIT](./LICENSE)