入门教程

了解如何导入 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 标题、段落和 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 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 的导入添加到其余导入中

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 等。

将以下导入添加到应用程序中的其余导入中

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';

接下来，通过在导入和 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>
  );
}

最后，在 <Sheet /> 上方添加新构建的 <ModeToggle /> 按钮

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

您的应用程序现在应该看起来像页面顶部的交互式演示。干得好，一路走到最后！

总结

以下是使用的组件的摘要

以下是介绍的一些主要特性

下一步

本教程不涵盖主题或常规组件自定义。了解有关不同自定义方法以及何时应用它们的更多信息。

要查看 Joy UI 在实践中更复杂的示例，请查看我们的模板集合。

您是否正在从 Material UI 迁移？了解如何在一个应用程序中同时使用 Joy UI 和 Material UI。