React SDK

安装

npm install @melody-auth/react --save

AuthProvider

将你的应用包裹在 AuthProvider 组件内，为应用中的其他组件提供认证上下文。

参数	类型	描述	默认值	必填
clientId	string	前端所连接的 app clientId	N/A	是
redirectUri	string	认证成功后重定向的 URL	N/A	是
serverUri	string	托管认证服务器的 URL	N/A	是
scopes	string[]	需要申请的权限作用域	N/A	否
storage	'sessionStorage' \| 'localStorage'	用于存储认证令牌的存储类型	'localStorage'	否
onLoginSuccess	(attr: { locale?: string; state?: string }) => void	登录成功后执行的回调函数	N/A	否

import { AuthProvider } from '@melody-auth/react'

export default function RootLayout ({ children }: {
  children: React.ReactNode;
}) {
  return (
    <html lang='en'>
      <AuthProvider
        clientId={process.env.CLIENT_ID ?? ''}
        redirectUri={process.env.REDIRECT_URI ?? ''}
        serverUri={process.env.SERVER_URI ?? ''}
      >
        <body>
          {children}
        </body>
      </AuthProvider>
    </html>
  )
}

isAuthenticated

用于判断当前用户是否已通过认证。

import { useAuth } from '@melody-auth/react'

export default function Home () {
  const { isAuthenticating, isAuthenticated } = useAuth()

  if (isAuthenticating) return <Spinner />
  if (isAuthenticated) return <Button>登出</Button>
  if (!isAuthenticated) return <Button>登录</Button>
}

loginRedirect

通过浏览器重定向的方式开启新的认证流程。

参数	类型	描述	默认值	必填
locale	string	指定认证流程使用的语言	N/A	否
state	string	若不使用自动生成的随机串，可自定义 state 参数	N/A	否
policy	string	指定要使用的策略	'sign_in_or_sign_up'	否
org	string	指定要使用的组织，值为组织的 slug	N/A	否

import { useAuth } from '@melody-auth/react'

export default function Home () {
  const { isAuthenticated, loginRedirect } = useAuth()

  const handleLogin = () => {
    loginRedirect({
      locale: 'en',
      state: JSON.stringify({ info: Math.random() })
    })
  }

  if (!isAuthenticated) {
    return <Button onClick={handleLogin}>登录</Button>
  }
}

loginPopup

在弹窗中开启新的认证流程。

参数	类型	描述	默认值	必填
locale	string	指定认证流程使用的语言	N/A	否
state	string	若不使用自动生成的随机串，可自定义 state 参数	N/A	否
org	string	指定要使用的组织，值为组织的 slug	N/A	否

import { useAuth } from '@melody-auth/react'

export default function Home () {
  const { isAuthenticated, loginPopup } = useAuth()

  const handleLogin = () => {
    loginPopup({
      locale: 'en',
      state: JSON.stringify({ info: Math.random() })
    })
  }

  if (!isAuthenticated) {
    return <Button onClick={handleLogin}>登录</Button>
  }
}

logoutRedirect

触发退出登录流程。

参数	类型	描述	默认值	必填
postLogoutRedirectUri	string	退出后跳转的 URL	N/A	否

import { useAuth } from '@melody-auth/react'

export default function Home () {
  const { isAuthenticated, logoutRedirect } = useAuth()

  const handleLogout = () => {
    logoutRedirect({ postLogoutRedirectUri: 'http://localhost:3000/' })
  }

  if (isAuthenticated) {
    return <Button onClick={handleLogout}>登出</Button>
  }
}

acquireToken

获取用户的 accessToken，若已过期则自动刷新。

import { useAuth } from '@melody-auth/react'

export default function Home () {
  const { isAuthenticated, acquireToken } = useAuth()

  const handleFetchUserInfo = () => {
    const accessToken = await acquireToken()
    // 使用 accessToken 获取受保护资源
    await fetch('/...', {
      headers: {
        Authorization: `Bearer ${accessToken}`,
      },
    })
  }

  if (isAuthenticated) {
    return <Button onClick={handleFetchUserInfo}>获取用户信息</Button>
  }
}

acquireUserInfo

从认证服务器获取当前用户的公开信息。

import { useAuth } from '@melody-auth/react'

export default function Home () {
  const { isAuthenticated, acquireUserInfo } = useAuth()

  const handleFetchUserInfo = () => {
    const userInfo = await acquireUserInfo()
  }

  if (isAuthenticated) {
    return <Button onClick={handleFetchUserInfo}>获取用户信息</Button>
  }
}

userInfo

当前用户信息。在访问 userInfo 之前，请先调用 acquireUserInfo。

import { useAuth } from '@melody-auth/react'

export default function Home () {
  const { userInfo } = useAuth()

  <div>{JSON.stringify(userInfo)}</div>
}

isAuthenticating

指示 SDK 是否正在初始化并尝试获取用户认证状态。

import { useAuth } from '@melody-auth/react'

export default function Home () {
  const { isAuthenticating } = useAuth()

  if (isAuthenticating) return <Spinner />
}

isLoadingToken

指示 SDK 是否正在获取或刷新令牌。

import { useAuth } from '@melody-auth/react'

export default function Home () {
  const { isLoadingToken } = useAuth()

  if (isLoadingToken) return <Spinner />
}

isLoadingUserInfo

指示 SDK 是否正在获取用户信息。

import { useAuth } from '@melody-auth/react'

export default function Home () {
  const { isLoadingUserInfo } = useAuth()

  if (isLoadingUserInfo) return <Spinner />
}

authenticationError

指示是否发生了与认证流程相关的错误。

import { useAuth } from '@melody-auth/react'

export default function Home () {
  const { authenticationError } = useAuth()

  if (authenticationError) return <Alert />
}

acquireTokenError

指示是否发生了与 acquireToken 流程相关的错误。

import { useAuth } from '@melody-auth/react'

export default function Home () {
  const { acquireTokenError } = useAuth()

  if (acquireTokenError) return <Alert />
}

acquireUserInfoError

指示是否发生了与 acquireUserInfo 流程相关的错误。

import { useAuth } from '@melody-auth/react'

export default function Home () {
  const { acquireUserInfoError } = useAuth()

  if (acquireUserInfoError) return <Alert />
}

idToken

当前用户的 id_token。

import { useAuth } from '@melody-auth/react'

export default function Home () {
  const { idToken } = useAuth()
}

account

从 id_token 解码得到的账户信息。

import { useAuth } from '@melody-auth/react'

export default function Home () {
  const { account } = useAuth()
}

loginError

指示是否发生了与登录流程相关的错误。

import { useAuth } from '@melody-auth/react'

export default function Home () {
  const { loginError } = useAuth()

  if (loginError) return <Alert />
}

logoutError

指示是否发生了与退出流程相关的错误。

import { useAuth } from '@melody-auth/react'

export default function Home () {
  const { logoutError } = useAuth()

  if (logoutError) return <Alert />
}