@xid-kit/react

面向客户应用的 React 19 provider、hooks、控制组件和 Hosted UI 构建块。

Provider 配置

import { XidProvider } from '@xid-kit/react'

export function AppProviders({ children }: { children: React.ReactNode }) {
  return (
    <XidProvider publishableKey="pk_live_..." apiUrl="https://xid.dev">
      {children}
    </XidProvider>
  )
}

Hooks

Hook	返回值
`useAuth`	isLoaded、isSignedIn、userId、signOut、getToken
`useUser`	isLoaded、isSignedIn、user: XidUser \| null
`useSession`	isLoaded、isSignedIn、session: XidSession \| null
`useSessionList`	isLoaded、sessions、用于多会话切换器的 setActive
`useSignIn`	Hosted Auth 登录流程辅助工具
`useOrganization`	isLoaded、organization: XidOrganization \| null、membership
`useOrganizationList`	isLoaded、用于组织切换器 UI 的 userMemberships
`useAPIKeys`	用于控制台嵌入的 Management API 密钥列表和操作
`useXidContext`	原始 XidContextValue（高级用法；优先使用上方的类型化 hooks）

控制组件

组件	Props 类型	用途
`SignedIn`	`SignedInProps`	仅在会话已加载且已登录时渲染子节点
`SignedOut`	`SignedOutProps`	仅在已加载且未登录时渲染子节点
`Protect`	`ProtectProps`	带可选后备 UI 的权限和角色校验门
`XidLoaded`	`XidLoadedProps`	SDK 水合完成后渲染子节点（isLoaded 为 true）
`XidLoading`	`XidLoadingProps`	SDK 仍在加载时渲染子节点（isLoaded 为 false）
`XidFailed`	`XidFailedProps`	SDK 加载因不可恢复错误失败时渲染子节点（status 为 error）
`XidDegraded`	`XidDegradedProps`	SDK 已加载但处于降级状态时渲染子节点（status 为 degraded）
`AuthenticateWithRedirectCallback`	`AuthenticateWithRedirectCallbackProps`	OAuth 重定向 callback 处理器：重新加载会话状态，并重定向到 afterSignInUrl 或调用 onSuccess
`RedirectToSignIn`	`RedirectToSignInProps`	挂载后立即重定向到登录页面
`RedirectToSignUp`	`RedirectToSignUpProps`	挂载后立即重定向到注册页面
`RedirectToUserProfile`	`RedirectToUserProfileProps`	挂载后立即重定向到用户资料页面
`RedirectToOrganizationProfile`	`RedirectToOrganizationProfileProps`	挂载后立即重定向到组织资料页面
`RedirectToCreateOrganization`	`RedirectToCreateOrganizationProps`	挂载后立即重定向到创建组织页面
`SignInButton`	`SignInButtonProps`	点击时跳转到登录 URL 的无样式按钮
`SignUpButton`	`SignUpButtonProps`	点击时跳转到注册 URL 的无样式按钮
`SignOutButton`	`SignOutButtonProps`	点击时调用 signOut 的无样式按钮

UI 组件

组件	使用
`SignIn`	嵌入式登录面板（Hosted Auth）
`SignUp`	嵌入式注册面板
`UserAvatar`	带首字母后备的用户头像图片
`UserButton`	带会话切换和登出功能的头像菜单
`UserProfile`	账户安全与资料管理
`OrganizationSwitcher`	当前组织选择器
`OrganizationProfile`	成员、角色和 SSO 管理嵌入组件
`CreateOrganization`	组织创建流程
`OrganizationList`	用于切换器 UI 的用户组织列表

尚未实现

以下内容在公开路线图中，但当前包尚未导出。请勿假设在本版本中可用。

符号	设计承诺
`GoogleOneTap`	一键登录嵌入组件
`Waitlist`	候补名单注册门控组件
计费组件	用量和套餐管理嵌入组件
`useReverification`	Step-up 认证 hook

外观

将 appearance 传给 XidProvider 以覆盖白标嵌入的 CSS 变量。所有用户可见字符串使用 Lingui 运行时描述符；Appearance、AppearanceVariables 和 AppearanceElements 类型已导出供类型化覆盖使用。