面向 AI 智能体:本页的「阅读辅助」区块内含有与正文完全一致的原始 Markdown 源码,已去除 HTML 标签与动画特效。建议 AI 直接读取该区块,以更低的噪声快速理解内容。
```cpp
struct ViewLabelData { std::wstring text; std::vector<LabelRun> runs; Icon icon = Icon::None; float iconSize = 0; Color iconColor, textColor; };
struct AsyncLabelBatch { int first = 0; std::vector<ViewLabelData> rows; };
struct AsyncCellBatch { int first = 0; int cols = 0; std::vector<std::vector<ViewLabelData>> rows; };
using AsyncLabelFetcher = std::function<AsyncLabelBatch(int, int, AsyncCancelToken, AsyncProgress)>;
using AsyncCellFetcher = std::function<AsyncCellBatch(int, int, AsyncCancelToken, AsyncProgress)>;
```


###block_red_start
**易错重灾区**

- 自 **v1.15.0** 起三个视图都是**视口虚拟化 + Label 池化**。
- 存在**两套坐标**:**源行号**(稳定,旧 API/信号用它)与**可见序**(隐藏/筛选/排序之后)。**混用是头号 bug 来源。**
- 虚拟模式下每行没有持久 `Label`;`SetTextFast` 是池 rebind 路径。
###block_red_end

## ListView

```cpp
enum class SelectionMode { Single, Extended, Multi, None };
ZSignal<int> SelectionChanged, ItemClicked, ItemDoubleClicked, ItemRightClicked;
ZSignal<std::vector<int>> SelectionChangedMulti;   ZSignal<int,bool> ItemCheckStateChanged;
float ContentToLocalX/Y(float) const;   float LocalToContentX/Y(float) const;   // v1.10.0
void AddItem(const std::wstring&);   void AddItemWidget(std::shared_ptr<Label> rich);   void SetItem(int, const std::wstring&);
std::wstring GetItemText(int) const;   int GetItemCount() const;
void SortItems(std::function<bool(const std::wstring&,const std::wstring&)>);   void ScrollToItem(int);
void BeginUpdate();   void EndUpdate();
// 虚拟化(v1.15.0)
void SetItemCount(int n);
void SetItemProvider(int n, std::function<std::wstring(int)>);
using AsyncRowFetcher = std::function<AsyncRowBatch(int first, int count, AsyncCancelToken, AsyncProgress)>;
void SetAsyncItemProvider(int n, AsyncRowFetcher);  void NotifyReset(int n = -1);  void NotifyChanged(int first, int count);
using ItemLabelProvider = std::function<void(int, Label&)>;   void SetItemLabelProvider(int n, ItemLabelProvider);
void SetAsyncLabelProvider(int n, AsyncLabelFetcher);
void SetRichTextClip(Label::RichTextClip);
void SetItemHidden(int src, bool=true);   bool IsItemHidden(int src) const;   void ClearHidden();
void SetFilter(std::function<bool(int)>);  void ClearFilter();
void SetViewComparator(std::function<bool(int,int)>);  void SortView(bool ascending=true);  void ClearViewSort();
int  VisibleCount() const;   int SourceOfVisible(int vi) const;   int VisibleOfSource(int src) const;
std::wstring TextAtVisible(int vi) const;   void SetSelectedVisible(int vi);   int GetSelectedVisible() const;
// 勾选 / 每项元数据
void SetCheckable(bool);  void SetItemChecked(int src,bool);  std::vector<int> GetCheckedIndices() const;
void SetItemDisabled(int src,bool=true);  void SetItemTextColor(int src,Color);  void SetItemToolTip(int src,const std::wstring&);
void SelectAll();  void ClearSelection();  void ClearMultiSelection();
std::vector<int> GetSelectedIndices() const;  std::vector<bool> GetSelectionStates() const;  bool IsIndexSelected(int) const;
```

###block_red_start
**易错**

- `SortItems()` 会重排 `items_` 并**清空多选/勾选**;`SortView` 只改**可见序**。
- 池化下改行文本走 `SetTextFast`,且容器宽度变化必须重测(`v1.18.0` 修:新增 `poolW_`,宽度变也重测,修省略号错位)。
- `SetFilter` / `SetViewComparator` 把 `std::function` **存在控件里**;按引用捕获外部变量会有悬空风险。虚拟模式下比较器每次都会调 `GetItemText`,大表请先快照文本,避免重复哈希查找。
- `SetItemHeight` 会把高度夹到 ≥1;但 `TableView::SetRowHeight` / `TreeView::SetRowHeight` **没有夹取**,传 0 会让行高计算/命中测试失效——行高必须 > 0。
###block_red_end

- **`版本`**:`BeginUpdate` `v1.9.6`;坐标转换 `v1.10.0`;虚拟化/隐藏/筛选/可见序 `v1.15.0`。

## TableView

```cpp
enum class SelectionMode { Cell, Row, Column, None };
static long long CellKey(int r,int c); static int CellKeyRow(long long); static int CellKeyCol(long long);
ZSignal<int,int> CellClicked, CellDoubleClicked, CurrentCellChanged, CellRightClicked;
ZSignal<int> HeaderClicked;  ZSignal<std::vector<std::pair<int,int>>> SelectionChangedCells;
void SetRowCount(int);  void SetColumnCount(int);  void BeginUpdate();  void EndUpdate();  void AppendRow/Column(); InsertRow/Column(int); RemoveRow/Column(int);
void SetItem(int row,int col,const std::wstring&);  std::wstring GetItemText(int r,int c) const;
using CellLabelProvider = std::function<void(int,int, Label&)>;   void SetCellLabelProvider(int rows,int cols,CellLabelProvider);
void SetAsyncCellLabelProvider(int rows, int cols, AsyncCellFetcher);
void SetRichTextClip(Label::RichTextClip);
void SetHeaderLabel(int,const std::wstring&);  void SetColumnWidth(int,float);   // 最小 40
void SetColumnAlignment(int, TextHAlign);   void SetRowHeight(float);  void SetRowHeightAt(int,float);
void SetColumnVisible(int,bool);
// 虚拟化(v1.15.0,全部按“源行”):SetItemHidden/SetFilter/SetViewComparator/SortView/VisibleCount/SourceOfVisible/VisibleOfSource
// 选中 / 勾选 / 元数据
void SetSelectionMode(SelectionMode);  void SetCurrentCell(int,int);  void SelectRow/Column(int);
void SelectAll();  void ClearSelection();  std::vector<std::pair<int,int>> GetSelectedCells() const;  std::vector<int> GetSelectedRows() const;
void SetCheckable(bool);  void SetRowChecked(int,bool);  void SetRowDisabled(int,bool);
void SetCellTextColor(int,int,Color);   void SetCellToolTip(int,int,const std::wstring&);
void SetColumnComparator(int, std::function<bool(const std::wstring&,const std::wstring&)>);  void SortByColumn(int,bool=true);
```

###block_red_start
**易错**

- 默认 `Cell` 选择;行/单元格元数据随插入/删除/排序**重映射**;隐藏列不参与命中。
- `SetRowHeight` 不会夹取,行高必须 > 0;传 0 会破坏行高计算/命中测试。按行覆盖的 `SetRowHeightAt` 会夹到 ≥8。
###block_red_end

## TreeNode(普通结构体)

```cpp
enum class CheckState { Unchecked, PartiallyChecked, Checked };
std::vector<std::shared_ptr<Label>> columns;   // 每列一个真实 Label;col0 = 节点文本
std::weak_ptr<TreeNode> parent;                // 弱引用!用 .lock()
std::vector<std::shared_ptr<TreeNode>> children;
bool expanded;  int depth;  void* userData;
bool hasChildren;  bool hasChildrenHinted;
std::wstring icon;  bool checkable;  CheckState checkState;  bool selected;  bool enabled;
std::wstring tooltip;   Color bgColor = Color(0,0,0,0);   // 行背景,v1.17.0
```

###block_red_start
**易错**

- `parent` 是 `weak_ptr`;行背景用 **`node->bgColor`** 直接字段(**没有** `SetNodeBackgroundColor`)。
###block_red_end

- **`版本`**:`bgColor` `v1.17.0`。

## TreeView

```cpp
enum class SelectionMode { Single, Extended, Multi };   enum class CheckMode { Linked, Independent };
ZSignal<std::shared_ptr<TreeNode>> SelectionChanged, NodeClicked, ItemDoubleClicked, ItemRightClicked;
ZSignal<std::shared_ptr<TreeNode>,bool> ExpandChanged;   ZSignal<int> HeaderClicked;
ZSignal<std::shared_ptr<TreeNode>, TreeNode::CheckState> ItemCheckStateChanged;
void SetColumnCount(int);  void SetHeaderLabels(const std::vector<std::wstring>&);  void SetColumnWidth(int,float);
using NodeLabelProvider = std::function<void(const std::shared_ptr<TreeNode>&, int, Label&)>;
void SetNodeLabelProvider(NodeLabelProvider);   void RefreshNodeLabels();
void SetAsyncNodeLabelProvider(AsyncCellFetcher);
void SetRichTextClip(Label::RichTextClip);
void SetStretchLastColumn(bool);  bool GetStretchLastColumn() const;   // v1.27.2
std::shared_ptr<TreeNode> AddRoot(const std::wstring&);   std::shared_ptr<TreeNode> AddChild(parent, const std::wstring&);
void RemoveNode(node);  void RemoveChildren(node);  void MoveNode(node, newParent, int index);  void Clear();
void BeginUpdate();  void EndUpdate();                       // v1.15.0:延后 BuildVisibleList(避免 O(N^2))
void SetLazyLoader(std::function<void(std::shared_ptr<TreeNode>)>);   // called before expanding a node
void SetNodeText(node,int col,const std::wstring&);   void SetNodeTooltip(node, ...);   void SetNodeIcon(node, ...);   void SetNodeHasChildren(node, bool);
void ExpandNode(node,bool);  void ExpandAll();  void CollapseAll();  void ExpandToDepth(int);
void SetDefaultExpandDepth(int);                             // 只影响之后插入的节点
void SetFilter(std::function<bool(const std::shared_ptr<TreeNode>&)>);   void Search(const std::wstring&);
void SetSelectionMode(SelectionMode);  void SetSelectedNode(node);  std::vector<std::shared_ptr<TreeNode>> GetSelectedNodes() const;
void SetCheckable(bool enable);  void SetCheckableShallow(bool enable);  void SetCheckMode(CheckMode);
void SetNodeCheckable(node, bool);   void SetNodeCheckableRecursive(node, bool);
void SetNodeEnabled(node, bool);     void SetNodeEnabledRecursive(node, bool);
void SetNodeCheckState(node, TreeNode::CheckState);
void SetNodeCheckStateFull(node, TreeNode::CheckState, bool updateChildren, bool updateParent);
float GetScrollOffsetY() const;   void SetScrollOffsetY(float);   void ScrollToNode(node);   // v1.17.0
```

###block_red_start
**易错**

- `Search` 保留命中节点**及其祖先链**;`SetDefaultExpandDepth` 只影响**未来**插入;`CheckMode::Linked` 自动算 `PartiallyChecked`。
- `GetVisibleNodeAt` 按**最新重建**的可见列表索引,不是节点树顺序。
- `MoveNode` 不能把节点移到自己的后代(返回 `false`,树不变);忽略返回值会误以为移动成功。
###block_red_end

- **`版本`**:`BeginUpdate`/`SetNodeText`/tooltip + 并发 `v1.15.0`;首列省略号修 `v1.16.0`;`Get/SetScrollOffsetY` + `ScrollToNode` + 节点 `bgColor` `v1.17.0`;`SetStretchLastColumn` 末列补宽 `v1.27.2`。
- **v1.27.2 列宽补充**:`SetStretchLastColumn(true)`(默认)在内容总宽小于视口时把剩余宽度补给最后一列,避免单列树中文标签被 40px 最小列宽截成 `...`;`SetStretchLastColumn(false)` 恢复固定列宽行为。
第 14 章

数据视图

ListView、TableView、TreeView、TreeNode(虚拟化、隐藏/筛选/可见序)

cpp
struct ViewLabelData { std::wstring text; std::vector<LabelRun> runs; Icon icon = Icon::None; float iconSize = 0; Color iconColor, textColor; };
struct AsyncLabelBatch { int first = 0; std::vector<ViewLabelData> rows; };
struct AsyncCellBatch { int first = 0; int cols = 0; std::vector<std::vector<ViewLabelData>> rows; };
using AsyncLabelFetcher = std::function<AsyncLabelBatch(int, int, AsyncCancelToken, AsyncProgress)>;
using AsyncCellFetcher = std::function<AsyncCellBatch(int, int, AsyncCancelToken, AsyncProgress)>;

易错重灾区

  • 自 v1.15.0 起三个视图都是视口虚拟化 + Label 池化。
  • 存在两套坐标:源行号(稳定,旧 API/信号用它)与可见序(隐藏/筛选/排序之后)。混用是头号 bug 来源。
  • 虚拟模式下每行没有持久 Label;SetTextFast 是池 rebind 路径。

ListView

cpp
enum class SelectionMode { Single, Extended, Multi, None };
ZSignal<int> SelectionChanged, ItemClicked, ItemDoubleClicked, ItemRightClicked;
ZSignal<std::vector<int>> SelectionChangedMulti;   ZSignal<int,bool> ItemCheckStateChanged;
float ContentToLocalX/Y(float) const;   float LocalToContentX/Y(float) const;   // v1.10.0
void AddItem(const std::wstring&);   void AddItemWidget(std::shared_ptr<Label> rich);   void SetItem(int, const std::wstring&);
std::wstring GetItemText(int) const;   int GetItemCount() const;
void SortItems(std::function<bool(const std::wstring&,const std::wstring&)>);   void ScrollToItem(int);
void BeginUpdate();   void EndUpdate();
// 虚拟化(v1.15.0)
void SetItemCount(int n);
void SetItemProvider(int n, std::function<std::wstring(int)>);
using AsyncRowFetcher = std::function<AsyncRowBatch(int first, int count, AsyncCancelToken, AsyncProgress)>;
void SetAsyncItemProvider(int n, AsyncRowFetcher);  void NotifyReset(int n = -1);  void NotifyChanged(int first, int count);
using ItemLabelProvider = std::function<void(int, Label&)>;   void SetItemLabelProvider(int n, ItemLabelProvider);
void SetAsyncLabelProvider(int n, AsyncLabelFetcher);
void SetRichTextClip(Label::RichTextClip);
void SetItemHidden(int src, bool=true);   bool IsItemHidden(int src) const;   void ClearHidden();
void SetFilter(std::function<bool(int)>);  void ClearFilter();
void SetViewComparator(std::function<bool(int,int)>);  void SortView(bool ascending=true);  void ClearViewSort();
int  VisibleCount() const;   int SourceOfVisible(int vi) const;   int VisibleOfSource(int src) const;
std::wstring TextAtVisible(int vi) const;   void SetSelectedVisible(int vi);   int GetSelectedVisible() const;
// 勾选 / 每项元数据
void SetCheckable(bool);  void SetItemChecked(int src,bool);  std::vector<int> GetCheckedIndices() const;
void SetItemDisabled(int src,bool=true);  void SetItemTextColor(int src,Color);  void SetItemToolTip(int src,const std::wstring&);
void SelectAll();  void ClearSelection();  void ClearMultiSelection();
std::vector<int> GetSelectedIndices() const;  std::vector<bool> GetSelectionStates() const;  bool IsIndexSelected(int) const;

易错

  • SortItems() 会重排 items_ 并清空多选/勾选;SortView 只改可见序。
  • 池化下改行文本走 SetTextFast,且容器宽度变化必须重测(v1.18.0 修:新增 poolW_,宽度变也重测,修省略号错位)。
  • SetFilter / SetViewComparator 把 std::function 存在控件里;按引用捕获外部变量会有悬空风险。虚拟模式下比较器每次都会调 GetItemText,大表请先快照文本,避免重复哈希查找。
  • SetItemHeight 会把高度夹到 ≥1;但 TableView::SetRowHeight / TreeView::SetRowHeight 没有夹取,传 0 会让行高计算/命中测试失效——行高必须 > 0。

TableView

cpp
enum class SelectionMode { Cell, Row, Column, None };
static long long CellKey(int r,int c); static int CellKeyRow(long long); static int CellKeyCol(long long);
ZSignal<int,int> CellClicked, CellDoubleClicked, CurrentCellChanged, CellRightClicked;
ZSignal<int> HeaderClicked;  ZSignal<std::vector<std::pair<int,int>>> SelectionChangedCells;
void SetRowCount(int);  void SetColumnCount(int);  void BeginUpdate();  void EndUpdate();  void AppendRow/Column(); InsertRow/Column(int); RemoveRow/Column(int);
void SetItem(int row,int col,const std::wstring&);  std::wstring GetItemText(int r,int c) const;
using CellLabelProvider = std::function<void(int,int, Label&)>;   void SetCellLabelProvider(int rows,int cols,CellLabelProvider);
void SetAsyncCellLabelProvider(int rows, int cols, AsyncCellFetcher);
void SetRichTextClip(Label::RichTextClip);
void SetHeaderLabel(int,const std::wstring&);  void SetColumnWidth(int,float);   // 最小 40
void SetColumnAlignment(int, TextHAlign);   void SetRowHeight(float);  void SetRowHeightAt(int,float);
void SetColumnVisible(int,bool);
// 虚拟化(v1.15.0,全部按“源行”):SetItemHidden/SetFilter/SetViewComparator/SortView/VisibleCount/SourceOfVisible/VisibleOfSource
// 选中 / 勾选 / 元数据
void SetSelectionMode(SelectionMode);  void SetCurrentCell(int,int);  void SelectRow/Column(int);
void SelectAll();  void ClearSelection();  std::vector<std::pair<int,int>> GetSelectedCells() const;  std::vector<int> GetSelectedRows() const;
void SetCheckable(bool);  void SetRowChecked(int,bool);  void SetRowDisabled(int,bool);
void SetCellTextColor(int,int,Color);   void SetCellToolTip(int,int,const std::wstring&);
void SetColumnComparator(int, std::function<bool(const std::wstring&,const std::wstring&)>);  void SortByColumn(int,bool=true);

易错

  • 默认 Cell 选择;行/单元格元数据随插入/删除/排序重映射;隐藏列不参与命中。
  • SetRowHeight 不会夹取,行高必须 > 0;传 0 会破坏行高计算/命中测试。按行覆盖的 SetRowHeightAt 会夹到 ≥8。

TreeNode(普通结构体)

cpp
enum class CheckState { Unchecked, PartiallyChecked, Checked };
std::vector<std::shared_ptr<Label>> columns;   // 每列一个真实 Label;col0 = 节点文本
std::weak_ptr<TreeNode> parent;                // 弱引用!用 .lock()
std::vector<std::shared_ptr<TreeNode>> children;
bool expanded;  int depth;  void* userData;
bool hasChildren;  bool hasChildrenHinted;
std::wstring icon;  bool checkable;  CheckState checkState;  bool selected;  bool enabled;
std::wstring tooltip;   Color bgColor = Color(0,0,0,0);   // 行背景,v1.17.0

易错

  • parent 是 weak_ptr;行背景用 node->bgColor 直接字段(没有 SetNodeBackgroundColor)。

TreeView

cpp
enum class SelectionMode { Single, Extended, Multi };   enum class CheckMode { Linked, Independent };
ZSignal<std::shared_ptr<TreeNode>> SelectionChanged, NodeClicked, ItemDoubleClicked, ItemRightClicked;
ZSignal<std::shared_ptr<TreeNode>,bool> ExpandChanged;   ZSignal<int> HeaderClicked;
ZSignal<std::shared_ptr<TreeNode>, TreeNode::CheckState> ItemCheckStateChanged;
void SetColumnCount(int);  void SetHeaderLabels(const std::vector<std::wstring>&);  void SetColumnWidth(int,float);
using NodeLabelProvider = std::function<void(const std::shared_ptr<TreeNode>&, int, Label&)>;
void SetNodeLabelProvider(NodeLabelProvider);   void RefreshNodeLabels();
void SetAsyncNodeLabelProvider(AsyncCellFetcher);
void SetRichTextClip(Label::RichTextClip);
void SetStretchLastColumn(bool);  bool GetStretchLastColumn() const;   // v1.27.2
std::shared_ptr<TreeNode> AddRoot(const std::wstring&);   std::shared_ptr<TreeNode> AddChild(parent, const std::wstring&);
void RemoveNode(node);  void RemoveChildren(node);  void MoveNode(node, newParent, int index);  void Clear();
void BeginUpdate();  void EndUpdate();                       // v1.15.0:延后 BuildVisibleList(避免 O(N^2))
void SetLazyLoader(std::function<void(std::shared_ptr<TreeNode>)>);   // called before expanding a node
void SetNodeText(node,int col,const std::wstring&);   void SetNodeTooltip(node, ...);   void SetNodeIcon(node, ...);   void SetNodeHasChildren(node, bool);
void ExpandNode(node,bool);  void ExpandAll();  void CollapseAll();  void ExpandToDepth(int);
void SetDefaultExpandDepth(int);                             // 只影响之后插入的节点
void SetFilter(std::function<bool(const std::shared_ptr<TreeNode>&)>);   void Search(const std::wstring&);
void SetSelectionMode(SelectionMode);  void SetSelectedNode(node);  std::vector<std::shared_ptr<TreeNode>> GetSelectedNodes() const;
void SetCheckable(bool enable);  void SetCheckableShallow(bool enable);  void SetCheckMode(CheckMode);
void SetNodeCheckable(node, bool);   void SetNodeCheckableRecursive(node, bool);
void SetNodeEnabled(node, bool);     void SetNodeEnabledRecursive(node, bool);
void SetNodeCheckState(node, TreeNode::CheckState);
void SetNodeCheckStateFull(node, TreeNode::CheckState, bool updateChildren, bool updateParent);
float GetScrollOffsetY() const;   void SetScrollOffsetY(float);   void ScrollToNode(node);   // v1.17.0

易错

  • Search 保留命中节点及其祖先链;SetDefaultExpandDepth 只影响未来插入;CheckMode::Linked 自动算 PartiallyChecked。
  • GetVisibleNodeAt 按最新重建的可见列表索引,不是节点树顺序。
  • MoveNode 不能把节点移到自己的后代(返回 false,树不变);忽略返回值会误以为移动成功。
↑