# @frontman-ai/dom-element-to-component-source 中文文档 规范地址：https://npmcn.com/package/%40frontman-ai/dom-element-to-component-source/ 版本：0\.5\.0 npm 元数据更新时间：2026-09-09T09:15:13.160Z 中文译文更新时间：2026-11-15T15:15:53.034Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40frontman-ai/dom-element-to-component-source 原文对照：https://npmcn.com/package/%40frontman-ai/dom-element-to-component-source/?lang=original 项目主页：https://github.com/frontman-ai/dom-element-to-component-source#readme 源码仓库：https://github.com/frontman-ai/dom-element-to-component-source ## 关键信息（来自 npm 元数据） - 包体积（解压后）：245 kB，21 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - Node.js 要求：\>=20\.19\.0 - 运行依赖：3 个 - 首次发布：2026-09-09T09:15:12.557Z - 最新版本发布：2026-09-09T09:15:12.880Z - 近 30 天下载量：7528（2026-10-16 至 2026-11-14，npm 官方下载统计） - 已发布版本数：1（近 12 个月 1 个） ## 中文简介 一个获取 React 应用程序中 DOM 元素源位置的库 ## 安装 ```sh npm install @frontman-ai/dom-element-to-component-source ``` 也可以使用：`pnpm add @frontman-ai/dom-element-to-component-source`、`yarn add @frontman-ai/dom-element-to-component-source`、`bun add @frontman-ai/dom-element-to-component-source` ## README # DOM 组件源元素 一个用于从 DOM 元素中查找 React JSX 源上下文的 TypeScript 库 通过源图解决 React 服务器组件位置. ## 特征 - 将选定的JSX定义与React 所有人援引祖先区分开来. - 保护客户端定义嵌入服务器所有者下方 . - 支持动态回放纤维键和有边框的向外转动. - 在一个操作中解决完整的服务器源上下文 . - 支持 Turbopack, webpack, 文件 URL, 以及地图相对源路径. - 返回结构化源解析失败 . ## 安装 ```bash yarn add dom-element-to-component-source ``` 在 npm 发布之前, 安装精确的 Git 承诺 。 包裹 `prepack` 脚本构建每个声明 `dist` 安装时导出 . ```bash yarn add dom-element-to-component-source@https://github.com/frontman-ai/dom-element-to-component-source.git# ``` ## 浏览器 API ```typescript import { getElementSourceContext } from 'dom-element-to-component-source' const button = document.querySelector('button') if (!button) throw new Error('Button not found') const result = await getElementSourceContext(button, { maxDepth: 10 }) if (!result.success) { throw new Error(result.error) } const { definition, invocations } = result.data if (definition) { console.log(`${definition.file}:${definition.line}:${definition.column}`) } for (const invocation of invocations) { console.log(`${invocation.file}:${invocation.line}:${invocation.column}`) } ``` `definition` 是被选中元素的 JSX 定义 当反应曝光. `invocations` 包含所有者呼叫站点 。 反应服务器 仍保留构成部分地点 `about://React/Server/...` URL 直至解决 服务器 API. ### 浏览器类型 ```typescript interface ElementSourceContext { definition?: SourceLocation invocations: SourceLocation[] } type ElementSourceContextResult = | { success: true; data: ElementSourceContext } | { success: false; error: string } interface ElementSourceContextOptions { maxDepth?: number } ``` ### 组件名称发现 使用 `getElementComponentName` 当只有最近符合条件的 React 组件时 需要名称。 它检查所有者 纤维之前返回 纤维最多检查 默认情况下,每个有分界线的转弯处有10个节点. ```typescript import { getElementComponentName } from 'dom-element-to-component-source' const name = getElementComponentName(element, { excludedNames: ['FrameworkWrapper'], includeUnderscorePrefixed: false, }) ``` ```typescript interface ElementComponentNameOptions { maxDepth?: number excludedNames?: readonly string[] includeUnderscorePrefixed?: boolean } ``` `Fragment` 财务报告和审定财务报表 `Suspense` 总是被忽略。 通知人除外情形被添加到 这些结构性排斥。 除非 `includeUnderscorePrefixed` 实值 `false`。 。 。 . ## 服务器 API 从专用服务器条目导入服务器功能 。 永远不要导入 输入浏览器代码. ```typescript import { resolveElementSourceContext } from 'dom-element-to-component-source/server' const result = await resolveElementSourceContext(context, { projectRoot: '/absolute/path/to/project', }) if (!result.success) { console.error(result.error.code, result.error.message) return } console.log(result.data.definition) console.log(result.data.invocations) ``` 解析器保存普通位置并解决每个 `about://React/Server/file:///...` 定义和援引。 生成的文件 和源地图必须在峡谷内解决 `projectRoot` 在他们之前 读取. 返回源路径是不可信的输出 。 原始源图条目可能 外部解决 `projectRoot` 并且不需要存在。 消费者必须批准 每一个返回的路径 之前揭露它或从它阅读。 消费者政策可以 包括允许的源根,存在检查, cononical symlink 封存, 并转换为相对路径. Next.js 应用程序应该将这个软件包外部化. 私人活动 `source-map` 依赖性仍然是执行细节,可以装载相邻的 `mappings.wasm` 运行时的文件 : ```javascript module.exports = { serverExternalPackages: ['dom-element-to-component-source'], } ``` ### 服务器结果 ```typescript type SourceResolutionResult = | { success: true; data: ElementSourceContext } | { success: false error: { code: | 'INVALID_REACT_URL' | 'GENERATED_FILE_NOT_FOUND' | 'SOURCE_MAP_NOT_FOUND' | 'POSITION_NOT_FOUND' | 'RESOLUTION_FAILED' message: string } } ``` ## 来源位置 ```typescript interface SourceLocation { file: string line: number column: number componentName?: string tagName?: string sourceCode?: string componentProps?: Record } ``` ## 所需资源 - 节点.js 20.19或服务器分辨率更新. - 反应开发元数据用于浏览器提取. - React 服务器组件分辨率的源地图. ## 发展 ```bash yarn install --immutable yarn test:run yarn type-check yarn build yarn pack --dry-run ``` ## 许可证 麻省理工学院 ## 常见问题 ### @frontman-ai/dom-element-to-component-source 是什么？ 一个获取 React 应用程序中 DOM 元素源位置的库 ### 如何安装 @frontman-ai/dom-element-to-component-source？ 在项目目录运行 npm install @frontman-ai/dom-element-to-component-source，或使用 pnpm add / yarn add / bun add。 ### @frontman-ai/dom-element-to-component-source 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @frontman-ai/dom-element-to-component-source 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @frontman-ai/dom-element-to-component-source 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=20\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @frontman-ai/dom-element-to-component-source 可以商用吗？ @frontman-ai/dom-element-to-component-source 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @frontman-ai/dom-element-to-component-source 的下载量有多少？ 根据 npm 官方下载统计，@frontman-ai/dom-element-to-component-source 在 2026/10/16 – 2026/11/14 这 30 天内被下载 7,528 次，日均约 251 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @frontman-ai/dom-element-to-component-source 还在维护吗？ 最新版本 0\.5\.0 发布于 2026/09/09（2 个月前）；至今共发布 1 个版本，其中过去 12 个月发布了 1 个；首次发布于 2026/09/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。