# descui

**Repository Path**: xhaoran/descui

## Basic Information

- **Project Name**: descui
- **Description**: 嵌入式HTML+CSS+QJS引擎
- **Primary Language**: C
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-20
- **Last Updated**: 2026-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DescUI

面向嵌入式设备（ESP32 等）的轻量级 UI 框架，使用 **C99** 编写。用 **HTML + CSS** 描述界面，可选 **QuickJS** 提供浏览器风格的 JavaScript 运行时，渲染到位图帧缓冲。

典型场景：数字吊坠、小屏手表、工业 HMI（如 172×320 彩色屏）。

## 特性

- **HTML / CSS** — 简易标签解析、内联样式、`<style>` 样式表、`:hover`
- **布局** — block、inline-block、flex、grid；支持 `width:100%`、`calc()`、`box-sizing`
- **渲染** — 背景、圆角边框、**UTF-8 中文**（12px 离线位图字库）、JPEG 图片、滚动条
- **交互** — 点击命中测试、滚轮/拖拽滚动、链接与 SPA 页面切换
- **JavaScript**（可选）— `document`、`console`、`setTimeout`、`requestAnimationFrame` 等 Chrome 风格 API
- **跨平台** — Win32 窗口预览调试；核心与平台解耦，便于移植到 ESP32

## 快速开始

### 环境要求

- GCC（Windows 推荐 [Strawberry Perl/GCC](https://strawberryperl.com/) 或 MinGW）
- CMake 3.10+（可选）

### 构建

```bat
build.bat              rem 默认并行编译（CPU 核数）
build.bat -j 8         rem 指定 8 线程
build.bat clean        rem 清理
```

可选：从 TTF 重新生成 24px 中文字库（需 Python 3 + Pillow）：

```bat
python tools/fontgen/gen_common2000.py
python tools/fontgen/extract_chars.py --common2000
python tools/fontgen/fontgen.py
```

默认同时生成 **12px + 24px** 两套字库；`font-size` 自动选用最接近的原生档位（1:1 无缩放）。

字体添加、裁剪与重新生成详见 **[docs/FONT_GUIDE.md](docs/FONT_GUIDE.md)**。授权说明见 [third_party/fonts/LICENSE](third_party/fonts/LICENSE)。

生成两个可执行文件（位于仓库根目录）：

| 程序 | 说明 |
|------|------|
| `descui_app.exe` | 无窗口，渲染 HTML 并输出 `output.bmp` |
| `descui_win32.exe` | Win32 窗口，支持鼠标/触摸交互 |

### 运行

从仓库根目录执行：

```bat
:: 离线渲染为 BMP
descui_app.exe tests/html/test2.html

:: 交互式窗口预览
descui_win32.exe tests/html/test_js.html
descui_win32.exe tests/html/test_scroll.html
```

### CMake（可选）

```bat
cmake -B build -DDESCUI_ENABLE_QUICKJS=ON
cmake --build build
```

产物位于 `build/bin/`。

## 测试页面

| 文件 | 用途 |
|------|------|
| `tests/html/test.html` / `test2.html` | 基础布局与样式 |
| `tests/html/test_js.html` | JavaScript / DOM / 定时器 API |
| `tests/html/test_scroll.html` | 滚动区域 |
| `tests/html/test_nav.html` | SPA 页面导航 |

测试图片资源位于 `tests/assets/`。

## JavaScript API（QuickJS）

编译时开启 `DESCUI_ENABLE_QUICKJS=1`。主循环需调用 `descui_view_tick(view, dt_ms)` 驱动定时器与 `requestAnimationFrame`。

完整说明见 **[docs/JS_API.md](docs/JS_API.md)**（含 `native` 原生扩展注册）。

| 类别 | API |
|------|-----|
| Console | `console.log` / `warn` / `error` / `info` / `debug` |
| Document | `getElementById`、`querySelector`、`querySelectorAll`、`getElementsByClassName` |
| Element | `textContent`、`id`、`className`、`classList`、`style.cssText`、`get/setAttribute`、`add/removeEventListener` |
| 导航 | `location.href`、`location.hash`、`history.back()` |
| 定时器 | `setTimeout`、`setInterval`、`clearTimeout`、`clearInterval` |
| 其他 | `requestAnimationFrame`、`window`、`navigator.userAgent`、`alert` |
| 原生扩展 | `native.xxx()` — C 端 `descui_js_register_natives` 注册 |
| **QuickJS 内置** | `JSON`、`Promise`/`async`、`Map`/`Set`、`RegExp`、`Date`、`Math`、`BigInt`、`TypedArray` 等（见 [JS_API.md](docs/JS_API.md)） |

```c
descui_js_native_def_t natives[] = {
    { "echo", js_echo, NULL },
};
descui_js_register_natives(js, natives, 1);
// JS: native.echo("hello")
```

> ESP32 上 QuickJS 堆建议 ≥ 128 KB；桌面调试可传 `0`（无限制）。

## CSS 支持摘要

完整属性列表见 **[docs/CSS_REFERENCE.md](docs/CSS_REFERENCE.md)**。

| 类别 | 支持 |
|------|------|
| 布局 | `block` / `inline-block` / `flex` / `grid`；`width`/`height` 的 `%`、`calc()`、`box-sizing` |
| 盒模型 | `margin`/`padding`/`border`/`border-radius`；`min-*` / `max-*` |
| Flex | `flex-direction`、`justify-content`、`align-items`、`align-self`、`flex-wrap` 等 |
| 定位 | `position`、`top/right/bottom/left`、`z-index` |
| 文本 | `color`、`font-size`（12/24px 字库）、`text-align`、`line-height`、`letter-spacing` |
| 背景/图片 | `background-*`、`object-fit`；JPEG `url()` |
| 滚动 | `overflow`、`scrollbar-width`、`scrollbar-color` |
| 样式表 | `#id`、`.class`、`tag`、后代、`>`、`:hover` |

## 最小示例

```c
#include "descui_view.h"

descui_view_t view;
descui_view_init(&view, 172, 320, DESCUI_PIXEL_RGB888);
descui_view_load_html_file(&view, "tests/html/ui.html");

for (;;) {
    platform_poll_input(&view);          // 触摸/按键 → descui_event_post
    descui_view_tick(&view, 16.0f);      // 定时器 + 脏区重绘
    platform_present(descui_view_framebuffer(&view));
}
```

## 项目结构

```
descui/
├── README.md
├── build.bat / CMakeLists.txt
├── docs/                      # 设计文档
├── src/
│   ├── app/                   # main.c, main_win32.c
│   ├── core/                  # DOM、布局、CSS、渲染、事件、导航
│   ├── js/                    # QuickJS 绑定
│   ├── raster/                # bitmap、font、image
│   └── platform/win32/        # Win32 后端
├── tests/
│   ├── html/                  # 测试页面
│   └── assets/                # 测试图片
├── tools/                     # 开发辅助工具（含 fontgen 字库生成）
└── third_party/
    ├── quickjs/               # QuickJS 源码
    └── fonts/                 # 字体授权说明（TTF 本地放置）
```

## 文档

| 文档 | 说明 |
|------|------|
| [docs/AI_HANDOFF.md](docs/AI_HANDOFF.md) | **AI 交接记忆**（接手必读） |
| [docs/FRAMEWORK_DESIGN.md](docs/FRAMEWORK_DESIGN.md) | 框架架构与设计 |
| [docs/CSS_REFERENCE.md](docs/CSS_REFERENCE.md) | 支持的 CSS 属性与选择器 |
| [docs/JS_API.md](docs/JS_API.md) | JavaScript API 与 C 原生扩展 |
| [docs/FONT_GUIDE.md](docs/FONT_GUIDE.md) | 字库添加、裁剪与重新生成 |

## 限制

- HTML/CSS 为简化子集，非完整浏览器实现
- 无 `fetch`、动态 `createElement` 等完整 DOM API
- 文本排版为单行 `line-height` 模型
- `querySelector` 仅支持 `#id`、`.class`、`tag` 简单选择器

## 许可证

- DescUI 项目代码：请根据仓库所有者约定使用
- 嵌入字体：见 [third_party/fonts/LICENSE](third_party/fonts/LICENSE)
- [QuickJS](third_party/quickjs/)：MIT / LGPL 双许可，详见 `third_party/quickjs/LICENSE`

## 仓库

https://gitee.com/xhaoran/descui