React.js 客户端 SDK 用于调色功能旗
使用此 README 开始使用我们的特性旗 (FF) 客户端 SDK 进行反应 。 本指南概述 从SDK开始 并提供一个完整的代码样本 让你尝试.
此样本不包括配置选项, 用于深度步骤和配置 SDK , 参见 页:1 反应客户端 SDK 引用。 。 。 .
所需资源
要使用 SDK , 请确定您是否:
- 安装了 Node.js v12 或更新版本
- 已安装 React.js v16.7 或更新版本
与我们的测试代码样本一样
- 在哈内斯平台上创建了特性旗
调用
harnessappdemodarkmode - 创建客户端 SDK 密钥 并把它复制出来
安装 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),当默认被送达.
出现这种情况时:
- 使用
asyncMode没有模式cache或者说initialEvaluations以及SDK还在初始化的地方. - 国旗标识符不正确(例如由于打字).
- 这个
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 引用 关于地物旗的更多信息,请参见: 我们 特性标记文档。 。 。 .