健康 API 的官方反应 SDK
概览
Healty SDK是一个用TypeScript所建的React组件库,提供组件和钩子,以方便与Hality的API合作. 目前得到支持的功能包括:
- 聊天
- 表单
- 预订和购买
在你开始之前
这个SDK意在用于一个使用Healthie的API的现有项目. 用户认证流量目前不是此 SDK 的一部分, 应该在您的工程中单独执行 .
安装
yarn add @healthie/sdk
yarn add @rails/actioncable graphql-ruby-client
# or
npm i @healthie/sdk
npm i @rails/actioncable graphql-ruby-client
基本设置
这个SDK在阿波罗客户端上方工作,假设你已经安装并设置了阿波罗客户端.
聊天和其他websocket能力使用ActionCable实现.
以下是阿波罗客户端的基本配置,以使SDK正常工作: 1
import {
ApolloProvider,
HttpLink,
ApolloClient,
InMemoryCache,
split,
} from '@apollo/client'
import { getMainDefinition } from '@apollo/client/utilities'
import * as ActionCable from '@rails/actioncable'
import ActionCableLink from 'graphql-ruby-client/subscriptions/ActionCableLink'
import { HealthieProvider } from '@healthie/sdk'
const httpLink = new HttpLink({
uri: 'https://api.gethealthie.com/graphql',
headers: {
authorization: 'Basic <user_auth_token>',
authorizationsource: 'API',
},
})
const cable = ActionCable.createConsumer(
'wss://ws.gethealthie.com/subscriptions?token=<user_auth_token>'
)
const wsLink = new ActionCableLink({ cable })
const link = split(
// split based on operation type
({ query }) => {
const definition = getMainDefinition(query)
if (!('operation' in definition)) {
return false
}
const { kind, operation } = definition
return kind === 'OperationDefinition' && operation === 'subscription'
},
wsLink,
httpLink
)
const client = new ApolloClient({
link,
cache: new InMemoryCache({
typePolicies: {
Query: {
fields: {
// custom configuration if needed
},
},
},
}),
})
export function App() {
return (
<ApolloProvider client={client}>
<HealthieProvider userId={'<user_id>'}>
{/* ... your app ... */}
</HealthieProvider>
</ApolloProvider>
)
}
替换 <user_auth_token> 在认证过程中获得的用户 API 密钥 <user_id> 带有当前认证用户的ID.
更多信息,请访问健康API认证 这里。 。 。 .
服务器系统渲染
Next.js,Remix,Astro等框架严重依赖服务器端渲染(SSR). 这意味着他们试图在服务器上渲染没有浏览器API的代码. 一些Healthie SDK组件(类似Chat)通过ActionCable库使用WebSockets. 如果您尝试在 Next.js 或其他 SSR 框架中使用以上 ActionCable 代码, 您可能会遇到错误 .
为解决这一问题,遵循以下步骤。 这一解决办法应有利于大多数框架。 如果你更喜欢特定框架的解决办法,例如: next/dynamic请查看您框架的文件.
首先,创建一个 useHydrated.ts 反应钩 可以帮助我们确定JS是否已经水分了.
import { useEffect, useState } from 'react'
let isHydrating = true
export function useHydrated() {
let [isHydrated, setIsHydrated] = useState(() => !isHydrating)
useEffect(function hydrate() {
isHydrating = false
setIsHydrated(true)
}, [])
return isHydrated
}
接下来,定义我们 ClientOnly.tsx 使儿童只成为客户的部分.
import { ReactNode } from 'react'
import { useHydrated } from './useHydrated'
type Props = {
children(): ReactNode
fallback?: ReactNode
}
export function ClientOnly({ children, fallback = null }: Props) {
return useHydrated() ? <>{children()}</> : <>{fallback}</>
}
然后确保懒惰地装入阿波罗普罗维德及其客户端定义,从而避免在服务器上运行WebSocket代码.
创建名为的文件 ApolloForHealthie.tsx 它包裹了阿波罗普罗维德.
type ProviderProps = {
children: React.ReactNode
}
// rest of the client initialization code (see the "Basic setup" guide)
// ...
// ...
// ...
const client = new ApolloClient({
link,
cache: new InMemoryCache(),
})
export default function ApolloForHealthie({ children }: ProviderProps) {
return <ApolloProvider client={client}>{children}</ApolloProvider>
}
最后,将新供应商懒散地装入并包装为客户端组件:
import { lazy } from 'react'
// it's important to use the React.lazy() instead of regular import
const ApolloForHealthie = lazy(() => import('./ApolloForHealthie'))
function Loading() {
return (
<div>
{/* Ideally this should be the same size as the original component to avoid layout shifts */}
</div>
)
}
export default function App() {
const healthieUserId = '__REPLACE_ME__'
return (
<ClientOnlyHydrated fallback={<Loading />}>
{() => (
<ApolloForHealthie>
<HealthieProvider userId={healthieUserId}>
{/* render Healthie components here */}
</HealthieProvider>
</ApolloForHealthie>
)}
</ClientOnlyHydrated>
)
}
上述代码将使ApolloClient和Healthie组件成为客户端,同时在服务器上渲染自定义的加载组件. 这阻止了在服务器上使用特定浏览器的API,如ActionCable.
示例用途
import { ConversationList, Chat, Form } from '@healthie/sdk'
import '@healthie/sdk/dist/styles/index.css'
// This example assumes you defined the Apollo Client according to the
// instructions described in the "Basic setup" section of the Readme
// const client = ...
export default function App() {
const healthieUserId = '' // obtain during the auth flow
return (
<ApolloProvider client={client}>
{/* HealthieProvider must be rendered before using any of these components */}
<HealthieProvider userId={healthieUserId}>
{/* ... */}
<div className="conversation-list-container">
<ConversationList />
</div>
<div className="chat-container">
<Chat />
</div>
{/* ... */}
<div>
<Form id="1">
</div>
{/* ... */}
</HealthieProvider>
</ApolloProvider>
)
}
构成部分
确保导入样式表, 通常在您的应用程序的根组件中 :
import '@healthie/sdk/dist/styles/index.css'
对话列表
此组件将获取当前认证用户的当前对话列表, 并在屏幕上显示 .
若无 onConversationClick 或者说 activeId 提供了道具,Healthie SDK将管理国家本身.
: bulb:默认和推荐的方法使这个组件成为"道具"同时留空并让"Healthie Context"管理状态.
<ConversationList
onConversationClick={handleOnConversationClick}
activeId="<conversation_id>"
/>
道具
| 专利名称 | 类型 | 说明 |
|---|---|---|
onConversationClick | Function | (可选)在用户点击会话项目时回拨以触发. 如果未提供, 将会将被点击的 conversaton 设定为活动 . |
activeId | string 编号 : null | 当前选中的对话的 (可选) ID 。 如果不提供,该组件将设定列表中的第一个对话为活动 . |
详细使用情况
import { useState } from 'react'
function Example() {
const [conversationId, setConversationId] = useState(null)
return (
<ConversationList
onConversationClick={(id) => {
setConversationId(id)
}}
activeId={conversationId}
/>
)
}
聊天
<Chat conversationId="<conversation_id>" />
3⁄4 ̄ ̧漯B: 如果你创造了
ConversationList没有自定义道具的组件,不要提供conversationId为了充分利用Healthie Context的全部能力而设计的道具.
道具
| 专利名称 | 类型 | 说明 |
|---|---|---|
conversationId | string | (可选)对话的ID打开. 获取这些信息 通过图形QL API 或使用 对话列表 组件。 如果没有提供, 则会从健康协议中进行主动对话 |
这个 Chat 组件为主容器的全部高度。 这使得你能够完全控制这个组件的大小和定位.
确保正确指定容器的高度(固定或流体),否则聊天信息可能无法被看到.
: bulb: 确保向用户提供当前认证的健康用户ID
HealthieProvider。否则,聊天部分将无法区分收发信件.
表单
这个 Form 组件在当前用户的上下文中生成一个表格模板(称为自定义模块格式)。 它会自动以用户的数据预填表(如果适用)并代表用户提交表.
<Form id="<custom_module_form_id>" />
道具
| 专利名称 | 类型 | 说明 |
|---|---|---|
id | string | 格式模板(海关模块表)的标识。 您可以通过查询等方式获取表单模板ID 表格完成请求 用于当前用户. |
submitButtonText | string? | (可选)在提交按钮上显示的文本 。 默认为"屈服". |
onSubmit | (values: FormFields) => Promise<boolean | void> | boolean | void | (可选)在提交表单时召回触发 。 回调会收到表格式数据作为参数提交. 你可以选择返回 false 从回调来防止表格提交。 在此情况下,您需要使用 createFormAnswerGroup 变相. |
onQueryStateChange | ({ loading, error, data }: QueryState) => void | (可选的)在加载表单时召回以接收阿波罗查询状态的更改更新. |
onMutationStateChange | ({ loading, error, data }: MutationState) => void | (可选)在提交表单时召回以接收阿波罗突变状态的更改更新. |
详细使用情况
import { useState } from 'react'
function Example() {
const customModuleFormId = '' // obtain via the GraphQL API
return (
<Form
id={customModuleFormId}
onSubmit={(data) => {
// do something with the data
// return false to prevent the form from submitting
}}
onQueryStateChange={({ loading, error, data }) => {
// access Apollo query status
}}
onMutationStateChange={({ loading, error, data }) => {
// access Apollo mutation statu
}}
submitButtonText="Submit form"
/>
)
}
样式
目前 Form 组件只通过压倒默认 CSS 类支持自定义样式。 所有字段都有类名 input-wrapper 或者说 form-field-container。每个字段类型都有自己的类名,因此可以针对特定字段.
此外,Healty SDK的所有组件都被包裹在 healthie-container 课.
要覆盖默认样式,您可以通过使用 CSS 特性来杠杆化 CSS 特性并覆盖默认样式 healthie-container 类作为父母选择者.
例如:
.healthie-container .input-text {
/* your styles */
}
无需使用此方法 !important 以覆盖默认样式,同时仍然能够根据您的需要形成组件样式.
文档和文件夹字段
这个 Form 组件支持渲染文档和文件夹字段。 这些字段打开了与健康网络应用中相应的文档或文件夹的链接. 默认情况下,链接会通过通用域来打开应用程序( phttps://security.gethealthie.com (中文(中国大陆) )) (中文(简体) ). 如果你使用标有"健康"的URL,你可以通过 brandedUrl 通过下列途径向保健机构提交信息: HealthieProvider 组件.
<HealthieProvider userId="<user_id>" brandedUrl="https://myapp.example.com">
<Form id="<form_id>" />
</HealthieProvider>
这将通过这样的品牌URL打开文档或文件夹:https://myapp.example.com/documents/{id}/download.
预订和购买
这个 Booking 组件生成日历和软件包的部件,使客户能够预订预约、浏览服务和购买软件包.
<Booking queryString={queryString} />
指定日历链接默认与健康生产 URL 生成 。 如果使用有品牌的"健康"后端URL或"健康"中转环境,可以通过 brandedBackendUrl 通过下列途径向保健机构提交信息: HealthieProvider 组件.
<HealthieProvider
userId="<user_id>"
brandedBackendUrl="https://staging-api.gethealthie.com"
>
<Booking queryString={queryString} />
</HealthieProvider>
道具
| 专利名称 | 类型 | 说明 |
|---|---|---|
queryString | string | 用于使预订部件嵌入的查询字符串 。 这是通过 共享链接 生成于健康板。 例如: ?dietitian_id=1&require_offering=true&offering_id=24&hide_package_images=false。 。 。 . |
许可证
这个SDK根据"健康反应SDK"许可证获得许可. 详见LICENSE文件.