{"_id":"@dao3fun/ui-path-find","_rev":"2-8a45654b2f5e23139f5e21e97acfd279","name":"@dao3fun/ui-path-find","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@dao3fun/ui-path-find","version":"1.0.0","author":{"name":"冷鱼闲风"},"license":"ISC","_id":"@dao3fun/ui-path-find@1.0.0","maintainers":[{"name":"viyrs","email":"2991883280@qq.com"},{"name":"surfish","email":"surfish.fun@outlook.com"},{"name":"tobylai","email":"toby_lai@126.com"},{"name":"studentnumber2","email":"pzh123gxy2023@163.com"},{"name":"l.w.kevin0wvf","email":"Qck320923@163.com"},{"name":"onloading","email":"605952607@qq.com"},{"name":"whale303","email":"little_whale303@outlook.com"}],"dist":{"shasum":"6b245e82afd6e7cdf683eb0ca22febdaf9218391","tarball":"https://registry.npmjs.org/@dao3fun/ui-path-find/-/ui-path-find-1.0.0.tgz","fileCount":4,"integrity":"sha512-q1btXLLPey5B+ghWN43T4UHzHlOuaI+iY5VXFml48PPBi6RDVuKHTAauqqTg1mD5pkvOTdLh5i29lcZU+AlVPQ==","signatures":[{"sig":"MEUCIQDYmo+7fK05O8cC/VlgWot9rLB0H5RftMgrniaAdKhDWAIgHCAFhAAWEdxakQEJ+Cr3qe6Ph8P1jVi/v1hnhv2y7uw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":6323},"main":"client/dist/client/src/clientApp.js","types":"client/dist/client/src/clientApp.d.ts","scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"_npmUser":{"name":"viyrs","actor":{"name":"viyrs","type":"user","email":"2991883280@qq.com"},"email":"2991883280@qq.com"},"_npmVersion":"10.9.2","description":"`findChildByPath` 是一个高效的 UI 节点查找工具，专门用于在神岛项目开发中替代冗长、繁琐的 `findChildByName` 链式调用。","directories":{},"_nodeVersion":"23.11.0","_hasShrinkwrap":false,"devDependencies":{"acorn":"^8.15.0","webpack":"^5.100.0","ts-loader":"^9.5.2","typescript":"^5.8.3","webpack-cli":"^6.0.1","terser-webpack-plugin":"^5.3.14"},"_npmOperationalInternal":{"tmp":"tmp/ui-path-find_1.0.0_1752161621995_0.8563152129866256","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2025-07-10T15:33:41.904Z","modified":"2025-07-17T09:04:44.165Z","1.0.0":"2025-07-10T15:33:42.218Z"},"author":{"name":"冷鱼闲风"},"license":"ISC","description":"`findChildByPath` 是一个高效的 UI 节点查找工具，专门用于在神岛项目开发中替代冗长、繁琐的 `findChildByName` 链式调用。","maintainers":[{"email":"2991883280@qq.com","name":"viyrs"},{"email":"surfish.fun@outlook.com","name":"surfish"},{"email":"toby_lai@126.com","name":"tobylai"},{"email":"pzh123gxy2023@163.com","name":"studentnumber2"},{"email":"Qck320923@163.com","name":"l.w.kevin0wvf"},{"email":"605952607@qq.com","name":"onloading"},{"email":"little_whale303@outlook.com","name":"whale303"},{"email":"863489539@qq.com","name":"syhdarkforest"}],"readme":"# `findChildByPath` - 神岛 UI 路径查询\n\n`@dao3fun/ui-path-find` 是一个高效的 UI 节点查找工具，专门用于在神岛项目开发中替代冗长、繁琐的 `findChildByName` 链式调用。\n\n## 解决的问题\n\n在处理复杂的 UI 层级时，我们经常需要编写如下代码来定位一个深层嵌套的节点：\n\n```javascript\nconst targetNode = UiScreen.getAllScreen()\n  .find((obj) => obj.name === \"screen\")\n  ?.findChildByName(\"player-1\")\n  ?.findChildByName(\"player-3\")\n  ?.findChildByName(\"player-4\")\n  ?.findChildByName(\"input-3\");\n```\n\n这种方式存在几个显著的缺点：\n\n- **可读性差**：代码冗长，难以一眼看出节点的完整路径。\n- **维护困难**：一旦 UI 结构调整，修改这条长链将非常痛苦且容易出错。\n- **调试不便**：如果中间某个节点未找到，整个表达式只会返回 `undefined`，你很难快速定位到具体是哪一环出了问题。\n\n## `findChildByPath` 解决方案\n\n本工具通过一个清晰的路径字符串来解决以上所有问题，让节点查找变得简单直观：\n\n```typescript\nimport findChildByPath from \"@dao3fun/ui-path-find\";\n\nconst targetNode = findChildByPath<UiInput>(\n  \"screen/player-1/player-3/player-4/input-3\"\n);\nconsole.log(targetNode?.name);\n```\n\n## 核心优势\n\n- **简洁可读**：用直观的路径字符串替代了繁琐的方法链，代码更易于理解和维护。\n- **精准的错误提示**：当路径中的某个节点未找到时，它会在控制台明确指出查找失败的位置，帮助你快速定位并修复问题。\n- **高效的缓存机制**：\n  - **根节点缓存**：首次执行时会自动缓存所有屏幕（根节点），避免重复调用 `getAllScreen()`。\n  - **路径查找缓存**：缓存每个路径的查找结果。后续对同一路径的查询会直接从缓存中读取，大大提升了执行效率。\n\n## 使用方法\n\n1.  **引入函数**：在你的代码文件中引入 `findChildByPath`。\n\n    ```typescript\n    import findChildByPath from \"@dao3fun/ui-path-find\";\n    ```\n\n2.  **调用函数**：传入节点的访问路径和期望的返回类型即可。\n\n    ```typescript\n    // 查找一个screen屏幕下的 UiImage 类型的节点\n    const image = findChildByPath<UiImage>(\"screen/mainPanel/header/logo\");\n\n    // 查找一个screen2屏幕下的 UiText 类型的节点\n    const label = findChildByPath<UiText>(\n      \"screen2/mainPanel/footer/copyrightLabel\"\n    );\n    ```\n\n## API\n\n```typescript\nexport function findChildByPath<T extends UiElement>(\n  path: UiNodePath\n): T | undefined;\n```\n\n- **`T` (泛型)**: 你期望返回的节点类型，例如 `UiImage`、`UiText` 等，它继承自 `UiElement`。\n- **`path` (UiNodePath)**: 节点的访问路径，由节点名称和 `/` 组成，例如 `\"screen/ui-1/ui-2/ui-3\"`。\n- **返回值**: 如果找到，返回对应类型的 UI 节点；如果未找到，则返回 `undefined` 并在控制台打印错误信息。\n","readmeFilename":"README.md"}