@sohaha/zview
v0.0.1
Published
Declarative enhancement for HTML - TypeScript implementation
Maintainers
seekweReadme
Zview
⚠️ 纠偏：本文件部分内容来自历史版本（例如旧包名写法、以及
z-on:click/z-bind:value/z-swap="innerHTML:..."等写法）。 本仓库实际发布包名为@sohaha/zview（packages/view/package.json），指令语法以连字符为准（z-on-click/z-bind-foo/z-swap="inner"）。 建议直接阅读仓库根目录的 AI 使用文档：../../docs/zview.md。
一个基于 TypeScript 的现代化响应式前端框架，通过声明式指令系统构建高性能的 Web 应用程序。
✨ 特性
- 🚀 极致性能 - 删除所有妥协代码，最小体积最大速度
- 📦 零依赖 - 无需任何外部依赖
- 🎯 声明式 - 通过 HTML 属性声明交互逻辑
- ⚡ 精简指令 - 核心指令，无过度设计
- 🔄 响应式 - 基于信号的响应式数据流
- 🌐 TypeScript - 完整类型支持
- 🔥 激进优化 - 不考虑向后兼容
📦 安装
⚠️ 重要提示： 使用 CDN 引入时，必须添加
data-init属性才会自动初始化。这让你可以完全控制初始化时机。
CDN 引入
<!-- 生产版本（自动初始化） -->
<script src="https://unpkg.com/@sohaha/zview/dist/zview.umd.min.js" data-init></script>
<!-- 开发版本（自动初始化） -->
<script src="https://unpkg.com/@sohaha/zview/dist/zview.umd.js" data-init></script>
<!-- 手动初始化（不加 data-init） -->
<script src="https://unpkg.com/@sohaha/zview/dist/zview.umd.js"></script>
<script>
// 稍后手动调用
Zview.init({ debug: true })
</script>NPM 安装
npm install @sohaha/zview
# 或
pnpm add @sohaha/zview
# 或
yarn add @sohaha/zviewES 模块
import Zview, { Zview as ZviewNamed } from '@sohaha/zview'如果只需要不含 HTTP 请求能力的核心入口：
import ZviewCore from '@sohaha/zview/core'CommonJS
const { Zview } = require('@sohaha/zview')核心入口同样可通过子路径导入：
const { Zview } = require('@sohaha/zview/core')🚀 快速开始
<!DOCTYPE html>
<html>
<head>
<title>Zview 示例</title>
</head>
<body>
<div id="app" z-signals='{"title":"Zview 框架","isVisible":true,"count":0,"items":[{"id":1,"name":"项目 1"},{"id":2,"name":"项目 2"}]}'>
<!-- 响应式文本绑定 -->
<h1 z-text="$title"></h1>
<!-- 条件显示 -->
<p z-show="$isVisible">Hello Zview!</p>
<!-- 事件处理 -->
<button z-on-click="$count++">
点击次数: <span z-text="$count"></span>
</button>
<!-- 循环渲染 -->
<ul>
<template z-for="item in $items" z-key="item.id">
<li z-text="item.name"></li>
</template>
</ul>
</div>
<script src="https://unpkg.com/@sohaha/zview/dist/zview.umd.js" data-init></script>
</body>
</html>⚙️ 初始化配置
自动初始化（推荐）
使用 data-init 属性让 Zview 自动初始化：
<!-- 基础自动初始化 -->
<script src="zview.js" data-init></script>
<!-- 带配置的自动初始化 -->
<script src="zview.js"
data-config='{"setup":{"debug":true,"timeout":10000}}'
data-init>
</script>手动初始化
如果需要延迟初始化或自定义初始化时机，不加 data-init 属性：
<script src="zview.js"></script>
<script>
// 在合适的时机手动初始化
document.addEventListener('DOMContentLoaded', () => {
Zview.init({
debug: true,
timeout: 10000
})
})
</script>配置选项
通过 data-config 传递配置（需要同时使用 data-init）：
<script src="zview.js"
data-config='{
"setup": {
"debug": true,
"timeout": 8000,
"formSerializationFormat": "json",
"defaultSwap": "replace"
}
}'
data-init>
</script>z-swap 为空或非法时，会回退到 defaultSwap；未配置 defaultSwap 则为 inner。
📚 文档
- API 参考 - 完整的 API 文档
- 指令指南 - 所有内置指令的使用说明
- 信号系统 - 响应式信号系统详解
- HTTP 请求 - AJAX 和网络请求处理
- 事件系统 - 事件处理和修饰符
- 最佳实践 - 开发建议和性能优化
🎯 核心概念
指令系统
Zview 使用 HTML 属性形式的指令来声明交互行为：
<!-- 数据绑定 -->
<input z-bind-message placeholder="输入消息">
<!-- 类控制 -->
<div z-class="{ active: $isActive, disabled: $isDisabled }">
<!-- 样式控制 -->
<div z-style="{ color: $textColor, fontSize: $fontSize + 'px' }">
<!-- 循环 -->
<template z-for="user in $users" z-key="user.id">
<div z-text="user.name"></div>
</template>响应式信号
通过全局信号对象 $z 管理应用状态：
// 设置信号值
$z.message = 'Hello World'
// 读取信号值
console.log($z.message)
// 信号变化会自动更新 DOM
$z.count = $z.count + 1HTTP 请求
内置的 HTTP 请求指令：
<!-- GET 请求 -->
<div z-req="/api/users"
z-trigger="load"
z-config='{"selector":".user-list"}'
z-swap="inner">
加载用户列表...
</div>
<!-- POST 请求 -->
<form z-req="/api/users"
z-config='{"method":"POST"}'
z-trigger="submit"
z-data>
<input name="name" type="text">
<button type="submit">提交</button>
</form>🔧 开发
开发环境
# 安装依赖
pnpm install
# 开发模式
pnpm dev
# 构建
pnpm build
# 运行测试
pnpm test
# 类型检查
pnpm typecheck
# 代码格式化
pnpm format项目结构
src/
├── core/ # 核心引擎
├── directives/ # 内置指令
├── signals/ # 响应式信号系统
├── request/ # HTTP 请求处理
├── swap/ # DOM 交换策略
├── types/ # TypeScript 类型定义
└── utils/ # 工具函数🌟 示例
查看 examples/ 目录中的完整示例：
📄 许可证
🤝 贡献
欢迎提交 Issue 和 Pull Request！