# @featbit/react-client-sdk 中文文档 规范地址：https://npmcn.com/package/%40featbit/react-client-sdk/ 版本：4\.4\.2 npm 元数据更新时间：2026-11-04T09:29:48.369Z 中文译文更新时间：2026-11-14T12:49:27.805Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40featbit/react-client-sdk 原文对照：https://npmcn.com/package/%40featbit/react-client-sdk/?lang=original 项目主页：https://www.featbit.co/ 源码仓库：https://github.com/featbit/featbit-react-client-sdk ## 关键信息（来自 npm 元数据） - 包体积（解压后）：124 kB，55 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：3 个 - peer 依赖：react ^16\.6\.3 \|\| ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^16\.8\.4 \|\| ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0 - 首次发布：2024-05-01T08:43:10.448Z - 最新版本发布：2026-11-04T09:29:48.216Z - 近 30 天下载量：47034（2026-10-15 至 2026-11-13，npm 官方下载统计） - 已发布版本数：38（近 12 个月 20 个） ## 中文简介 FeatBit 客户端 SDK 反应 ## 安装 ```sh npm install @featbit/react-client-sdk ``` 也可以使用：`pnpm add @featbit/react-client-sdk`、`yarn add @featbit/react-client-sdk`、`bun add @featbit/react-client-sdk` ## README # FeatBit 客户端- Side SDK 用于 ReactJS ## 导言 这是功能管理平台的 React 客户端 SDK [费特比特](https://www.featbit.co/)。 。 。 . 要注意,这是客户端SDK,它打算用于单用户上下文,可以是移动,桌面或嵌入式应用程序. 此 SDK 只能在浏览器环境中运行, 不适合 React Industrial 项目 . 如果你要找回原生SDK 请检查这个 [反应原生 SDK](https://github.com/featbit/featbit-react-native-sdk)。 。 。 . > 反应 SDK 基于 JavaScript SDK > React SDK基于FeatBit的JavaScript SDK,为React应用提供更好的集成. 因此,JavaScript SDK的大部分功能也可供React SDK使用. > SDK 版本兼容性 > React SDK与16.3.0和更高版本的React兼容. 反应SDK提供两个自定义钩. 如果想要使用这些,则必须使用16.8.0或更高版本的React. 要学得更多,读一下这个 [使用钩子](https://npmcn.com/package/%40featbit/react-client-sdk/#readme-using-hooks)。 。 。 . > 与 Next.js 一起使用 如果您使用 Next.js 的 SDK 工程, 请注意 SDK 与服务器侧面渲染不兼容 。 你应该只用客户端的SDK. 如果您想在服务器侧使用 SDK, 请使用 [@ featbit/ node-server-sdk (英语)](https://github.com/featbit/featbit-node-server-sdk)。 。 。 . ## 开始 ### 安装 ``` npm install @featbit/react-client-sdk ``` ### 先决条件 在使用SDK之前,需要获得环境秘密和SDK URL. 遵循以下文档获取这些值 - [如何让环境秘密](https://docs.featbit.co/sdk/faq#how-to-get-the-environment-secret) - [如何获得 SDK URL](https://docs.featbit.co/sdk/faq#how-to-get-the-sdk-urls) ### 快速启动 以下代码显示: 1. 初始化 SDK 2. 用用户 Flags 钩子评估旗帜 ```javascript import { createRoot } from 'react-dom/client'; import { asyncWithFbProvider, useFlags, FbProvider } from '@featbit/react-client-sdk'; function Game() { return (
This is a game
); } function APP() { const flags = useFlags(); const gameEnabled = flags['game-enabled']; return (
{ gameEnabled ? :
The game is not enabled
}
); } (async () => { const configWithAnonymousUser = { options: { user: { name: 'the user name', keyId: 'fb-demo-user-key', customizedProperties: [] }, sdkKey: 'YOUR ENVIRONMENT SECRET', streamingUri: 'THE STREAMING URL', eventsUri: 'THE EVENTS URL' } }; const root = createRoot(document.getElementById('root')); const Provider = await asyncWithFbProvider(configWithAnonymousUser); root.render( , ); // Use the following code in React < 18.0.0 // ReactDOM.render( // // // , // document.getElementById('root') // ); })(); ``` ## 实例 - [反应APP](https://npmcn.com/package/%40featbit/react-client-sdk/examples/react-app) - [下一个.js APP](https://npmcn.com/package/%40featbit/react-client-sdk/examples/nextjs-app) ## SDK 软件 ### 初始化 SDK 安装依赖后,初始化反应SDK. 你可以通过两种方式之一做到这一点: - 使用 `asyncWithFbProvider` 函数 - 使用 `withFbProvider` 函数 两者都依赖于 React 的上下文 API , 它允许您从组件等级的任意级别访问您的旗帜 . #### 使用 asyncWithFb 提供初始化 这个 `asyncWithFbProvider` 函数初始化 React SDK 并返回作为 React 组件的提供者。 这是一种主动函数。 它接受一个 `ProviderConfig` 对象. `asyncWithFbProvider` 不能推迟。 你必须初始化 `asyncWithFbProvider` 在渲染前的应用程序入口处,以确保旗子和客户端在应用程序开始时就绪. ```javascript import { createRoot } from 'react-dom/client'; import { asyncWithFbProvider } from '@featbit/react-client-sdk'; (async () => { const config = { options: { sdkKey: 'YOUR ENVIRONMENT SECRET', streamingUri: 'THE STREAMING URL', eventsUri: 'THE EVENTS URL', user: { name: 'USER NAME', keyId: 'USER ID', customizedProperties: [ { "name": "age", "value": '18' } ] } } } const root = createRoot(document.getElementById('root')); const FbProvider = await asyncWithFbProvider(config); root.render( , ); })(); ``` 在初始化完成后, 您的旗帜和客户端可以在您的 React app 生命周期开始时使用 。 这将确保您的应用程序不会因为启动时的旗帜更改而闪烁 . > 渲染可能会被延迟 > 由于 AsyncWithFb Provider 函数是同步的,您的 React app 的渲染被延后到初始化完成. 这最多需要100毫秒,但往往更早完成. 或者,如果您喜欢先制作您的应用程序,然后在渲染完成后处理旗帜更新,您也可以使用带有FbProvider功能. > 此函数需要回放 16. 8.0 或稍后 > ASyncWithFbProvider功能使用Hooks API,它需要回放16.8.0版本或更后. #### 以 Fb 创建初始化 这个 `withFbProvider` 函数初始化 React SDK ,并将根组件包入 **2\. 背景情况。 提供者**它接受 `ProviderConfig` 用于配置 React SDK 的对象. ```javascript import { withFbProvider } from '@featbit/react-client-sdk'; const config = { options: { sdkKey: 'YOUR ENVIRONMENT SECRET', streamingUri: 'THE STREAMING URL', eventsUri: 'THE EVENTS URL', user: { name: 'USER NAME', keyId: 'USER ID', customizedProperties: [ { "name": "age", "value": '18' } ] } } }; export default withFbProvider(config)(YourApp); ``` #### 订阅标记更改 React SDK 自动订阅国旗更改事件. 这与JavaScript SDK不同,客户需要选择参与事件监听. ### 配置反应 SDK 这个 `ProviderConfig` 对象为两者提供配置 `withFbProvider` 财务报告和审定财务报表 `asyncWithFbProvider` 函数. 唯一的强制性财产是 **选项**,这是初始化 `@featbit/js-client-sdk`。了解更多关于 **选项**请参考 [@ featbit/js-客户端-sdk](https://github.com/featbit/featbit-js-client-sdk)。所有其他属性都与 SDK 相关. 现有属性的完整列表 : - **选项**: 初始化配置 `@featbit/js-client-sdk`。 。 。 . **强制** 你可以用这个 **[选项](https://github.com/featbit/featbit-js-client-sdk?tab=readme-ov-file#bootstrap)** 选项以默认值填充 SDK. - **反应选项**: 您可以使用此选项, 在使用 React SDK 时启用旗下键的自动骆驼外壳 。 默认值为虚假 **非强制性** - **推迟**: 此属性允许 SDK 初始化被推迟, 直到您定义 fbClient 属性 。 默认值为虚假 **非强制性** asyncWithFb 提供器不支持延迟初始化 。 在渲染前, 您必须在应用程序入口处初始化 asyncWithFb 提供 , 以确保您的应用程序开始时客户端准备好 . 通过推迟SDK初始化,您会推迟作为SDK初始化的一部分而进行的所有步骤,包括从本地存储中读取旗帜值并发送SDK的已准备好事件. 这个规则的一个例外是,只要将被拖住的被拖住的被拖住的被拖住的被拖住的被拖住的被拖住的被拖住的被拖住的被拖住的被拖住的被拖住的被拖住的被拖住的被拖住的被拖走的被拖住的被拖住的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走. 如果您表示SDK应该从本地存储中拖出拖曳旗,则在SDK初始化前不会发生. 以下是包含上述每个属性的提供方对象: ```javascript { options: { sdkKey: 'YOUR ENVIRONMENT SECRET', streamingUri: 'THE STREAMING URL', eventsUri: 'THE EVENTS URL', user: { name: 'USER NAME', keyId: 'USER ID', customizedProperties: [ { "name": "age", "value": '18' } ] } ... }, reactOptions: { useCamelCaseFlagKeys: false }, deferInitialization: false } ``` ### 正在使用旗子 #### 在类组中悬挂旗帜 有两种方法可以消耗旗帜. ##### 使用上下文Type属性 ```javascript import { context } from '@featbit/react-client-sdk'; class MyComponent extends React.Component { static contextType = context; constructor(props) { super(props); } render() { const { flags } = this.context; return (
{ flags['dev-test-flag'] ? 'Flag on' : 'Flag off' }
) } } export default MyComponent; ``` ##### 使用 Fb 客户端 与 FbConcumer 的还原值是一个将您组件取回并返回以旗帜和 fbClient 作为道具注入的 React 组件的折叠函数 . ```javascript import { withFbConsumer } from '@featbit/react-client-sdk'; class MyComponent extends React.Component { render() { const { flags } = this.props; return (
{flags.flag1}
); } } export default withFbConsumer()(Board) ``` #### 在函数组件中使用标记 有两种方法可以消耗旗帜. ##### 使用 Fb 客户端 与 FbConcumer 的还原值是一个将您组件取回并返回以旗帜和 fbClient 作为道具注入的 React 组件的折叠函数 . ```javascript import { withFbConsumer } from '@featbit/react-client-sdk'; const Home = ({ flags, fbClient /*, ...otherProps */ }) => { // You can call any of the methods from the JavaScript SDK // fbClient.identify({...}) return flags['dev-test-flag'] ?
Flag on
:
Flag off
; }; export default withFbConsumer()(Home); ``` ##### 使用钩子 React SDK 提供了两个自定义的钩子,您可以用来替代 `withFbConsumer`数字 : - `useFlags` - `useFbClient` > 这些功能需要回放 16.8.0 或稍后 > 使用Flags并使用FbClient使用Hooks API,需要16.8.0或更晚的回放版本. 使用 Flags 是自定义的钩子, 它返回所有特征旗 。 它使用Context原始来访问由AsyncWithFbProvider或与FbProvider所设置的FeatBit上下文. 您仍然必须在您的应用程序根部使用 asyncWithFb Provider 或 与 Fb 提供更高排序组件来初始化 React SDK 并用 fbClient 和您的旗帜来填充上下文 . 使用FbClient 是返回 FeatBit 基本 JavaScript SDK 客户端对象的第二个自定义钩头 。 和使用Flags自定义钩一样,使用FbClient也使用使用Context原始来访问由AsyncWithFbProvider或与FbProvider所设置的上下文. 您仍必须使用 AsyncWithFb Provider 或用 Fb 提供更高顺序的组件来初始化 React SDK 才能使用此自定义钩子 . 以下是如何使用这两个钩子的例子: ```javascript import { useFlags, useFbClient } from '@featbit/react-client-sdk'; const MyComponent = props => { const fbClient = useFbClient(); const { flag1, flag2 } = useFlags(); // or use const flags = useFlags(); // then use flags.flag1 or flags['flag1'] to reference the flag1 feature flag return (
1: {flag1}
2: {flag2}
); }; export default MyComponent; ``` ### 初始化后切换用户 如果用户在初始化期间不可用,您可以拨打 **身份( )** 方法打开 **fb 密度** 设置初始化后的用户. #### 在类组件中切换用户 ```javascript import { withFbConsumer, useFbClient } from '@featbit/react-client-sdk'; class LoginComponent extends React.Component { handleLogin = async () => { const { fbClient } = this.props; const user = {}; // use your user object await fbClient.identify(user); } render() { return (
); } } export default withFbConsumer()(LoginComponent) ``` #### 在函数组件中切换用户 ```javascript import { useFbClient } from '@featbit/react-client-sdk'; const LoginComponent = () => { const fbClient = useFbClient(); handleLogin = async () => { const user = {}; // use your user object await fbClient.identify(user); } return (
); } ``` ### SDK 以倒挂旗标值填充 如上所述,你可以使用 **选项** 选项以默认值填充 SDK 。 如果您想要在 SDK 初始化前为您的旗帜提供默认值, 此选项是有用的 . 如果无法从 SDK 中获取一面旗帜, SDK 将使用您在靴子夹对象中提供的默认值 . ```javascript options: { bootstrap: [ { "id": "my-flag", "variation": "on" }, { "id": "second-flag", "variation": "AlphaGo" } ] } ``` ## 旗下密钥 费特 Bit主要用密钥识别特征标记, 密钥必须只包含字母字符, 点 (.), 下划线 ( ), 和分线 (-) 。 这些密钥被用于我们所有API以及SDK识别旗帜. 然而, JavaScript 和 React 无法使用点标记访问密钥, 因此 React SDK 可以将所有旗下密钥更改为骆驼大小写( 您需要用 **反应可选. useCamelCaseFlagKeys** 参数). 有密钥的旗帜 `dev-flag-test` 以 `flags.devFlagTest`。此标记 **旗帜 \['dev-flag-test'\]** 如果禁用CamelCaseFlagKeys,则应当使用,默认禁用. 请注意,通过激活使用CamelCaseFlagKeys,你会看到以下问题: - 如果有多个标记键决定同一个骆驼箱键,则可能诱发密钥相撞。 譬如说, `dev-flag-test` 财务报告和审定财务报表 `dev.flag.test` 是独一无二的密钥, 但是反应 SDK 把它们修改为相同的驼峰大小写密钥 . - 如果一行中有3个或更多个大写字母,SDK会自动将第一个和最后一个大写字母之间的所有字母转换为小写. 例如, SDK 转换带有密钥的旗帜 `devQAFlagTest` 改为 `devQaFlagTest`。如果使用devQAFlag Test with the use Flags () hook,则SDK找不到旗帜. - 因为骆驼案的功能是在React SDK中而不是在基础的JavaScript SDK中被执行的,所以由JavaScript SDK提供的基础客户对象和功能会以原始格式反映旗帜密钥. 只有像您注射道具这样的特定反应环境使用骆驼箱. > 如果您启用了 CamelCaseFlagKeys 选项, 尝试使用其原始密钥访问一面旗帜将会在控制台触发警告信息 : **你试图用它的原始键盘访问一面旗帜:xxx,尽管使用CamelCaseFlagKeys是设定为真实的.** ## 导入类型 除了自己的捆绑类型外,React SDK还使用来自 `@featbit/js-client-sdk`,这些类型由React SDK再出口. 您可以直接从 React SDK 导入这些类型 ## 常见问题 ### @featbit/react-client-sdk 是什么？ FeatBit 客户端 SDK 反应 ### 如何安装 @featbit/react-client-sdk？ 在项目目录运行 npm install @featbit/react-client-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^16\.6\.3 \|\| ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0）、react-dom（^16\.8\.4 \|\| ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @featbit/react-client-sdk 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @featbit/react-client-sdk 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @featbit/react-client-sdk 可以商用吗？ @featbit/react-client-sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @featbit/react-client-sdk 的下载量有多少？ 根据 npm 官方下载统计，@featbit/react-client-sdk 在 2026/10/15 – 2026/11/13 这 30 天内被下载 47,034 次，日均约 1,568 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @featbit/react-client-sdk 还在维护吗？ 最新版本 4\.4\.2 发布于 2026/11/04（10 天前）；至今共发布 38 个版本，其中过去 12 个月发布了 20 个；首次发布于 2024/05/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。