面向 AI 智能体:本页的「阅读辅助」区块内含有与正文完全一致的原始 Markdown 源码,已去除 HTML 标签与动画特效。建议 AI 直接读取该区块,以更低的噪声快速理解内容。
> 拖放由 `ZufyUIDragDrop.h` 提供(`ZufyUI.h` 末尾已包含)。应用内默认 MOVE,跨应用 COPY。

```cpp
// ---- 拖放:载荷 / 事件 ----
class DragData {                                   // 拖入方只读访问
    bool HasText() const;   std::wstring GetText() const;
    bool HasFiles() const;  std::vector<std::wstring> GetFiles() const;
    bool HasFormat(const std::wstring& fmt) const;
    bool GetFormatData(const std::wstring& fmt, std::vector<BYTE>& out) const;
};
struct DragEventArgs { const DragData& data; float x, y; DWORD allowed, effect, keyState; };   // x/y 为元素相对 DIP

// ---- 拖放:源端发起 ----
class DragDataBuilder {
    DragDataBuilder& AddText(const std::wstring&);
    DragDataBuilder& AddFile(const std::wstring& path);
    DragDataBuilder& AddFiles(const std::vector<std::wstring>& paths);
    DragDataBuilder& AddCustom(const std::wstring& fmt, const void* bytes, size_t n);
    DragDataBuilder& SetPreferredEffect(DWORD);
};
DWORD Window::BeginDrag(DragDataBuilder&, DWORD allowed = COPY|MOVE|LINK, UIElement* source = nullptr);

// ---- 拖放:目标端(元素)----
void UIElement::SetDropTargetEnabled(bool);   bool IsDropTargetEnabled() const;
DWORD UIElement::GetAllowedDropEffects() const;                   // 默认 COPY|MOVE|LINK
DWORD UIElement::OnDragEnter/OnDragOver(DragEventArgs&);         // 返回 effect
void  UIElement::OnDragLeave(DragEventArgs&);   DWORD UIElement::OnDrop(DragEventArgs&);
void UIElement::SetDragSource(std::function<void(DragDataBuilder&)>, DWORD allowed = COPY|MOVE|LINK);
ZSignal<DragEventArgs&> DragEnter, DragOver, DragLeave, Drop;

// ---- 拖放:整窗接收(光标未命中任何“启用落点”的元素时由窗口接收)----
void Window::SetDropTargetEnabled(bool);   bool Window::IsDropTargetEnabled() const;
ZSignal<DragEventArgs&> Window::DragEnter, DragOver, DragLeave, Drop;   // x/y = 客户区 DIP

// ---- Expander:可折叠卡片 ----
class Expander : public UIElement {
    Expander(const std::wstring& title = L"", const std::wstring& subtitle = L"");
    void SetTitle/SetSubtitle(const std::wstring&);   void SetContent(std::shared_ptr<UIElement>);
    std::shared_ptr<UIElement> GetContent() const;
    void SetExpanded(bool);   bool IsExpanded() const;   void Toggle();
    void SetIcon(Icon, float size = 22.0f);   // 标题前图标(None = 无)
    ZSignal<bool> ExpandedChanged;
};

// ---- SettingsList:设置行列表 ----
class SettingsList : public UIElement {
    void AddRow(Icon, const std::wstring& text, const std::wstring& subtitle, std::function<void()> onClick, const std::wstring& id = {});
    ZSignal<int> RowClicked;
};
```
- 同控件内文本拖动:源端先删原选区、再按落点插入并左移修正;目标端检测私有格式 `ZufyUI.TextSource` 跳过重复插入。

###block_red_start
**易错**

- `DragEventArgs.x/y` 是**元素相对 DIP**(不是屏幕像素)。
- `Expander` 的展开高度由动画进度进入 `Measure`,不再写用户可见的 `height_`;父布局仍会随动画收拢/推开后续元素。
- 初始折叠时也会测量一次 content;展开状态的内容始终留在 `childrenView_` 中,避免折叠再展开后内容不显示。
- 内容裁剪会留 at least 4px bleed(并叠加 content 自身 bleed),避免 ComboBox 边框/阴影/焦点环被切。
###block_red_end

- **`版本`**:折叠/展开用与页面切换相同的 **smoothstep 缓动**;箭头随同一缓动**旋转**(收起向下 → 展开向上)。`v1.26.0` 修复首次展开未测量、折叠再展开内容丢失和内容裁剪。
- **`版本`**:标题条悬停**高亮**(圆角);`ComboBox` 下拉箭头同样改为随展开**旋转**的 chevron。
- 图片展示用 `Label`:`SetImage` + `SetImageFit(true)`(等比缩放至完整可见)+ `SetDragSource`(拖出)。
- **`版本`**:整窗接收——`Window::SetDropTargetEnabled(true)` + 窗口级 `DragEnter/DragOver/DragLeave/Drop`(`x/y` 为客户区 DIP)。
- **`版本`**:`Expander::SetIcon(Icon, size)` 在标题前加图标;`TextEdit` 撤销/重做改为标准方案(撤销/重做都还原当时的选区与光标)。
第 17 章

拖放与卡片组件

Drag & Drop、Expander、SettingsList(v1.19.0)

拖放由 ZufyUIDragDrop.h 提供(ZufyUI.h 末尾已包含)。应用内默认 MOVE,跨应用 COPY。

cpp
// ---- 拖放:载荷 / 事件 ----
class DragData {                                   // 拖入方只读访问
    bool HasText() const;   std::wstring GetText() const;
    bool HasFiles() const;  std::vector<std::wstring> GetFiles() const;
    bool HasFormat(const std::wstring& fmt) const;
    bool GetFormatData(const std::wstring& fmt, std::vector<BYTE>& out) const;
};
struct DragEventArgs { const DragData& data; float x, y; DWORD allowed, effect, keyState; };   // x/y 为元素相对 DIP

// ---- 拖放:源端发起 ----
class DragDataBuilder {
    DragDataBuilder& AddText(const std::wstring&);
    DragDataBuilder& AddFile(const std::wstring& path);
    DragDataBuilder& AddFiles(const std::vector<std::wstring>& paths);
    DragDataBuilder& AddCustom(const std::wstring& fmt, const void* bytes, size_t n);
    DragDataBuilder& SetPreferredEffect(DWORD);
};
DWORD Window::BeginDrag(DragDataBuilder&, DWORD allowed = COPY|MOVE|LINK, UIElement* source = nullptr);

// ---- 拖放:目标端(元素)----
void UIElement::SetDropTargetEnabled(bool);   bool IsDropTargetEnabled() const;
DWORD UIElement::GetAllowedDropEffects() const;                   // 默认 COPY|MOVE|LINK
DWORD UIElement::OnDragEnter/OnDragOver(DragEventArgs&);         // 返回 effect
void  UIElement::OnDragLeave(DragEventArgs&);   DWORD UIElement::OnDrop(DragEventArgs&);
void UIElement::SetDragSource(std::function<void(DragDataBuilder&)>, DWORD allowed = COPY|MOVE|LINK);
ZSignal<DragEventArgs&> DragEnter, DragOver, DragLeave, Drop;

// ---- 拖放:整窗接收(光标未命中任何“启用落点”的元素时由窗口接收)----
void Window::SetDropTargetEnabled(bool);   bool Window::IsDropTargetEnabled() const;
ZSignal<DragEventArgs&> Window::DragEnter, DragOver, DragLeave, Drop;   // x/y = 客户区 DIP

// ---- Expander:可折叠卡片 ----
class Expander : public UIElement {
    Expander(const std::wstring& title = L"", const std::wstring& subtitle = L"");
    void SetTitle/SetSubtitle(const std::wstring&);   void SetContent(std::shared_ptr<UIElement>);
    std::shared_ptr<UIElement> GetContent() const;
    void SetExpanded(bool);   bool IsExpanded() const;   void Toggle();
    void SetIcon(Icon, float size = 22.0f);   // 标题前图标(None = 无)
    ZSignal<bool> ExpandedChanged;
};

// ---- SettingsList:设置行列表 ----
class SettingsList : public UIElement {
    void AddRow(Icon, const std::wstring& text, const std::wstring& subtitle, std::function<void()> onClick, const std::wstring& id = {});
    ZSignal<int> RowClicked;
};

易错

  • DragEventArgs.x/y 是元素相对 DIP(不是屏幕像素)。
  • Expander 的展开高度由动画进度进入 Measure,不再写用户可见的 height_;父布局仍会随动画收拢/推开后续元素。
  • 初始折叠时也会测量一次 content;展开状态的内容始终留在 childrenView_ 中,避免折叠再展开后内容不显示。
  • 内容裁剪会留 at least 4px bleed(并叠加 content 自身 bleed),避免 ComboBox 边框/阴影/焦点环被切。
↑