入門教學

學習如何匯入 Joy UI 元件並設定樣式，以建立具有淺色和深色模式的簡易登入頁面。

本教學將引導您了解如何使用 Joy UI 組裝基本登入頁面的 UI。您將認識幾個常見的元件，以及一些可用於控制其樣式的 props。您還會遇到 Joy UI 的主要功能，例如全域變體、sx prop 和 useColorScheme hook。

完成本教學後，您應該了解如何

匯入和自訂 Joy UI 元件
使用 sx 為 Joy UI 元件新增樣式
使用 component 覆寫預設 HTML 元素
使用 useColorScheme 切換淺色和深色模式

互動式範例

以下是最終產品的外觀—點擊範例下方的「顯示程式碼」按鈕以查看完整原始碼

先決條件

本教學假設您已完成以下事項

設定 React 應用程式—如果您需要樣板，請試試 Create React App
在您的應用程式中安裝 Joy UI—請參閱安裝以取得說明

匯入 Sheet 元件以建立結構

Sheet 元件是一個 <div> 容器，支援 Joy UI 的全域變體功能，有助於確保整個應用程式的一致性。

匯入 Sheet 並將其新增至您的應用程式，如下所示。（例如，如果您使用 Create React App，則所有程式碼都應放在 App.js 中。）

import * as React from 'react';
import { CssVarsProvider } from '@mui/joy/styles';
import Sheet from '@mui/joy/Sheet';

export default function App() {
  return (
    <CssVarsProvider>
      <Sheet variant="outlined">Welcome!</Sheet>
    </CssVarsProvider>
  );
}

使用 sx prop 新增樣式

所有 Joy UI 元件都接受 sx prop，讓您可以存取用於編寫 CSS 的簡寫語法。它非常適合建立一次性自訂或快速實驗不同的樣式。

將上一步中的基本 Sheet 替換為以下 sx 樣式的 Sheet

<Sheet
  sx={{
    width: 300,
    mx: 'auto', // margin left & right
    my: 4, // margin top & bottom
    py: 3, // padding top & bottom
    px: 2, // padding left & right
    display: 'flex',
    flexDirection: 'column',
    gap: 2,
    borderRadius: 'sm',
    boxShadow: 'md',
  }}
>
  Welcome!
</Sheet>

使用 Typography 元件新增文字

Typography 元件取代了 HTML header、paragraph 和 span 標籤，以幫助維護頁面上文字的一致層級結構。

level prop 讓您可以存取預先定義的排版值比例。Joy UI 預設提供 11 個排版層級。

四個標題層級：'h1' | 'h2' | 'h3' | 'h4'
三個標題層級：'title-lg' | 'title-md' | 'title-sm'
四個內文層級：'body-lg' | 'body-md' | 'body-sm' | 'body-xs'

將 Typography 的 import 新增到其餘的 imports 中

import Typography from '@mui/joy/Typography';

將 Sheet 元件內的 Welcome! 替換為這個 <div>

<div>
  <Typography level="h4" component="h1">
    Welcome!
  </Typography>
  <Typography level="body-sm">Sign in to continue.</Typography>
</div>

為使用者輸入新增文字欄位

Form Control、Form Label 和 Input 元件可以一起使用，為您提供複雜的使用者輸入欄位。

將 Form Control、Form Label 和 Input 的 imports 新增到其餘的 imports 中

import FormControl from '@mui/joy/FormControl';
import FormLabel from '@mui/joy/FormLabel';
import Input from '@mui/joy/Input';

將這兩個文字欄位插入到上一步的 <div> 下方，在 Sheet 內部

<FormControl>
  <FormLabel>Email</FormLabel>
  <Input
    // html input attribute
    name="email"
    type="email"
    placeholder="johndoe@email.com"
  />
</FormControl>
<FormControl>
  <FormLabel>Password</FormLabel>
  <Input
    name="password"
    type="password"
    placeholder="password"
  />
</FormControl>

Button 和 Link 元件分別取代了 HTML <button> 和 <a> 標籤，讓您可以存取全域變體、sx 和 component props 等功能。

將以下 imports 新增到應用程式中其餘的 imports 中

import Button from '@mui/joy/Button';
import Link from '@mui/joy/Link';

在上一步的文字欄位之後，新增以下 Button、Typography 和 Link 元件，仍然巢狀在 Sheet 內部。請注意，Link 是附加到 endDecorator prop 內的 Typography。

<Button sx={{ mt: 1 /* margin top */ }}>
  Log in
</Button>
<Typography
  endDecorator={<Link href="/sign-up">Sign up</Link>}
  fontSize="sm"
  sx={{ alignSelf: 'center' }}
>
  Don't have an account?
</Typography>

🎁 獎勵：建立淺色和深色模式的切換開關

useColorScheme hook 有助於實作應用程式中淺色和深色模式之間切換的切換按鈕。它還使 Joy UI 能夠確保使用者選取的模式（預設儲存在 localStorage 中）在瀏覽器標籤之間保持同步。

將 useColorScheme 新增到您從 @mui/joy/styles 匯入的項目中

import { CssVarsProvider, useColorScheme } from '@mui/joy/styles';

接下來，透過在 imports 和 App() 之間新增以下程式碼片段來建立淺色/深色模式切換器

import Select from '@mui/joy/Select';
import Option from '@mui/joy/Option';

function ModeToggle() {
  const { mode, setMode } = useColorScheme();
  const [mounted, setMounted] = React.useState(false);

  // necessary for server-side rendering
  // because mode is undefined on the server
  React.useEffect(() => {
    setMounted(true);
  }, []);
  if (!mounted) {
    return null;
  }

  return (
    <Select
      value={mode}
      onChange={(event, newMode) => {
        setMode(newMode);
      }}
      sx={{ width: 'max-content' }}
    >
      <Option value="system">System</Option>
      <Option value="light">Light</Option>
      <Option value="dark">Dark</Option>
    </Select>
  );
}

最後，將您新建立的 <ModeToggle /> 按鈕新增到 <Sheet /> 上方

 export default function App() {
   return (
     <CssVarsProvider>
+      <ModeToggle />
       <Sheet>...</Sheet>
     </CssVarsProvider>
   );
 }

您的應用程式現在應該看起來像頁面頂部的互動式範例。做得好，一路完成到最後！

摘要

以下是使用的元件回顧

以下是一些介紹的主要功能

下一步

本教學未涵蓋主題設定或一般元件自訂。深入了解不同的自訂方法以及何時應用它們。

若要查看 Joy UI 實際運作中更複雜的範例，請查看我們的範本集合。

您是否從 Material UI 遷移？了解如何在一個應用程式中同時使用 Joy UI 和 Material UI。