# @flipt-io/flipt-client-react 中文文档
规范地址：https://npmcn.com/package/%40flipt-io/flipt-client-react/
版本：1\.3\.0
npm 元数据更新时间：2026-11-08T16:02:14.210Z
中文译文更新时间：2026-11-14T23:23:28.205Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40flipt-io/flipt-client-react
原文对照：https://npmcn.com/package/%40flipt-io/flipt-client-react/?lang=original
项目主页：https://github.com/flipt-io/flipt-client-sdks/tree/main#readme
源码仓库：https://github.com/flipt-io/flipt-client-sdks#main
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：176 kB，15 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=16\.8\.0，react-dom \>=16\.8\.0，@flipt-io/flipt-client-js ^0\.6\.0 \|\| ^0\.7\.0
- 首次发布：2024-09-21T20:01:28.584Z
- 最新版本发布：2026-11-08T16:02:14.037Z
- 近 30 天下载量：94618（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 5 个）
## 中文简介
翻转客户端评价反应SDK
## 安装
```sh
npm install @flipt-io/flipt-client-react
```
也可以使用：`pnpm add @flipt-io/flipt-client-react`、`yarn add @flipt-io/flipt-client-react`、`bun add @flipt-io/flipt-client-react`
## README
# 翻转反应 SDK
[](https://www.npmjs.com/package/@flipt-io/flipt-client-react)
Flipt React SDK 为集成提供了方便的方法 [翻转](https://flipt.io/) 使用自定义钩和上下文提供者在您的 React 应用程序中添加特性标记。 它建在翻转上方 [客户端评价](https://www.flipt.io/docs/integration/client) 用于浏览器的客户端.
## 安装
```bash
npm install @flipt-io/flipt-client-react
```
## 先决条件
- 反应16.8.0或以上
## 使用量
使用"翻转回放"SDK有三种方式.
1. 使用 `useFliptBoolean` 将布林评价钩在被包在一个函数元件中的 `FliptProvider`。 。 。 .
2. 使用 `useFliptVariant` 将变量评价钩子装入一个 `FliptProvider`。 。 。 .
3. 使用 `useFliptSelector` 将自定义评价连接到包含在 `FliptProvider`。 。 。 .
> \[TIP\] 寻找下一个JS支持吗 ? 看看我们 [下一个 JS 示例](https://github.com/flipt-io/flipt/tree/main/examples/nextjs) 在主翻转.
### 翻转提供
首先,将您的申请或其中一部分与 `FliptProvider`数字 :
```tsx
import { FliptProvider } from '@flipt-io/flipt-client-react';
function App() {
return (
{/* Your app components */}
);
}
```
#### 使用Flipt Boolean 钩
这个 `useFliptBoolean` 钩子简化了评价布尔特征旗的过程. 此钩必须用在由 `FliptProvider` 上下文. 如果当前无法评价特性旗(例如由于网络问题或数据缺失),则返回默认值.
```tsx
import { useFliptBoolean } from '@flipt-io/flipt-client-react';
function MyComponent() {
const result = useFliptBoolean('my-flag', false, 'user-123', {
// additional context
});
const handleCheckFlag = async () => {
console.log('Flag evaluation result:', result);
};
return (
);
}
```
#### 使用 FliptVariant 钩
这个 `useFliptVariant` 钩子简化了一个变种特征旗的评价过程. 此钩必须用在由 `FliptProvider` 上下文. 如果当前无法评价特性旗(例如由于网络问题或数据缺失),则返回默认值.
```tsx
import { useFliptVariant } from '@flipt-io/flipt-client-react';
function MyComponent() {
const result = useFliptVariant('my-flag', 'fallback', 'user-123', {
// additional context
});
const handleCheckFlag = async () => {
console.log('Flag evaluation result:', result);
};
return (
);
}
```
### 使用 Flipt 选择钩
这个 `useFliptSelector` 钩子允许直接访问 Flipt 客户端,这样它就可以被用包在一个功能组件中使用 `FliptProvider`。 。 。 .
这对更复杂的评价或者在您想要调用Flipt客户端时有用.
> \[尖叫声\] `flipt-client-react` 严重依赖 `useSyncExternalStore` 有钩子的 [说明](https://react.dev/reference/react/useSyncExternalStore#caveats)
```tsx
import { useFliptSelector } from '@flipt-io/flipt-client-react';
function MyComponent() {
const result = useFliptSelector((client, isLoading, error) => {
const result = client?.evaluateBoolean('my-flag', 'user-123', {
// additional context
});
console.log('Flag evaluation internals:', result, isLoading, error);
return result?.enabled;
});
// Use the client to evaluate flags
const handleCheckFlag = async () => {
console.log('Flag evaluation result:', result);
};
return (
);
}
```
### 初始化参数
这个 `FliptProvider` 组件接受两个可选参数:
- `options`: 实例 `ClientOptions` 类型,用于支持客户端的若干选项。 其结构是:
- `environment`: 评价旗帜时所用的环境(Flipt v2)。 如果不提供,客户端将默认为 `default` 环境.
- `namespace`: 获取旗下状态的命名空间 。 如果不提供,客户端将默认为 `default` 名称空间.
- `url`: 上游翻转实例的 URL。 如果不提供,客户端将默认为 `http://localhost:8080`。 。 。 .
- `authentication`: 与上游翻转实例通信时使用的认证策略。 如果不提供,客户端将默认为没有认证. 见 [认证](https://npmcn.com/package/%40flipt-io/flipt-client-react/#readme-authentication) 用于提供更多信息.
- `updateInterval`:从Flipt获取新状态的投票间隔(以秒计). 设定为 `120` 默认的秒。 A 类 `0` 值在初始获取后完全禁用投票.
- `reference`编号: [参考文献](https://docs.flipt.io/guides/user/using-references) 用于获取旗帜状态。 如果不提供参考文献,则不使用参考文献.
- `snapshot`由JS客户端返回的 Base64 编码快照 `getSnapshot()` 方法。 用这个 `errorStrategy: ErrorStrategy.Fallback` 以允许启动,而 Flipt 是无法到达的.
- `errorStrategy`: 获取错误的战略。 使用 `ErrorStrategy.Fallback` 与 `snapshot` 用于离线启动.
- `fetchMode`数字 : `FetchMode.Polling` (违约)或 `FetchMode.Streaming`与 `@flipt-io/flipt-client-js` 0.7.0或更后,当客户端应用已改变的旗下状态时,包括流上更新时,组件会重新回复.
- `fetcher`执行 [获取器](https://github.com/flipt-io/flipt-client-sdks/blob/4821cb227c6c8b10419b96674d44ad1d6668a647/flipt-client-browser/src/models.ts#L5) 界面,用于请求旗帜状态时。 如果没有提供,则使用浏览器的默认取取器 [`fetch` API 密码](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) 将被使用.
### 认证
这个 `FliptProvider` 构成部分支持下列认证战略:
- 无认证( 默认)
- [客户端托肯认证](https://docs.flipt.io/authentication/using-tokens)
- [JWT 认证](https://docs.flipt.io/authentication/using-jwts)
### 带快照的离线启动
`flipt-client-react` 用途 `@flipt-io/flipt-client-js` 在引擎盖下,它支持同样的手动快照流. 自己储存快照,然后通过 `FliptProvider` 选项.
```tsx
import { ErrorStrategy } from '@flipt-io/flipt-client-js';
import { FliptProvider, useFliptSelector } from '@flipt-io/flipt-client-react';
function PersistFliptSnapshot() {
useFliptSelector((client) => {
if (client) {
localStorage.setItem('fliptSnapshot', client.getSnapshot());
}
return null;
});
return null;
}
function App() {
const snapshot = localStorage.getItem('fliptSnapshot') ?? undefined;
return (
{/* Your app components */}
);
}
```
如果启动抓取失败, 提供者会使用缓存快照 。 当Flipt可以到达时,新鲜状态将替换缓存快照并 `getSnapshot()` 返回最新状态.
## 实例
以下是一个更完整的实例,说明如何在您的应用程序中使用回放SDK:
```tsx
import React from 'react';
import { FliptProvider, useFliptBoolean } from '@flipt-io/flipt-client-react';
// A custom component that renders its children if the feature flag is enabled
function FeatureFlag({ flagKey, entityId, children }) {
const isEnabled = useFliptBoolean('flagKey', false, entityId, {
// additional context
});
return isEnabled ? children : null;
}
function App() {
return (
My App
{/* Will render the children if the feature flag evaluation results in true */}
This is a new feature!
);
}
export default App;
```
## 捐款
欢迎捐款! 请随意打开一个问题或提交拉出请求.
## 许可证
本项目根据以下规定获得许可证: [MIT 许可证](https://npmcn.com/package/%40flipt-io/flipt-client-react/LICENSE)。 。 。 .
## 常见问题
### @flipt-io/flipt-client-react 是什么？
翻转客户端评价反应SDK
### 如何安装 @flipt-io/flipt-client-react？
在项目目录运行 npm install @flipt-io/flipt-client-react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=16\.8\.0）、react-dom（\>=16\.8\.0）、@flipt-io/flipt-client-js（^0\.6\.0 \|\| ^0\.7\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @flipt-io/flipt-client-react 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @flipt-io/flipt-client-react 支持 ESM 还是 CommonJS？
同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。
### @flipt-io/flipt-client-react 可以商用吗？
@flipt-io/flipt-client-react 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @flipt-io/flipt-client-react 的下载量有多少？
根据 npm 官方下载统计，@flipt-io/flipt-client-react 在 2026/10/15 – 2026/11/13 这 30 天内被下载 94,618 次，日均约 3,154 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @flipt-io/flipt-client-react 还在维护吗？
最新版本 1\.3\.0 发布于 2026/11/09（7 天前）；至今共发布 18 个版本，其中过去 12 个月发布了 5 个；首次发布于 2024/09/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。