Events

事件	回调参数	说明
`update:modelValue`	`(value: TreeModelValue)`	选中值变化（配合 `v-model`）
`check-change`	`(payload: TreeCheckChangePayload)`	选中状态变化
`expand-change`	`(payload: TreeExpandPayload)`	节点展开/收起
`node-click`	`(payload: TreeNodeClickPayload)`	点击节点行
`load`	`(payload: TreeLoadPayload)`	懒加载成功
`load-error`	`(payload: TreeLoadErrorPayload)`	懒加载失败
`filter-change`	`(payload: TreeFilterPayload)`	过滤结果变化

非懒加载模式下，如果受控 modelValue 中的 key 因 data 更新而不再存在，组件会通过 update:modelValue 回传清理后的值。该过程属于数据对账，没有可作为“本次操作节点”的合法节点，因此不会额外触发 check-change。父组件仍需接收并更新受控值。

filter-change 在以下情况下触发：组件初始化时已有非空 filter-value；过滤值或 filter-method 改变；非空过滤期间，data 替换或懒加载结果使状态树更新。清空已有过滤条件也会触发一次。未启用过滤时，普通展开/收起和数据更新不会触发该事件。

事件参数结构（Payload）

TreeCheckChangePayload

interface TreeCheckChangePayload {
  value: TreeModelValue;       // 新的 v-model 值
  keys: TreeKey[];             // 当前全部选中 keys
  nodes: TreeNode[];           // 当前全部选中节点
  halfCheckedKeys: TreeKey[];  // 当前半选 keys（严格模式或单选时为空）
  halfCheckedNodes: TreeNode[]; // 当前半选节点
  node: TreeNode;              // 本次触发变化的节点
}

TreeExpandPayload

interface TreeExpandPayload {
  expanded: boolean; // 变化后的展开状态：true 展开，false 收起
  node: TreeNode;    // 本次展开/收起的节点
}

TreeNodeClickPayload

interface TreeNodeClickPayload {
  id: TreeKey;      // 被点击节点的 key
  node: TreeNode;   // 被点击的节点
  path: TreeNode[]; // 根到该节点的路径（含自身）
}

TreeLoadPayload / TreeLoadErrorPayload

interface TreeLoadPayload {
  node: TreeNode;           // 完成加载的节点
  children: TreeDataItem[]; // load-api 本次返回的子节点数据
}

interface TreeLoadErrorPayload {
  node: TreeNode; // 加载失败的节点，停留在失败态可重试
  error: unknown; // load-api 抛出或 Promise 拒绝时的错误
}

TreeFilterPayload

interface TreeFilterPayload {
  value: string;             // 当前关键词
  keys: TreeKey[];           // 最终可见 keys：直接命中 + 祖先 + 后代
  nodes: TreeNode[];         // 最终可见节点
  matchedKeys: TreeKey[];    // 仅直接通过默认/自定义规则命中的 keys
  matchedNodes: TreeNode[];  // 仅直接命中的节点
}

关键词为空时不过滤，keys/nodes 表示当前展开状态下的可见节点，matchedKeys/matchedNodes 为空数组。

Events ​

事件参数结构（Payload） ​

TreeCheckChangePayload ​

TreeExpandPayload ​

TreeNodeClickPayload ​

TreeLoadPayload / TreeLoadErrorPayload ​

TreeFilterPayload ​