dtkcss — DTK CSS 样式引擎

为 DTK（Deepin ToolKit）应用增加 “用 CSS 设计界面” 的能力。一份接近 Web CSS 的样式表， 由引擎翻译为 DTK 原生的 DPalette / DStyle / DFontSizeManager 以及安全的 QSS 桥接， 从而兼顾明暗主题、控件状态（hover/pressed/disabled/focus）与 DTK 视觉规范。

本模块是 DTK 上游功能的 提案实现原型，目标 DTK 6.x（palette 主线，DThemeManager 已废弃）。

---

已确认的设计决策（见 DTK-CSS-开发计划书.md）

#	决策	结果
1	模块形态	独立模块 dtkcss
2	目标 DTK 版本	DTK 6.x（不主动兼容 5.x）
3	实现策略	混合式（原生 + QSS 桥接）
4	覆盖范围	仅 C++/Widget（QML 暂不做）
5	选择器范围	同时支持 DTK 控件（D*）与 Qt 标准控件（QPushButton 等）

---

目录结构

dtkcss/
├── CMakeLists.txt          # CMake 构建（Qt5/Qt6 + pkg-config DTK）
├── dtkcss.pro              # qmake 构建（DTK 习惯用法）
├── dtkcss.pc               # pkg-config 文件（qmake 用）
├── cmake/dtkcss.pc.in      # pkg-config 模板（CMake 用）
├── src/
│   ├── src.pri             # 源/头文件清单
│   └── css/                # 库源码（命名空间 Dtk::Css）
│       ├── dcssglobal.h            # 版本 / 导出宏 / 命名空间
│       ├── dcss.h                  # 总包含头
│       ├── dcssrule.h/.cpp         # 选择器 / 规则 AST + 匹配
│       ├── dcssstylesheet.h/.cpp   # 解析后的样式表
│       ├── dcssparser.h/.cpp       # CSS 解析器（纯 Qt，可单测）
│       ├── dcsspalette.h/.cpp      # 颜色解析 / var / DPalette 角色映射（M3）
│       ├── dcssapplicator.h/.cpp   # 应用器（M3+ 实现）
│       └── dcssapplicationhelper.h/.cpp # 应用级入口
└── tests/
    ├── test_parser.cpp     # Qt Test 单元测试（解析器）
    ├── test_palette.cpp    # 颜色映射 / 角色 / var 测试（M3）
    ├── CMakeLists.txt
    └── test_parser.pro

---

构建

⚠️ 实际编译需要 Linux + DTK 6.x 开发环境（deepin 23 / UOS，或装有 dtkwidget-dev、dtkgui-dev 的构建机）。Windows 下无法构建 DTK，本仓库仅作为源码与原型交付。

qmake

qmake dtkcss.pro
make
sudo make install

CMake

mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/usr
make
ctest --output-on-failure   # 运行解析器单元测试
sudo make install

---

API 用法（草案）

#include <dtkcss/dcss.h>
DTKCSS_USE_NAMESPACE

// 应用级（在 DApplication 之后调用）
DCssApplicationHelper::instance()->loadAppCss(":/style/app.css");
// 注册窗口：其控件树应用样式，并在明暗主题切换时自动重应用
DCssApplicationHelper::instance()->registerWidget(mainWindow);

// 单控件级
DCssApplicator::applyString(
    "DButton { background: #0081ff; color: white; border-radius: 12px; }",
    myButton);

---

支持的 CSS 语法（子集）

@theme auto;                 /* auto=跟随系统 / light / dark */

:root {
  --brand: #0081ff;
  --radius: 8px;
}

DMainWindow { background: #f8f8f8; }

DButton {
  background: #e5e5e5;       /* → DPalette::Button */
  color: #000;               /* → DPalette::ButtonText */
  border-color: #d0d0d0;     /* → DPalette::FrameBorder */
  border-radius: var(--radius); /* → DStyle::setFrameRadius（原生，M4 实现） */
  font-size: T6;             /* → DFontSizeManager::T6（M4 实现） */
  padding: 6px 12px;         /* → M5 QSS 桥接 (暂未实现) */
}

DButton:hover  { background: #dcdcdc; }   /* → QSS 桥接 */
DButton:pressed{ background: #d0d0d0; }   /* → QSS 桥接 */
DButton:disabled { background: #f0f0f0; color: rgba(0,0,0,.3); } /* → QPalette::Disabled */

#login-btn { background: var(--brand); }  /* 按 objectName 命中 */

/* 暗色主题覆盖 */
@media (prefers-color-scheme: dark) {
  DButton { background: #444; color: #fff; }
}

选择器：DButton / QPushButton（类，含基类匹配）、#id（objectName）、 [attr="val"]（动态属性）、DMainWindow DButton（后代）、:hover/:pressed/:disabled/:focus/:checked（伪类，元数据）。

---

开发状态

阶段	内容	状态
M0	调研 + 计划书定稿	✅
M1	模块骨架（构建/pkg-config/命名空间/头骨架）	✅
M2	CSS 解析器（tokenizer/parser/AST/选择器/单测）	✅
M3	应用器①：DPalette 映射 + 明暗双调色板 + 主题切换	✅
M4	应用器②：DStyle 度量（frameRadius）+ DFontSizeManager（T1–T11 / px）	⬜
M5	应用器③：伪类与 QSS 桥接	⬜
M6	应用级加载 API + 示例 demo	⬜
M7	QML 绑定（暂不做）	⏸
M8	文档 + 集成/验收测试	⬜

当前（M1–M3）已完成：

• M1+M2：可解析 CSS 并产出 AST（DCssStylesheet），可在不含 DTK 的环境下用 tests/test_parser 对解析器做单元测试；
• M3：把解析结果真正落地到控件——颜色属性映射到 DPalette（标准 QPalette 角色 + DTK 扩展角色 ItemBackground/TextTitle/TextTips/TextWarning/FrameBorder 等）， 支持 @media dark/light 与 @theme 的明暗过滤，并监听 DGuiApplicationHelper::themeTypeChanged() 在切换明暗时自动重应用 （tests/test_palette 验证映射正确性）。
• 伪类与 QSS 桥接（M5）尚未实现，故 :hover/:pressed/:disabled 等状态属性、 以及 padding/margin/box-shadow 等盒模型属性暂未生效（计划由 M5 的 QSS 桥接覆盖）。