透過 FirebaseUI 輕鬆將登入程序新增至網頁應用程式

FirebaseUI for Web 是一組以 Firebase 驗證 JavaScript SDK 為基礎建構的程式庫，可協助您快速發布驗證流程。

FirebaseUI for Web 提供下列優點：

  • 支援使用 initializeApp(...) 和目前的 Firebase JS SDK，打造現代模組化 SDK。
  • 可組合的畫面、表單和按鈕，而非單一的單體式小工具。
  • 支援 React、Shadcn 和 Angular。
  • 可設定重新導向與彈出式視窗流程、Google One Tap、匿名升級、手機設定等行為。
  • 透過 @firebase-oss/ui-translations 支援本地化。
  • 內建支援電子郵件/密碼、電子郵件連結、電話驗證、OAuth 供應商和多重驗證流程。

本指南將逐步說明如何安裝、初始化、登入，以及設定 React、Shadcn 和 Angular 應用程式。

事前準備

  1. 將 Firebase 新增至您的網頁應用程式：

    在 Firebase 控制台中啟用「驗證」。

    如果專案中尚未安裝 firebase，請執行下列操作：

    npm install firebase

    使用模組化 Firebase JS SDK：

    import { initializeApp } from 'firebase/app';

const app = initializeApp({
  /* your Firebase config */
});

  2. 選擇平台並安裝 FirebaseUI：

    如果是以 shadcn/ui 為基礎的 React 應用程式，請將 Firebase 登錄檔新增至 components.json：

    {
  "registries": {
    "@firebase": "https://firebaseopensource.com/r/{name}.json"
  }
}

    本指南中使用的驗證元件都可從該登錄檔取得，包括 sign-in-auth-screen、sign-up-auth-screen、email-link-auth-screen、oauth-screen、phone-auth-screen、google-sign-in-button、apple-sign-in-button 和 github-sign-in-button。

    然後新增要使用的元件：

    npx shadcn@latest add @firebase/sign-in-auth-screen @firebase/google-sign-in-button

    這會為您安裝基礎的 React FirebaseUI 依附元件。

    如果 React 應用程式沒有 shadcn/ui，請安裝：

    npm install @firebase-oss/ui-react@beta @firebase-oss/ui-styles

    如果是 Angular 應用程式，請安裝：

    npm install @angular/fire @firebase-oss/ui-angular@beta @firebase-oss/ui-core@beta @firebase-oss/ui-styles@beta

初始化 FirebaseUI

使用 initializeUI(...) 建立共用 UI 商店，然後傳遞至架構整合。

回應

import { initializeApp } from 'firebase/app';
import { initializeUI } from '@firebase-oss/ui-core';
import { FirebaseUIProvider } from '@firebase-oss/ui-react';

const app = initializeApp({
  /* your Firebase config */
});

const ui = initializeUI({
  app,
});

export function AppProviders({ children }: { children: React.ReactNode }) {
  return <FirebaseUIProvider ui={ui}>{children}</FirebaseUIProvider>;
}

Shadcn

Shadcn 的設定與 React 相同，因為它在幕後也使用 @firebase-oss/ui-react：

import { initializeApp } from 'firebase/app';
import { initializeUI } from '@firebase-oss/ui-core';
import { FirebaseUIProvider } from '@firebase-oss/ui-react';

const app = initializeApp({
  /* your Firebase config */
});

const ui = initializeUI({
  app,
});

export function AppProviders({ children }: { children: React.ReactNode }) {
  return <FirebaseUIProvider ui={ui}>{children}</FirebaseUIProvider>;
}

這些元件會使用現有的 shadcn 樣式；使用 shadcn 登錄檔時，您通常不會匯入 FirebaseUI 隨附的 CSS。

Angular

import { type ApplicationConfig } from '@angular/core';
import { provideFirebaseApp, initializeApp } from '@angular/fire/app';
import { provideFirebaseUI } from '@firebase-oss/ui-angular';
import { initializeUI } from '@firebase-oss/ui-core';

export const appConfig: ApplicationConfig = {
  providers: [
    provideFirebaseApp(() =>
      initializeApp({
        /* your Firebase config */
      }),
    ),
    provideFirebaseUI((apps) =>
      initializeUI({
        app: apps[0],
      }),
    ),
  ],
};

包括樣式

FirebaseUI 預先建構了 React 和 Angular 的 UI 元件。如要使用元件，請加入其 CSS：

如果搭配 React 或 Angular 使用 Tailwind：

否則，請加入 FirebaseUI 樣式：

@import '@firebase-oss/ui-styles/dist.min.css';

FirebaseUI for Web 支援透過 CSS 變數覆寫自訂主題。詳情請參閱主題設定說明文件。

設定登入方式

使用者必須先在 Firebase 主控台的「驗證」->「登入方式」中啟用各項供應商，才能登入。

網頁版 FirebaseUI 會直接顯示畫面、表單和按鈕。這些流程的共用設定位於傳遞至 initializeUI(...) 的 behaviors 中。

電子郵件地址和密碼

  1. 在 Firebase 控制台中啟用「電子郵件/密碼」。
  2. 在 React 中算繪 SignInAuthScreen 或 SignUpAuthScreen、在 Shadcn 中產生的 sign-in-auth-screen 或 sign-up-auth-screen 元件，或在 Angular 中算繪 fui-sign-in-auth-screen 或 fui-sign-up-auth-screen。
  1. 在 Firebase 控制台中啟用「電子郵件/密碼」和「電子郵件連結 (不需要密碼即可登入)」。
  2. 在 React 中算繪 EmailLinkAuthScreen、在 Shadcn 中算繪產生的 email-link-auth-screen 元件，或在 Angular 中算繪 fui-email-link-auth-screen。
  3. 視需要使用核心輔助程式，透過目前的網址完成登入程序。
import { completeEmailLinkSignIn } from '@firebase-oss/ui-core';

await completeEmailLinkSignIn(ui, window.location.href);

OAuth 供應商

網頁版 FirebaseUI 支援 Google、Apple、Facebook、GitHub、Microsoft 和 X/Twitter 等供應商的內建按鈕。

  1. 在 Firebase 控制台中啟用供應商。
  2. 視需要將應用程式網域新增至「已授權網域」。
  3. 使用所需的供應商按鈕 (例如 React 中的 OAuthScreen、GoogleSignInButton、AppleSignInButton、FacebookSignInButton、GitHubSignInButton、MicrosoftSignInButton 或 TwitterSignInButton，應用程式中產生的 shadcn 對等項目，或 Angular 中的 fui-oauth-screen、fui-google-sign-in-button、fui-apple-sign-in-button、fui-facebook-sign-in-button、fui-github-sign-in-button、fui-microsoft-sign-in-button 或 fui-twitter-sign-in-button) 算繪。

電話號碼

  1. 在 Firebase 控制台中啟用「電話」。
  2. 將應用程式網域新增至「已授權網域」。
  3. 在 React 中算繪 PhoneAuthScreen 或 PhoneAuthForm、在 Shadcn 中算繪產生的 phone-auth-screen 或 phone-auth-form 元件，或在 Angular 中算繪 fui-phone-auth-screen。

選用：設定允許的國家/地區、預設國家/地區或 reCAPTCHA 行為：

import {
  countryCodes,
  initializeUI,
  recaptchaVerification,
} from '@firebase-oss/ui-core';

const ui = initializeUI({
  app,
  behaviors: [
    countryCodes({
      allowedCountries: ['GB', 'US', 'FR'],
      defaultCountry: 'GB',
    }),
    recaptchaVerification({
      size: 'compact',
      theme: 'light',
    }),
  ],
});

自訂

在傳遞至 initializeUI(...) 的 behaviors 中設定共用驗證行為。

要求使用者在註冊時提供顯示名稱

import { initializeUI, requireDisplayName } from '@firebase-oss/ui-core';

const ui = initializeUI({
  app,
  behaviors: [requireDisplayName()],
});

升級匿名使用者

使用 autoUpgradeAnonymousUsers(...) 行為將匿名工作階段併入已登入的帳戶。

import {
  autoUpgradeAnonymousUsers,
  initializeUI,
} from '@firebase-oss/ui-core';

const ui = initializeUI({
  app,
  behaviors: [
    autoUpgradeAnonymousUsers({
      async onUpgrade(ui, oldUserId, credential) {
        // Migrate or merge user data here if needed.
      },
    }),
  ],
});

如需遷移詳細資料，請參閱 MIGRATION.md)。

登入

算繪所需驗證畫面，並在元件回呼或 Angular 輸出中處理成功案例。

回應

```tsx import { SignInAuthScreen } from '@firebase-oss/ui-react'; import { useNavigate } from 'react-router';

export function SignInPage() { const navigate = useNavigate();

return ( { navigate('/dashboard'); }} /> ); } ```

Shadcn

Shadcn 使用與 React 相同的執行階段和流程。唯一差別在於，您是從應用程式匯入產生的元件，而不是從 @firebase-oss/ui-react 匯入：

```tsx import { SignInAuthScreen } from '@/components/sign-in-auth-screen'; import { useNavigate } from 'react-router';

export function SignInPage() { const navigate = useNavigate();

return ( { navigate('/dashboard'); }} /> ); } ```

Angular

import { Component } from '@angular/core';
import { Router } from '@angular/router';
import { SignInAuthScreenComponent } from '@firebase-oss/ui-angular';
import type { User } from '@angular/fire/auth';

@Component({
  selector: 'app-sign-in-page',
  standalone: true,
  imports: [SignInAuthScreenComponent],
  template: `
    <fui-sign-in-auth-screen (signIn)="onSignIn($event)" />
  `,
})
export class SignInPageComponent {
  constructor(private router: Router) {}

  onSignIn(user: User) {
    this.router.navigate(['/dashboard']);
  }
}

登出

如要登出使用者，請使用標準的 Firebase 驗證登出 API：

import { getAuth, signOut } from 'firebase/auth';

const auth = getAuth(app);
await signOut(auth);

OAuth 供應商：彈出式視窗與重新導向

選擇具有下列行為的供應商登入流程：

  • providerPopupStrategy() 手勢可開啟彈出式流程
  • providerRedirectStrategy()，適用於重新導向流程

彈出式視窗是預設值，因此您只需要明確設定重新導向：

import { initializeUI, providerRedirectStrategy } from '@firebase-oss/ui-core';

const ui = initializeUI({
  app,
  behaviors: [providerRedirectStrategy()],
});

如要顯示 OAuth 按鈕，請將按鈕新增至特定平台的畫面。

回應

import {
  GitHubSignInButton,
  GoogleSignInButton,
  OAuthScreen,
} from '@firebase-oss/ui-react';

export function OAuthPage() {
  return (
    <OAuthScreen>
      <GoogleSignInButton />
      <GitHubSignInButton />
    </OAuthScreen>
  );
}

Shadcn

import { GitHubSignInButton } from '@/components/github-sign-in-button';
import { GoogleSignInButton } from '@/components/google-sign-in-button';
import { OAuthScreen } from '@/components/oauth-screen';

export function OAuthPage() {
  return (
    <OAuthScreen>
      <GoogleSignInButton />
      <GitHubSignInButton />
    </OAuthScreen>
  );
}

Angular

import { Component } from '@angular/core';
import {
  GithubSignInButtonComponent,
  GoogleSignInButtonComponent,
  OAuthScreenComponent,
} from '@firebase-oss/ui-angular';

@Component({
  selector: 'app-oauth-page',
  standalone: true,
  imports: [
    OAuthScreenComponent,
    GoogleSignInButtonComponent,
    GithubSignInButtonComponent,
  ],
  template: `
    <fui-oauth-screen>
      <fui-google-sign-in-button />
      <fui-github-sign-in-button />
    </fui-oauth-screen>
  `,
})
export class OAuthPageComponent {}

Google One Tap

使用 oneTapSignIn(...) 行為啟用 Google One Tap：

import { initializeUI, oneTapSignIn } from '@firebase-oss/ui-core';

const ui = initializeUI({
  app,
  behaviors: [
    oneTapSignIn({
      clientId: 'YOUR_GOOGLE_WEB_CLIENT_ID',
      autoSelect: false,
      cancelOnTapOutside: false,
    }),
  ],
});

確認 Firebase 控制台已啟用 Google 登入功能，然後從 Google 供應商設定複製網頁用戶端 ID。

服務條款和隱私權政策

透過平台供應商設定附加政策連結。

回應

```tsx import { FirebaseUIProvider } from '@firebase-oss/ui-react';

<FirebaseUIProvider ui={ui} policies={{ termsOfServiceUrl: 'https://example.com/terms', privacyPolicyUrl: 'https://example.com/privacy', }}

{children} ; ```

Shadcn

使用與 React 相同的 FirebaseUIProvider 設定。

Angular

import { type ApplicationConfig } from '@angular/core';
import { provideFirebaseUIPolicies } from '@firebase-oss/ui-angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideFirebaseUIPolicies(() => ({
      termsOfServiceUrl: 'https://example.com/terms',
      privacyPolicyUrl: 'https://example.com/privacy',
    })),
  ],
};

翻譯

網頁版 FirebaseUI 支援透過 @firebase-oss/ui-translations 進行本地化。

import { initializeUI } from '@firebase-oss/ui-core';
import { registerLocale } from '@firebase-oss/ui-translations';

const enUsCustom = registerLocale('en-US', {
  labels: {
    signIn: 'Continue',
  },
});

const ui = initializeUI({
  app,
  locale: enUsCustom,
});

後續步驟