@harnessio/ff-react-client-sdk

中文文档
2.4.0发布于 2026/01/09Apache-2.0TypeScriptESM + CJS近 30 天下载 13.4万

[!][反应版-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作作作弊-作弊

中文使用文档
文档目录18 节
  1. 所需资源
  2. 安装 SDK
  3. 代码样本
  4. 同步模式
  5. 在未找到的旗帜上
  6. 缓存评价
  7. 覆盖内部日志
  8. API 密码
  9. FFContextProvider
  10. useFeatureFlag
  11. useFeatureFlags
  12. useFeatureFlagsLoading
  13. useFeatureFlagsClient
  14. ifFeatureFlag
  15. withFeatureFlags
  16. withFeatureFlagsClient
  17. 用 Jest 进行测试
  18. 其他阅读

React.js 客户端 SDK 用于调色功能旗

React version TypeScript version Node.js version APLv2

使用此 README 开始使用我们的特性旗 (FF) 客户端 SDK 进行反应 。 本指南概述 从SDK开始 并提供一个完整的代码样本 让你尝试.

此样本不包括配置选项, 用于深度步骤和配置 SDK , 参见 页:1 反应客户端 SDK 引用。 。 。 .

所需资源

要使用 SDK , 请确定您是否:

  • 安装了 Node.js v12 或更新版本
  • 已安装 React.js v16.7 或更新版本

与我们的测试代码样本一样

安装 SDK

第一步是安装FF SDK作为应用程序中的依赖. 要使用 npm 安装,请使用 :

npm install @harnessio/ff-react-client-sdk

或者用纱线安装,使用:

yarn add @harnessio/ff-react-client-sdk

代码样本

下面是一个完整的代码示例,可以用来测试 harnessappdemodarkmode 您创建的旗帜 驾驭平台. 当你运行代码时,它会:

  • 渲染装入屏幕
  • 连接到 FF 服务
  • 获取所有旗帜
  • 使用 useFeatureFlag 钩子
  • 使用 useFeatureFlags 钩子
import React from 'react'
import ReactDOM from 'react-dom'

import {
  FFContextProvider,
  useFeatureFlag,
  useFeatureFlags
} from '@harnessio/ff-react-client-sdk'

ReactDOM.render(<App />, document.querySelector('#react-root'))

function App() {
  return (
    <FFContextProvider
      apiKey="YOUR_API_KEY"
      target={{
        identifier: 'reactclientsdk',
        name: 'ReactClientSDK'
      }}
    >
      <SingleFeatureFlag />
      <MultipleFeatureFlags />
    </FFContextProvider>
  )
}

function SingleFeatureFlag() {
  const flagValue = useFeatureFlag('harnessappdemodarkmode')

  return (
    <p>The value of "harnessappdemodarkmode" is {JSON.stringify(flagValue)}</p>
  )
}

function MultipleFeatureFlags() {
  const flags = useFeatureFlags()

  return (
    <>
      <p>Here are all our flags:</p>
      <pre>{JSON.stringify(flags, null, 2)}</pre>
    </>
  )
}

同步模式

默认情况下, React 客户端 SDK 将会屏蔽儿童的渲染,直到Feature Flags 的初始负载完成, 要么成功( SDK) Event.READY 或出现无法弥补的错误(Event.ERROR_AUTH 已释放). 这确保儿童在制作时能够立即接触所有旗帜。 然而,在某些情况下 可能有利于立即使应用程序和处理每个组件的装载显示. React Client SDK 的同步模式允许通过可选方式进行此操作 asyncMode 连接时的道具 FFContextProvider。 。 。 .

在未找到的旗帜上

这个 onFlagNotFound 选项允许您处理返回默认变量的情况. 它包括了旗帜,变异,以及SDK是否还在初始化(loading),当默认被送达.

出现这种情况时:

  1. 使用 asyncMode 没有模式 cache 或者说 initialEvaluations 以及SDK还在初始化的地方.
  2. 国旗标识符不正确(例如由于打字).
  3. 这个 Event.ERROR_AUTH 事件被释放,这意味着发生了无法恢复的错误,例如错误的 API 密钥正在被使用或认证失败,而预期的旗帜无法用于该项目.
<FFContextProvider
  apiKey="YOUR_API_KEY"
  target={{
    identifier: 'reactclientsdk',
    name: 'ReactClientSDK'
  }}
  onFlagNotFound={(flagNotFoundPayload, loading) => {
    if (loading) {
      console.debug(
        `Flag "${flagNotFound.flag}" not found because the SDK is still initializing. Returned default: ${flagNotFound.defaultVariation}`
      )
    } else {
      console.warn(
        `Flag "${flagNotFound.flag}" not found. Returned default: ${flagNotFound.defaultVariation}`
      )
    }
  }}
>
  <MyApp />
</FFContextProvider>

通过使用 onFlagNotFound prop, 您的应用程序可以在缺少一面旗帜和默认情况下被通知 变量已返回.

缓存评价

在实际操作中,旗帜很少改变,因此可以缓存从服务器收到的最后评价,以便 您需要尽快启动申请。 设置 cache 选项为 true 或作为一个对象(参见界面) (见下文)将允许SDK将其评价储存到 localStorage 启动时检索。 这让SDK得到 即刻启动并开始为旗帜服务,同时进行认证和获取最新评价 从幕后服务器.

<FFContextProvider
  apiKey="YOUR_API_KEY"
  target={{
    identifier: 'reactclientsdk',
    name: 'ReactClientSDK'
  }}
  options={{
    cache: true
  }}
>
  <MyApp />
</FFContextProvider>

这个 cache 选项也可以作为对象通过,其选项如下.

interface CacheOptions {
  // maximum age of stored cache, in ms, before it is considered stale
  ttl?: number
  // storage mechanism to use, conforming to the Web Storage API standard, can be either synchronous or asynchronous
  // defaults to localStorage
  storage?: AsyncStorage | SyncStorage
  // use target attributes when deriving the cache key
  // when set to `false` or omitted, the key will be formed using only the target identifier and SDK key
  // when set to `true`, all target attributes with be used in addition to the target identifier and SDK key
  // can be set to an array of target attributes to use a subset in addition to the target identifier and SDK key
  // defaults to false
  deriveKeyFromTargetAttributes?: boolean | string[]
}

interface SyncStorage {
  getItem: (key: string) => string | null
  setItem: (key: string, value: string) => void
  removeItem: (key: string) => void
}

interface AsyncStorage {
  getItem: (key: string) => Promise<string | null>
  setItem: (key: string, value: string) => Promise<void>
  removeItem: (key: string) => Promise<void>
}

覆盖内部日志

默认情况下, React 客户端 SDK 将使用 console 对象。 在某些情况下,它 可用于登录某项服务,或者在没有记录错误的情况下静默地失败.

const myLogger = {
  debug: (...data) => {
    // do something with the logged debug message
  },
  info: (...data) => {
    // do something with the logged info message
  },
  error: (...data) => {
    // do something with the logged error message
  },
  warn: (...data) => {
    // do something with the logged warning message
  }
}

return (
  <FFContextProvider
    apiKey="YOUR_API_KEY"
    target={{
      identifier: 'reactclientsdk',
      name: 'ReactClientSDK'
    }}
    options={{
      logger: myLogger
    }}
  >
    <MyApp />
  </FFContextProvider>
)

API 密码

FFContextProvider

这个 FFContextProvider 组件用于设置 React 上下文,允许您的应用程序访问地物标记 使用 useFeatureFlag 财务报告和审定财务报表 useFeatureFlags 钩子和 withFeatureFlags 韩克. 它至少要求 apiKey 您已经设置在 您的调取功能标志账户 target。你可以想到一个 target 作为用户.

这个 FFContextProvider 组件还接受 options 对象, a fallback 组件,一个阵列 联 合 国 initialEvaluations,一个 onError 处理器,并可以放置在 同步模式 使用 asyncMode 道具 (英语). 这个 fallback 组件将在 SDK 装入和取取您的旗帜时显示 。 这个 initialEvaluations 道具允许您在SDK认证和取取旗时,通过一系列评价立即使用. 这个 onError prop 允许您通过一个事件处理器, 当网络出错时会调用它 .

import { FFContextProvider } from '@harnessio/ff-react-client-sdk'

// ...

function MyComponent() {
  return (
    <FFContextProvider
      asyncMode={false} // OPTIONAL: whether or not to use async mode
      apiKey="YOUR_API_KEY" // your SDK API key
      target={{
        identifier: 'targetId', // unique ID of the Target
        name: 'Target Name',  // name of the Target
        attributes: { // OPTIONAL: key/value pairs of attributes of the Target
          customAttribute: 'this is a custom attribute',
          anotherCustomAttribute: 'this is something else'
        }
      }}
      fallback={<p>Loading ...</p>} // OPTIONAL: component to display when the SDK is connecting
      options={{ // OPTIONAL: advanced configuration options
        cache: false,
        baseUrl: 'https://url-to-access-flags.com',
        eventUrl: 'https://url-for-events.com',
        streamEnabled: true,
        debug: true,
        eventsSyncInterval: 60000
      }}
      initialEvaluations={evals} // OPTIONAL: array of evaluations to use while fetching
      onError={handler} // OPTIONAL: event handler to be called on network error
    >
      <CompontToDisplayAfterLoad /> <!-- component to display when Flags are available -->
    </FFContextProvider>
  )
}

useFeatureFlag

这个 useFeatureFlag 钩子返回一个单一命名的旗帜值. 可选第二个参数允许您设定什么值 如果旗帜没有值,将返回。 默认 useFeatureFlag 将返回 undefined 如果旗帜 无法找到 .

说明: 同步模式中,默认值将返回到旗下检索. 考虑使用 使用 FeatureFlags 连接钩 以确定 SDK 何时完成 装入.

import { useFeatureFlag } from '@harnessio/ff-react-client-sdk'

// ...

function MyComponent() {
  const myFlagValue = useFeatureFlag('flagIdentifier', 'default value')

  return <p>My flag value is: {myFlagValue}</p>
}

useFeatureFlags

这个 useFeatureFlags 钩子返回旗标识符/旗值对的对象. 您可以通过一阵旗帜 标识符或旗下标识符/默认值对的对象。 如果使用了数组而找不到旗帜,则 返回旗帜的值 undefined。如果没有通过任何参数,所有旗将返回.

说明: 同步模式中,默认值将返回到旗下检索. 考虑使用 使用 FeatureFlags 连接钩 以确定 SDK 何时完成 装入.

import { useFeatureFlag } from '@harnessio/ff-react-client-sdk'

// ...

function MyComponent() {
  const myFlagValues = useFeatureFlags()

  return (
    <>
      <p>My flag values are:</p>
      <pre>{JSON.stringify(myFlagValues, null, 2)}</pre>
    </>
  )
}

获取旗子集

const myFlagValues = useFeatureFlags(['flag1', 'flag2'])

获得带有自定义默认值的旗子集

const myFlagValues = useFeatureFlags({
  flag1: 'defaultForFlag1',
  flag2: 'defaultForFlag2'
})

useFeatureFlagsLoading

这个 useFeatureFlagsLoading 钩子返回布尔值,表示SDK是否正在装入旗舰 从服务器.

import {
  useFeatureFlagsLoading,
  useFeatureFlags
} from '@harnessio/ff-react-client-sdk'

// ...

function MyComponent() {
  const isLoading = useFeatureFlagsLoading()
  const flags = useFeatureFlags()

  if (isLoading) {
    return <p>Loading ...</p>
  }

  return (
    <>
      <p>My flag values are:</p>
      <pre>{JSON.stringify(flags, null, 2)}</pre>
    </>
  )
}

useFeatureFlagsClient

React客户端SDK内部使用Javascript客户端SDK与Harness通信. 有时候可能有用 以访问 Javascript 客户端 SDK 实例, 而不是使用已有的钩或更高顺序 (单位:千美元) 这个 useFeatureFlagsClient 钩钩返回当前 Javascript 客户端 SDK 实例 客户端 SDK正在使用。 此实例将被配置、初始化, 并已经连接到各种事件 Javascript客户端 SDK 提供.

import {
  useFeatureFlagsClient,
  useFeatureFlagsLoading
} from '@harnessio/ff-react-client-sdk'

// ...

function MyComponent() {
  const client = useFeatureFlagsClient()
  const loading = useFeatureFlagsLoading()

  if (loading || !client) {
    return <p>Loading...</p>
  }

  return (
    <p>
      My flag value is: {client.variation('flagIdentifier', 'default value')}
    </p>
  )
}

ifFeatureFlag

这个 ifFeatureFlag 高序组件( HOC) 包入您的组件, 并仅在命名的旗帜时有条件制作 启用或匹配特定值.

import { ifFeatureFlag } from '@harnessio/ff-react-client-sdk'

// ...

function MyComponent() {
  return <p>This should render if the flag is on</p>
}

const MyConditionalComponent = ifFeatureFlag('flag1')(MyComponent)

然后可以使用 MyConditionalComponent 作为正常组件,并且只有在 flag1价值是真实的.

有条件且有特定值

import { ifFeatureFlag } from '@harnessio/ff-react-client-sdk'

// ...

function MyComponent() {
  return <p>This should render if the flag evaluates to 'ABC123'</p>
}

const MyConditionalComponent = ifFeatureFlag('flag1', { matchValue: 'ABC123' })(
  MyComponent
)

然后可以使用 MyConditionalComponent 作为正常组件,仅在 flag1'值与通过值相匹配' 条件.

在同声模式下装入后退

若为 同步模式 ,默认情况下,组件将在显示前等待被取回旗子。 这个 行为可以通过传递一个元素来推翻 loadingFallback; 装入 loadingFallback 将会是 显示,直到找到“旗帜”,此时组件将显示或隐藏为正常.

import { ifFeatureFlag } from '@harnessio/ff-react-client-sdk'

// ...

function MyComponent() {
  return <p>This should render if the flag is on</p>
}

const MyConditionalComponent = ifFeatureFlag('flag1', {
  loadingFallback: <p>Loading...</p>
})(MyComponent)

withFeatureFlags

这个 withFeatureFlags 高排序组件( HOC) 包入您的组件并添加 flags 财务报告和审定财务报表 loading 作为额外 道具来. flags 包含所有已知旗帜的评价 loading 显示 SDK 是否正在积极获取 旗帜.

import { withFeatureFlags } from '@harnessio/ff-react-client-sdk'

// ...

function MyComponent({ flags }) {
  return <p>Flag1's value is {flags.flag1}</p>
}

const MyComponentWithFlags = withFeatureFlags(MyComponent)

以同步模式装入

若为 同步模式 用于: loading 道克会表示SDK是否已完成地物旗的初始负载. 装入完成时, 要么成功 (Event.READY 或出现无法弥补的错误(Event.ERROR_AUTH ),该 loading 道具会 false 编辑 flags 道具将包含所有已知的旗帜.

import { withFeatureFlags } from '@harnessio/ff-react-client-sdk'

// ...

function MyComponent({ flags, loading }) {
  if (loading) {
    return <p>Loading...</p>
  }

  return <p>Flag1's value is {flags.flag1}</p>
}

const MyComponentWithFlags = withFeatureFlags(MyComponent)

withFeatureFlagsClient

React客户端SDK内部使用Javascript客户端SDK与Harness通信. 有时候可能有用 以访问 Javascript 客户端 SDK 实例, 而不是使用已有的钩或更高顺序 (单位:千美元) 这个 withFeatureFlagsClient HOC 包装您的组件并添加 featureFlagsClient 作为额外 道具 (英语). featureFlagsClient 是当前 Javascript 客户端 SDK 实例,反应客户端 SDK 正在使用 。 这个 实例将被配置、初始化并已经连接到各种事件 Javascript客户端 SDK 提供.

import { withFeatureFlagsClient } from '@harnessio/ff-react-client-sdk'

// ...

function MyComponent({ featureFlagsClient }) {
  if (featureFlagsClient) {
    return (
      <p>
        Flag1's value is {featureFlagsClient.variation('flag1', 'no value')}
      </p>
    )
  }

  return <p>The Feature Flags client is not currently available</p>
}

const MyComponentWithClient = withFeatureFlagsClient(MyComponent)

用 Jest 进行测试

在与Jest一起运行测试时,你可能想要嘲笑SDK以避免提出网络请求. 通过使用 包含 TestWrapper 组件。 此组件接受旗帜及其值的列表, 并将嘲笑 SDK 以返回这些价值。 在下面的例子中,我们使用测试库来制作组件 <MyComponent /> 那个 内部使用 useFeatureFlag 钩.

注: TestWrapper 组件,您必须从 dist/cjs/test-utils 目录, 不来自 主软件包.

import { render, screen } from '@testing-library/react'
import { TestWrapper } from '@harnessio/ff-react-client-sdk/dist/cjs/test-utils'

// ...

test('it should render the flag value', () => {
  render(
    <TestWrapper flags={{ flag1: 'value1', flag2: 'value2' }}>
      <MyComponent />
    </TestWrapper>
  )

  expect(screen.getByText('value1')).toBeInTheDocument()
})

其他阅读

更多实例和配置选项见 页:1 React.js 客户端 SDK 引用 关于地物旗的更多信息,请参见: 我们 特性标记文档。 。 。 .

版本与发布记录

@harnessio/ff-react-client-sdk 共发布 48 个版本,首次发布于 2022/09/03;过去 12 个月发布了 2 个版本。

版本发布日期距今
2.4.0latest2026/01/0910 个月前
2.3.12025/11/2611 个月前
2.3.02025/08/181.2 年前
2.2.02025/02/131.8 年前
2.1.02025/02/111.8 年前
2.0.02024/11/212 年前

其他发布通道:alpha → 1.9.0-alpha.0,beta → 2.0.0-rc.1。

关于 @harnessio/ff-react-client-sdk 的常见问题

@harnessio/ff-react-client-sdk 是什么?

[!][反应版-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作弊-作作作弊-作弊

如何安装 @harnessio/ff-react-client-sdk?

在项目目录运行 npm install @harnessio/ff-react-client-sdk,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(>=16.7.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@harnessio/ff-react-client-sdk 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@harnessio/ff-react-client-sdk 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@harnessio/ff-react-client-sdk 可以商用吗?

@harnessio/ff-react-client-sdk 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@harnessio/ff-react-client-sdk 的下载量有多少?

根据 npm 官方下载统计,@harnessio/ff-react-client-sdk 在 2026/10/18 – 2026/11/16 这 30 天内被下载 134,051 次,日均约 4,468 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@harnessio/ff-react-client-sdk 还在维护吗?

最新版本 2.4.0 发布于 2026/01/09(10 个月前);至今共发布 48 个版本,其中过去 12 个月发布了 2 个;首次发布于 2022/09/03。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。