# @harnessio/ff-react-client-sdk 中文文档

规范地址：https://npmcn.com/package/%40harnessio/ff-react-client-sdk/

版本：2\.4\.0
npm 元数据更新时间：2026-11-16T17:37:06.738Z
中文译文更新时间：2026-11-17T10:14:21.286Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40harnessio/ff-react-client-sdk
原文对照：https://npmcn.com/package/%40harnessio/ff-react-client-sdk/?lang=original
项目主页：https://github.com/harness/ff-react-client-sdk#readme
源码仓库：https://github.com/harness/ff-react-client-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：62.6 kB，47 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react \>=16\.7\.0
- 首次发布：2022-09-02T16:09:18.541Z
- 最新版本发布：2026-01-09T13:33:34.577Z
- 近 30 天下载量：134051（2026-10-18 至 2026-11-16，npm 官方下载统计）
- 已发布版本数：48（近 12 个月 2 个）

## 中文简介

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

## 安装

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

也可以使用：`pnpm add @harnessio/ff-react-client-sdk`、`yarn add @harnessio/ff-react-client-sdk`、`bun add @harnessio/ff-react-client-sdk`

## README

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

[![React version](https://img.shields.io/badge/React.js-%3E=%2016.7-blue.svg)](https://reactjs.org/) [![TypeScript version](https://img.shields.io/badge/TypeScript-4.7-blue.svg)](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-7.html) [![Node.js version](https://img.shields.io/badge/Node.js-%3E=%2012-blue.svg)](https://nodejs.org/dist/latest/docs/api/) [![APLv2](https://img.shields.io/badge/license-APLv2-blue.svg)](https://github.com/drone/ff-nodejs-server-sdk/blob/main/LICENSE)

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

此样本不包括配置选项, 用于深度步骤和配置 SDK , 参见 页:1 [反应客户端 SDK 引用](https://developer.harness.io/docs/feature-flags/ff-sdks/client-sdks/react-client)。 。 。 .

## 所需资源

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

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

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

-   [在哈内斯平台上创建了特性旗](https://developer.harness.io/docs/feature-flags/ff-creating-flag/create-a-feature-flag/) 调用 `harnessappdemodarkmode`
-   [创建客户端 SDK 密钥](https://developer.harness.io/docs/feature-flags/ff-creating-flag/create-a-project#create-an-sdk-key) 并把它复制出来

## 安装 SDK

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

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

或者用纱线安装,使用:

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

## 代码样本

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

-   渲染装入屏幕
-   连接到 FF 服务
-   获取所有旗帜
-   使用 `useFeatureFlag` 钩子
-   使用 `useFeatureFlags` 钩子

```typescript
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 密钥正在被使用或认证失败,而预期的旗帜无法用于该项目.

```typescript
<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得到 即刻启动并开始为旗帜服务,同时进行认证和获取最新评价 从幕后服务器.

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

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

```typescript
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` 对象。 在某些情况下,它 可用于登录某项服务,或者在没有记录错误的情况下静默地失败.

```typescript
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` [韩克](https://reactjs.org/docs/higher-order-components.html). 它至少要求 `apiKey` 您已经设置在 您的调取功能标志账户 `target`。你可以想到一个 `target` 作为用户.

这个 `FFContextProvider` 组件还接受 `options` 对象, a `fallback` 组件,一个阵列 联 合 国 `initialEvaluations`,一个 `onError` 处理器,并可以放置在 [同步模式](https://npmcn.com/package/%40harnessio/ff-react-client-sdk/#readme-Async-mode) 使用 `asyncMode` 道具 (英语). 这个 `fallback` 组件将在 SDK 装入和取取您的旗帜时显示 。 这个 `initialEvaluations` 道具允许您在SDK认证和取取旗时,通过一系列评价立即使用. 这个 `onError` prop 允许您通过一个事件处理器, 当网络出错时会调用它 .

```typescript
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` 如果旗帜 无法找到 .

> 说明: [同步模式](https://npmcn.com/package/%40harnessio/ff-react-client-sdk/#readme-Async-mode)中,默认值将返回到旗下检索. 考虑使用 [使用 FeatureFlags 连接钩](https://npmcn.com/package/%40harnessio/ff-react-client-sdk/#readme-usefeatureflagsloading) 以确定 SDK 何时完成 装入.

```typescript
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`。如果没有通过任何参数,所有旗将返回.

> 说明: [同步模式](https://npmcn.com/package/%40harnessio/ff-react-client-sdk/#readme-Async-mode)中,默认值将返回到旗下检索. 考虑使用 [使用 FeatureFlags 连接钩](https://npmcn.com/package/%40harnessio/ff-react-client-sdk/#readme-usefeatureflagsloading) 以确定 SDK 何时完成 装入.

```typescript
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>
    </>
  )
}
```

#### 获取旗子集

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

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

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

### `useFeatureFlagsLoading`

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

```typescript
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 提供.

```typescript
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) 包入您的组件, 并仅在命名的旗帜时有条件制作 启用或匹配特定值.

```typescript
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`价值是真实的.

#### 有条件且有特定值

```typescript
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`'值与通过值相匹配' 条件.

#### 在同声模式下装入后退

若为 [同步模式](https://npmcn.com/package/%40harnessio/ff-react-client-sdk/#readme-Async-mode) ,默认情况下,组件将在显示前等待被取回旗子。 这个 行为可以通过传递一个元素来推翻 `loadingFallback`; 装入 `loadingFallback` 将会是 显示,直到找到“旗帜”,此时组件将显示或隐藏为正常.

```typescript
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 是否正在积极获取 旗帜.

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

// ...

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

const MyComponentWithFlags = withFeatureFlags(MyComponent)
```

#### 以同步模式装入

若为 [同步模式](https://npmcn.com/package/%40harnessio/ff-react-client-sdk/#readme-Async-mode) 用于: `loading` 道克会表示SDK是否已完成地物旗的初始负载. 装入完成时, 要么成功 (`Event.READY` 或出现无法弥补的错误(`Event.ERROR_AUTH` ),该 `loading` 道具会 `false` 编辑 `flags` 道具将包含所有已知的旗帜.

```typescript
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 提供.

```typescript
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` 目录, 不来自 主软件包.

```typescript
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 引用](https://developer.harness.io/docs/feature-flags/ff-sdks/client-sdks/react-client) 关于地物旗的更多信息,请参见: 我们 [特性标记文档](https://developer.harness.io/docs/feature-flags/ff-onboarding/getting-started-with-feature-flags/)。 。 。 .

## 常见问题

### @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 和提交记录判断。

