axisly::css::LayoutTree 保存节点、样式、父子关系和缓存。每次计算指定一个根和可用空间,
默认同步返回完整布局结果,也可保留布局并按节点读取。快速示例见 中文 README,接口定义见
css_tree.hpp。
create_node(style, measure)创建节点,测量回调可省略;默认Style使用 Flex 布局。append_child/insert_child建立父子关系,也可用于换父级或重新排序。create_node_with_children创建带子节点的容器;set_children整体更新子节点。replace_child按索引替换;detach_child_at、detach_children按索引或范围分离。detach保留子树;remove_node只删除节点并将其子节点变为根。remove_subtree删除节点及其全部后代。node_count、child_count、child_at、dirty提供查询,clear清空节点。set_style更新样式;set_measure更新测量回调;外部内容改变时调用mark_dirty。
NodeId 标识库中的节点,宿主自行维护它到控件的映射。失效句柄、跨树句柄和循环拓扑会被拒绝。
一次计算可从任意有效节点开始,输出仅包含该根的子树。
style()、context() 返回借用引用,children() 返回借用 span;跨树修改保留数据时应先复制,
不要在节点删除后继续使用引用,也不要在父子关系修改后继续使用旧 span。
字号、文字、图片、DPI 或其他测量依赖改变后,即使回调对象没有变化,也需要主动标脏。
mark_dirty(node) 只失效该节点和祖先;整个容器内容变化应使用 mark_subtree_dirty(node)。
无关分支可以在相同约束下复用缓存;一个叶子变化仍可能使祖先和兄弟节点重新分配尺寸。
树操作先完成参数检查和可能失败的内存准备,再提交父子关系;缓存失效与删除不分配工作列表。
操作因内存分配失败而抛出异常时,原有拓扑仍然有效。
namespace css = axisly::css;
css::Style style;
style.display = css::Display::Flex;
style.flex_direction = css::FlexDirection::Column;
style.gap.height = css::Length::length(8);
style.box.size.width = css::Length::percent(0.5F); // 50%,不是 50
style.box.min_size.width = css::Length::length(120);样式分为通用 Style、盒模型 BoxStyle 和轨道/放置 GridStyle。
长度值区分确定长度、百分比、auto、固有尺寸关键字及类型化计算表达式。
完整字段对应关系见 兼容性说明。
Unit 为 float,逻辑坐标的单位由宿主约定;Insets 顺序为左、上、右、下。
已知零尺寸与未定尺寸有不同含义,不能把零当成缺省值。
可用空间通过 AvailableSpace::definite()、indefinite()、min_content() 和
max_content() 表达,不通过无穷或 NaN 表示。
测量叶子在 create_node 或 set_measure 中接收 MeasureFunction。
回调返回内容盒尺寸及可选的首/末基线,不包含 padding、border 和 margin。
下面是一个固定尺寸图标的测量回调:
auto icon = tree.create_node({}, [](const css::MeasureRequest& request) {
return css::Measurement{{
request.known_content_width.value_or(24),
request.known_content_height.value_or(24)}};
});文字宿主应根据请求执行自己的文字排版:
| 请求字段 | 含义 |
|---|---|
known_content_width/known_content_height |
已确定的内容尺寸;有值时优先于回调该轴的返回值,零也是有效约束 |
available_width/available_height |
确定的可用空间、未定空间或 min/max-content 查询 |
Measurement::content_size |
本次约束下的内容尺寸,必须有限且非负 |
first_baseline/last_baseline |
相对内容盒顶部的可选基线 |
scrollable_content_size |
实际可滚动内容尺寸;省略时使用 content_size |
回调可能在同一帧被不同约束多次调用,也可能因缓存而完全不调用。 它应当根据请求和当前内容返回稳定结果,不应依赖调用顺序。 库不加载字体或进行文字塑形;换行、字体度量、图标和图片尺寸由宿主提供。
少量独立控件可直接用节点级 MeasureFunction。宿主已有统一文字/图片测量服务,
或希望减少每节点捕获对象时,推荐共享 MeasureProvider 加节点上下文。
set_context(node, shared_ptr<void>) 保存宿主上下文,context(node) 读取它。
实现 MeasureProvider::measure(node, style, context, request) 后,通过
LayoutOptions::measure_provider 为一次计算提供共享测量。节点自己的 MeasureFunction 优先。
提供者用于所有需要内容测量的叶子,上下文可以为空。提供者对象在计算期间必须有效。
输入内容变化仍需标脏对应节点;共享测量策略整体改变时递增 measurement_revision。
更换提供者地址或 revision 会失效全树布局缓存,普通连续帧保持它们不变即可复用缓存。
const auto& result = tree.compute(root, available);
if (result.succeeded()) {
if (const auto* node = tree.find_layout(icon)) {
const auto bounds = node->border_box;
// 应用 bounds 到宿主;嵌套控件需要按父控件坐标系转换。
}
}nodes按根优先、深度优先顺序保存完整几何;border_box和content_box相对布局根。margin、padding、border、scrollbar和基线分别报告。scrollable_overflow_rect是节点局部滚动范围;裁剪、滚动偏移与滚动交互由宿主处理。grid_tracks包含 Grid 轨道尺寸、位置、线名和项目放置等诊断数据。LayoutResult::find做线性查找;频繁按 ID 读取时可使用树上的find_layout惰性索引。layout(node, CoordinateSpace::Parent)返回相对父节点的几何值,无需从大坐标相减。unrounded_layout(node)可在取整后继续读取原始逻辑坐标。
结果由树持有。树修改本身保留上一份已发布快照,下一次计算会更新它。
节点指针在重新计算或树销毁后不能继续使用;需要同时保留多帧时复制 LayoutResult。
layout 返回值副本,其生命周期独立于后续计算;find_layout 返回借用指针。
css::LayoutOptions options;
options.publish_nodes = false; // 保留内部布局,省去完整数组发布
options.collect_grid_tracks = false; // 不生成 Grid 诊断信息
const auto& status = tree.compute(root, available, options);
if (status.succeeded()) {
if (auto bounds = tree.layout(icon, css::CoordinateSpace::Parent)) {
// 应用 bounds->border_box 到嵌套控件。
}
}这时 nodes 和 grid_tracks 为空,数值错误检查仍会执行。layout() 按树路径查找节点,
首次访问宽分支时建立可复用的子节点索引;
大量节点遍历宜选择默认完整快照。调用 find_layout() 会惰性生成完整数组和索引。
更改诊断开关会失效诊断相关缓存,建议在稳定的使用模式中保持该选项不变。
css_source.hpp 提供 LayoutSource 和 LayoutSession。
宿主实现 node(NodeId),返回借用的 Style、子节点 span、父节点和上下文指针。
LayoutSession 直接借用它们进行计算,仅持有算法缓存和输出,不复制宿主样式及子节点数组。
// host_tree 实现 css::LayoutSource;它的生命周期长于 session。
css::LayoutSession session(host_tree);
const auto& result = session.compute(host_root, available);
auto bounds = session.layout(host_child, css::CoordinateSpace::Parent);- 宿主提供非零、唯一的 NodeId,并维持无环、一致的父子关系。
- 样式、子节点数组、上下文在计算期间不能改变或失效。
- 修改样式或内容后调用
session.mark_dirty(node);修改拓扑、删除节点或复用 ID 后调用session.invalidate()。 invalidate()丢弃节点绑定和缓存,上一份已发布几何仍可读取,直到下一次计算。- 会话可通过
LayoutOptions使用共享测量、取整、按需结果和诊断开关。 - 完整发布后的根坐标值查询使用惰性的宿主 ID 排序索引,避免逐节点读取时反复扫描全数组。
- 同一会话需要串行访问;回调不能重入或使该会话失效。
宿主已有布局管理器时,应让它与 Axisly 分别管理不同的控件范围,避免多方重复设置同一控件的矩形。
compute(root, available, axisly::PixelRounding{scale}) 可发布设备像素对齐的几何,
内部缓存保留逻辑坐标。跨临时树可共享 LayoutMemory,多棵独立树可交给 LayoutBatch。
具体生命周期与线程约定见 执行资源。
单棵树的计算、修改和查询需要串行访问或由宿主同步。测量回调不能修改或重入计算同一棵树。 默认批量模式将回调留在调用线程;显式并行前,宿主需保证回调和所用资源适合多线程访问。
样式工厂和树操作的非法参数通过异常报告。计算失败时检查 result.error 中的错误码、节点与消息;
失败结果为空,不返回部分几何。宿主回调异常原样传播,保留上一份完整发布结果。
入口检查和布局检查的边界如下。validate_style 检查类型化样式的属性域,不解析特定容器下的最终数值,
也不能保证随后 compute 成功;set_style 自身会完成同样的检查,无需为了提交而重复校验。
重复提交与节点当前值相同的样式时直接返回,不复制样式、不重新校验、不使缓存失效。
实际变更使用左值时先完成校验和副本准备,使用右值时先校验再移动;校验或副本分配失败
会保留旧样式和缓存。所有提交仍须遵守节点句柄有效性及计算期间禁止修改的约定。
| 阶段 | 条件举例 | 报告方式 |
|---|---|---|
| 值工厂 | NaN/无穷长度、零 Grid 线号、非法 span | std::invalid_argument,对象尚未生成 |
validate_style、create_node、set_style |
非法枚举、负 flex 因子、非正宽高比、Grid 区域不成矩形、非法模板组合 | std::invalid_argument,不提交非法样式 |
| 树修改和查询 | 无效句柄、循环父子关系、越界子索引、计算中修改同一棵树 | std::invalid_argument、std::out_of_range 或 std::logic_error |
compute 的参数 |
非法确定空间、取整比例或原点 | std::invalid_argument,保留上一份发布结果 |
| 布局过程中 | 依赖容器的值、借用宿主样式、测量返回值、计算预算 | 下表的 LayoutErrorCode,发布空的失败结果 |
| 节点/共享测量器抛出异常 | 包括 invalid_argument、overflow_error、length_error、bad_alloc 及非标准异常 |
保留类型和值并向调用方传播,保留上一份完整发布结果 |
| 库自身的内存分配失败 | 样式复制、缓存、结果存储分配失败 | std::bad_alloc;不会伪装成非法样式或空布局 |
LayoutErrorCode |
含义与边界 |
|---|---|
None |
计算成功 |
InvalidRoot |
请求的根或遍历时需要的节点不存在;借用树应检查宿主拓扑 |
InvalidStyle |
解析后的 gap 为负、盒模型参数不合法,或借用树的样式在计算时未通过校验;属性域合法不代表每个容器尺寸下都合法 |
Unsupported |
保留错误码,当前算法没有产生此码的路径;不支持的浏览器功能不能用这个枚举自动检测 |
UnresolvedPercentage |
算法需要确定盒边时仍缺少百分比基准;未定百分比并非一律报错,许多布局路径按各自规则延后或按零处理 |
InvalidMeasurement |
回调正常返回,但尺寸/基线等未通过测量值校验;与回调抛出异常不同 |
NumericOverflow |
库内计算或几何发布超出有限 Unit 范围 |
LimitExceeded |
布局深度、测量次数、轨道/放置/均衡换行工作量等超过上限;建树节点数超限在入口抛 std::length_error |
当前库要求启用 C++ 异常,不支持 -fno-exceptions。尚无 check_style/try_set_style 的无异常契约;
来自配置文件的值应由宿主在输入边界捕获验证异常。仅增加 noexcept 包装不足以消除值工厂、
样式复制及宿主回调的异常,不能据此宣称整个“校验、提交、计算”流程无异常。
TreeLimits 默认限制最大深度为 64,树节点数、每次计算的测量次数及两类缓存条目预算各为 100,000。
可在构造树时按业务规模调整。预算用于限制工作量,超限不应被当成正常空布局。
两类缓存条目预算控制缓存保留量;达到缓存上限可以继续计算,不等于布局工作量超限。
历史接口调整及替代写法统一维护在变更记录,包括节点失效、
删除、溢出字段和 compute 参数迁移。