ZZufyUI文档首页DocumentationДокументацияDokumentationDocumentationDocumentación

正在准备文档Preparing your docsПодготовка документацииDokumentation wird geladenPréparation de la documentationPreparando la documentación

从这里开始 · 支持全文搜索

框架概览

轻量到几 MB,快到原生合成。 纯头文件、零第三方依赖的 C++20 Windows 自绘 UI 框架,直接构建在 Direct2D 1.1 + DirectComposition 之上。 - 没有 Qt 的打包包袱,没有 Electron 的内存税。 几个头文件,include 即用;应用工程不链

易错点

> 这份文件把散落在代码注释、HANDOFF.md、TODO.md 里的“坑”集中到一处。接手/使用前先扫一遍。 > 优先级:易错 = 违反必踩;注意 = 契约/限制,违反易出问题;约定 = 库的取向;不要 = 明确不做。 --- 1. 链式构造 DSL(ZufyUIDsl.h) | | 状态 |

参考总览

> 本文档覆盖 ZufyUI 框架的全部公开 API,按“使用分类”组织(不是按代码/头文件顺序)。 > 配套阅读:[项目说明与构建](https://github.com/zhc9968/ZufyUI/blob/master/README.md)。 > 阅读方式:本文不是“签名清单”,而是按“它是

约定

颜色与标记 - 红色块:易错——真实踩坑、反直觉行为、会崩溃/UAF/竞争的用法,优先看。 - 橙色块:注意——线程、生命周期、绘制顺序等契约;不一定是错误,但违反后容易出问题。 - 绿色块:推荐——推荐写法、所有权模型、最佳实践。 - 普通项目符号表示普通语义、默认值或版本变化,不代表没有风险。

快速开始

最小程序 cpp include "ZufyUI.h" include "ZufyUIWidgets.h" using namespace ZufyUI; int APIENTRY wWinMain(HINSTANCE, HINSTANCE, LPWSTR, int) { // Windows 子系

基础类型

Color cpp struct Color { float r, g, b, a; // 分量范围 [0,1],不是 0..255 Color(float r=0, float g=0, float b=0, float a=1.0f); static Color FromArgb(uint8t

事件与信号

何时用信号 - 控件对外通知(点击、选中、值变化)用内置 ZSignal。 - 自定义控件对外事件:自己声明 ZSignal 成员并 Fire。 ConnectionThread cpp enum class ConnectionThread { CurrentThread, NewThread,

语言

API 参考 / v1.29.1

布局系统

Layout、ColumnBox、RowBox、GridLayout、Card、Page、PageHost

下载 Markdown

Layout(布局基类)

class Layout : public UIElement { bool UseCache() const override { return false; } };
  • 布局容器一律不缓存。

ColumnBox(垂直)/ RowBox(水平)

enum class LayoutAlignment { Start, Center, End, Stretch };
enum class Justify { Start, Center, End, SpaceBetween, SpaceAround };
ColumnBox(); RowBox();
void AddChild(std::shared_ptr<UIElement>);  void ClearChildren();
void RemoveChild(std::shared_ptr<UIElement>);  void RemoveChildAt(int);  void InsertChild(int, std::shared_ptr<UIElement>);
void SetSpacing(float);
void SetJustify(Justify);              // 主轴:Start/Center/End/SpaceBetween/SpaceAround
void SetCrossAlign(LayoutAlignment);   // 交叉轴,默认 Stretch(兼容旧行为)
  • ColumnBox 默认水平填满、垂直不拉伸;RowBox 相反。
  • Justify 只在没有 flex/拉伸子元素时分配剩余空间;CrossAlign 设为 Center/Start/End 时按子元素 desiredSize 摆放,不再强制拉满。

易错

  • AddChild 会 SetParent(this);容器用 shared_ptr 拥有子元素。子元素设了显式 SetHeight 时,剩余空间按权值叠加到该高度上。
  • 版本:v1.17.0 起按子元素拉伸权值分配剩余空间。

GridLayout(网格)

using Alignment = LayoutAlignment;   // Start / Center / End / Stretch
void AddChild(std::shared_ptr<UIElement>, int row, int col, int rowSpan=1, int colSpan=1,
              Alignment hAlign=Alignment::Stretch, Alignment vAlign=Alignment::Stretch);
void SetColumnCount(int);  void SetRowCount(int);
void SetSpacing(float h, float v);
void SetColumnStretch(int col, float weight);  void SetRowStretch(int row, float weight);
void SetHorizontalAlignment(Alignment);        void SetVerticalAlignment(Alignment);
void SetCellAlignment(int row, int col, Alignment h, Alignment v);
  • 行/列数由 SetColumnCount/SetRowCount(或 SetColumnStretch/SetRowStretch)定义;空轨道仍然存在,不需要占位元素。
  • SetCellAlignment 控制子元素在自己的 cell 内如何摆放,默认 Stretch;SetHorizontalAlignment/SetVerticalAlignment 控制整个 Grid 内容在剩余空间中的位置。
  • 1×1 Grid 也可以使用内容对齐;SetColumnStretch(2, ...) 会建立第 3 列。
  • 未显式设行/列拉伸时,单元格轨道权重取所跨子元素权值的最大者。
  • 版本:v1.26.0 起,Grid 自身的显式 SetWidth/SetHeight 同时作为 cell 测量范围;不会再出现“对外返回 260、内部按 274+ 排列”的溢出。

LayoutHost / Card / Page

class LayoutHost : public UIElement {
    std::shared_ptr<UIElement> GetLayout() const;  void SetLayout(...);
    std::shared_ptr<UIElement> GetContent() const; void SetContent(...);   // 单内容别名
    void SetContentAlignment(LayoutAlignment h, LayoutAlignment v);        // 默认 Stretch
};
class Card  : public LayoutHost { DefaultPadding=12; DefaultCornerRadius=8; ... };
void SetContent(const std::wstring& title, const std::wstring& description, std::shared_ptr<UIElement> action=nullptr);
class Page  : public LayoutHost { DefaultPadding=10; ... };
void Page::SetScrollableContent(std::shared_ptr<UIElement> content);   // 一行套 ScrollViewer(fill)+8px 边距
  • LayoutHost 是“单内容宿主”;Card 是带圆角/描边/悬停的卡片;Page 是 TabView/PageHost 的页面容器。
  • SetContentAlignment(Center, Center) 可让 Page/Card 的内容整体居中;默认 Stretch 保持旧行为。
  • 空内容时,Card/Page 的显式 SetWidth/SetHeight 仍然生效;ScrollViewer 无内容时也返回显式/有限视口尺寸。
  • Card::UseCache() = HasShadow();Page::UseCache() = false。

PageHost(页面宿主 / 过渡)

enum class TransitionDirection { Left, Right, Up, Down };
enum class TransitionEasing { Linear, EaseInOut, EaseOut };
void AddPage(std::shared_ptr<Page>);  void RemovePage(int);  void ClearPages();
void NavigateTo(int index);   void SetCurrentIndexInstant(int index);
void SetTransitionDirection(...);  void SetTransitionEasing(...);  void SetAnimationDuration(float);
int GetCurrentIndex() const;  std::shared_ptr<Page> GetCurrentPage() const;
  • 过渡期间同时把源页与目标页作为可见子元素返回;UpdateAnimation 每页只更新一次(否则动画速度翻倍)。

易错

  • NavigateTo 是异步的(动画结束才真正切到目标),GetCurrentPage()/GetCurrentIndex() 在动画期间可能还是旧值。
  • 页面内元素显隐请用 SetVisible()(会 InvalidateLayout());不要直接改内部可见标志,否则既不会重测也不会重绘。
  • 版本:缓动 v1.8.1;隐藏页缓存延迟释放(约 1.2s,整棵子树递归) = v1.18.0——解决快速切页内存抖动式增长;MeasureOverride 测量全部页面 = v1.23.1——页面内元素运行时显隐(如选择下拉后显示的 Expander 卡片)会立即重新布局并参与命中,不再需要改变窗口尺寸来触发。

TabView(页签)

见「容器与滚动 / 页签」章。

查看源文件docs/src/API.md