# @fullstory/babel-plugin-annotate-react 中文文档 规范地址：https://npmcn.com/package/%40fullstory/babel-plugin-annotate-react/ 版本：2\.4\.1 npm 元数据更新时间：2026-09-30T20:20:10.660Z 中文译文更新时间：2026-11-15T16:49:30.043Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40fullstory/babel-plugin-annotate-react 原文对照：https://npmcn.com/package/%40fullstory/babel-plugin-annotate-react/?lang=original 项目主页：https://github.com/fullstorydev/fullstory-babel-plugin-annotate-react 源码仓库：https://github.com/fullstory-babel-plugin-annotate-react ## 关键信息（来自 npm 元数据） - 包体积（解压后）：41.1 kB，10 个文件 - 模块格式：CommonJS - TypeScript 类型：未声明 - Node.js 要求：\>=16\.20\.2 - 运行依赖：0 个 - 首次发布：2020-05-29T17:00:43.655Z - 最新版本发布：2026-09-30T20:20:10.459Z - 近 30 天下载量：415462（2026-10-16 至 2026-11-14，npm 官方下载统计） - 已发布版本数：16（近 12 个月 2 个） ## 中文简介 一个批注反应组件的 Babel 插件, 使其更容易通过 FullStory 搜索目标 ## 安装 ```sh npm install @fullstory/babel-plugin-annotate-react ``` 也可以使用：`pnpm add @fullstory/babel-plugin-annotate-react`、`yarn add @fullstory/babel-plugin-annotate-react`、`bun add @fullstory/babel-plugin-annotate-react` ## README # Babel 插件: 注释反应 [![CircleCI](https://circleci.com/gh/fullstorydev/fullstory-babel-plugin-annotate-react.svg?style=svg)](https://circleci.com/gh/fullstorydev/fullstory-babel-plugin-annotate-react) 这是一个 Babel 插件, 用于注释具有稳定属性的组件, 用于搜索和选择 [完整的故事](https://www.fullstory.com/)。这在使用生成组件或重排元素动态名称的反应系统时最为有用. # 开始 ## 以 npm 为单位 ``` npm i @fullstory/babel-plugin-annotate-react --save ``` ## 用纱线 ``` yarn add @fullstory/babel-plugin-annotate-react ``` ## Babel 配置 添加数据 `@fullstory/babel-plugin-annotate-react` 插件到您的 babel 插件配置( 例如 ), **(原始内容存档于2013-10-12). bayl.config.js**) (中文(简体) ). ``` module.exports = { /* ... */ plugins: [ /* ... */ "@fullstory/babel-plugin-annotate-react" ] }; ``` # 说明 对于网络上的响应, 属性 `data-component`, (中文(简体) ), `data-element`,以及 `data-source-file` 在每个元素中添加。 对于反应原生,添加的属性是 `dataComponent`, (中文(简体) ), `dataElement`,以及 `dataSourceFile`。 。 。 . > 请注意,对于网络和本地,这些属性将显示为 _**弹匣**_ 在Fullstory应用程序中,由于后端处理。 Fullstory 的终端用户应使用 _**弹匣**_。 。 。 . 组件属性名称 `React.Component` 和元素属性名称 `View` 或者说 `Image` 或诸如DOM元素的发射器 `Fragment`。 。 。 . 示例输入 : ``` class HelloComponent extends Component { render() { return

Hello world

; } } ``` 联合来文产出实例: ``` class HelloComponent extends Component { render() { return React.createElement("div", { "data-component": "HelloComponent", "data-file-source": "hello-component.js" }, React.createElement("h1", { null }, "Hello world")); } } ``` 最后意见: ```

Hello world

``` # 配置选项 ## 原生反应 要激活原始支持, 您必须在 `native` 类似插件选项 : ``` plugins: [ ["@fullstory/babel-plugin-annotate-react", { native: true }] ] ``` 见 [以 FullStory 反应本地捕获开始](https://help.fullstory.com/hc/en-us/articles/360052419133-Getting-Started-with-FullStory-React-Native-Capture) 需要更多信息. ### `setFSTagName` 设置 当使用此库时 [移动应用程序的完整故事](https://www.fullstory.com/platform/mobile-apps/)我们建议设定 `setFSTagName: true` 生成更好的隐私选择器。 此设置将自动设定 [`fsTagName`](https://developer.fullstory.com/mobile/react-native/auto-capture/set-tag-name/) 值为 `dataElement` 或者说 `dataComponent`,它将缩短隐私选择器,并避免重复命名. 示例 - 在此之前 `RCTSafeAreaView[data-source-file="App.tsx"][data-element="SafeAreaView"][data-component="App"]` - 之后 `App[data-source-file="App.tsx"]` ``` plugins: [ '@fullstory/react-native', ["@fullstory/annotate-react", { native: true, setFSTagName: true, }] ] ``` QQ 重要: 现有全史隐私选择器和被定义的元素如果应用程序之前没有发布,可能需要更新 `setFSTagName: true`。 。 。 . ## 碎片 默认情况下, 插件没有注释 `React.Fragment`s 因为它们可能包含也可能不包含一个最终成为HTML元素的孩子. 一个没有儿童因素的例子: ``` const componentName = () => ( Hello, there. ); ``` 儿童因素的例子: ``` const componentName = () => ( Some text

Hello, there.

/* This one could be annotated */ Click me ); ``` 如果您希望插件尝试对由碎片( 如果存在) 创建的第一个 HTML 元素进行注释, 请设置 `annotate-fragments` 旗帜 : ``` plugins: [ ["@fullstory/babel-plugin-annotate-react", { "annotate-fragments": true }] ] ``` ## React 编译器 如果您的项目使用 [React 编译器](https://react.dev/learn/react-compiler),启用 `reactCompiler` 选项 : ```javascript plugins: [ ["@fullstory/babel-plugin-annotate-react", { reactCompiler: true }] ] ``` React 编译器通过取出 JSX 子树来优化功能组件 `return` 声明为中间缓存变量。 这意味着编译的组件可能看起来像: ```javascript // Before React Compiler function MyComponent() { return
Hello
; } // After React Compiler (simplified) function MyComponent() { let t0; if ($[0] === Symbol.for("react.memo_cache_sentinel")) { t0 =
Hello
; $[0] = t0; } return t0; } ``` 无 `reactCompiler: true`,插件将看到一个非JSX `return` 语句并全部跳过组件,不产生注释。 启用此选项后, 插件会穿过整个函数机构找到并注释所有 JSX 节点, 不管它们在哪里出现 . ⚠️ **重要内容:** 因为反应编译器会调整JSX的发射方式,从而能够 `reactCompiler: true` 可能改变JSX节点的注释。 在启用此选项后, 选择器和先前在 Fullstory 中定义的已命名元素不保证匹配 。 启用此设置后审查您已有的片段、 度量和定义的元素 . ## 忽略组件 如果您希望插件跳过某些组件的注释, 请使用 `ignoreComponents` 选项 : ```javascript plugins: [ [ "@fullstory/annotate-react", { ignoreComponents:[ // each item must be a string array containing three items: file name, component name, element name // corresponding to the values for data-source-file, data-component, data-element // use wild card (*) to match anything ["myBoxComponent.jsx","MyBox","Box"], ["App.jsx", "*", "ThemeProvider"], // use wild-card to match anything ["App.jsx", "App", "*"], ] } ], ] ``` ## 应用程序样本 我们有一些样本可以演示这个插件: - [单页 App](https://github.com/fullstorydev/fullstory-babel-plugin-annotate-react/tree/master/samples/single-page-app/) - [样式组件](https://github.com/fullstorydev/fullstory-babel-plugin-annotate-react/tree/master/samples/styled-components/) - [本地反应](https://github.com/fullstorydev/fullstory-babel-plugin-annotate-react/tree/master/samples/react-native-app/) 添加属性的许多逻辑来源于 [变换反应- qa 类](https://github.com/davesnx/babel-plugin-transform-react-qa-classes/) 插件 . ## 获取帮助 请参看我们 [知识基础文章](https://help.fullstory.com/hc/en-us/articles/360049493054-FullStory-s-Annotate-React-plugin-for-Web-Native) 或联系人 [移动支持@ fullstory.com](mailto:mobile-support@fullstory.com) 需要额外的帮助. ### 原生反应 请看我们的 [以 FullStory 反应本地捕获开始](https://help.fullstory.com/hc/en-us/articles/360052419133) 指南或电子邮件 [移动支持@ fullstory.com](mailto:mobile-support@fullstory.com) 需要额外的帮助. ## 常见问题 ### @fullstory/babel-plugin-annotate-react 是什么？ 一个批注反应组件的 Babel 插件, 使其更容易通过 FullStory 搜索目标 ### 如何安装 @fullstory/babel-plugin-annotate-react？ 在项目目录运行 npm install @fullstory/babel-plugin-annotate-react，或使用 pnpm add / yarn add / bun add。 ### @fullstory/babel-plugin-annotate-react 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/fullstory\_\_babel-plugin-annotate-react 是否存在。 ### @fullstory/babel-plugin-annotate-react 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @fullstory/babel-plugin-annotate-react 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=16\.20\.2。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @fullstory/babel-plugin-annotate-react 可以商用吗？ @fullstory/babel-plugin-annotate-react 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @fullstory/babel-plugin-annotate-react 的下载量有多少？ 根据 npm 官方下载统计，@fullstory/babel-plugin-annotate-react 在 2026/10/16 – 2026/11/14 这 30 天内被下载 415,462 次，日均约 13,849 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @fullstory/babel-plugin-annotate-react 还在维护吗？ 最新版本 2\.4\.1 发布于 2026/10/01（1 个月前）；至今共发布 16 个版本，其中过去 12 个月发布了 2 个；首次发布于 2020/05/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。