findChildByPath - 神岛 UI 路径查询

@dao3fun/ui-path-find 是一个高效的 UI 节点查找工具，专门用于在神岛项目开发中替代冗长、繁琐的 findChildByName 链式调用。

解决的问题

在处理复杂的 UI 层级时，我们经常需要编写如下代码来定位一个深层嵌套的节点：

const targetNode = UiScreen.getAllScreen()
  .find((obj) => obj.name === "screen")
  ?.findChildByName("player-1")
  ?.findChildByName("player-3")
  ?.findChildByName("player-4")
  ?.findChildByName("input-3");

这种方式存在几个显著的缺点：

• 可读性差：代码冗长，难以一眼看出节点的完整路径。
• 维护困难：一旦 UI 结构调整，修改这条长链将非常痛苦且容易出错。
• 调试不便：如果中间某个节点未找到，整个表达式只会返回 undefined，你很难快速定位到具体是哪一环出了问题。

findChildByPath 解决方案

本工具通过一个清晰的路径字符串来解决以上所有问题，让节点查找变得简单直观：

import findChildByPath from "@dao3fun/ui-path-find";

const targetNode = findChildByPath<UiInput>(
  "screen/player-1/player-3/player-4/input-3"
);
console.log(targetNode?.name);

核心优势

• 简洁可读：用直观的路径字符串替代了繁琐的方法链，代码更易于理解和维护。
• 精准的错误提示：当路径中的某个节点未找到时，它会在控制台明确指出查找失败的位置，帮助你快速定位并修复问题。
• 高效的缓存机制：
  • 根节点缓存：首次执行时会自动缓存所有屏幕（根节点），避免重复调用 getAllScreen()。
  • 路径查找缓存：缓存每个路径的查找结果。后续对同一路径的查询会直接从缓存中读取，大大提升了执行效率。

使用方法

1. 引入函数：在你的代码文件中引入 findChildByPath。

   import findChildByPath from "@dao3fun/ui-path-find";

2. 调用函数：传入节点的访问路径和期望的返回类型即可。

   // 查找一个screen屏幕下的 UiImage 类型的节点
   const image = findChildByPath<UiImage>("screen/mainPanel/header/logo");
   
   // 查找一个screen2屏幕下的 UiText 类型的节点
   const label = findChildByPath<UiText>(
     "screen2/mainPanel/footer/copyrightLabel"
   );

API

export function findChildByPath<T extends UiElement>(
  path: UiNodePath
): T | undefined;

• T (泛型): 你期望返回的节点类型，例如 UiImage、UiText 等，它继承自 UiElement。
• path (UiNodePath): 节点的访问路径，由节点名称和 / 组成，例如 "screen/ui-1/ui-2/ui-3"。
• 返回值: 如果找到，返回对应类型的 UI 节点；如果未找到，则返回 undefined 并在控制台打印错误信息。