跳到主要內容
🚀 影響 Toolpad Core 2025 年的產品藍圖！參與最新的開發者問卷調查
+

基礎概念

了解 Toolpad Core 的基本概念，以便有效地整合並在您的專案中使用它。

導入

Toolpad Core 組件可以直接從 @toolpad/core 套件導入。這讓您可以將它們與現有的 Material UI 或其他組件一起使用。

import Button from '@mui/material/Button';
import { DashboardLayout } from '@toolpad/core/DashboardLayout';

組件層級結構

Toolpad Core 函式庫旨在於不同的 React 執行環境下運作，例如 Next.js、Vite，甚至是您自訂的設定。它的許多組件都依賴於它們所使用之特定執行環境的功能。使組件感知執行環境的關鍵組件是 AppProvider。

App Provider

AppProvider 作為您的應用程式執行環境和 Toolpad 組件之間的橋樑。它應該包裹您的整個應用程式，或是您想要使用 Toolpad 組件的應用程式部分。

import { AppProvider } from '@toolpad/core/AppProvider';

function MyApp({ Component, pageProps }) {
  return (
    <AppProvider>
      <Component {...pageProps} />
    </AppProvider>
  );
}

透過使用 AppProvider 包裹您的應用程式，您可以確保您使用的所有其他 Toolpad 組件都能存取必要的上下文和功能。

AppProvider 組件接受 props 來配置應用程式的導航、主題、品牌、路由器、身份驗證和會話，如下所示

<AppProvider
  navigation={NAVIGATION}
  theme={theme}
  branding={BRANDING}
  router={router}
  authentication={AUTHENTICATION}
  session={session}
>
  {props.children}
</AppProvider>

前往 AppProvider 頁面以獲取更多詳細資訊以及所有 props 的使用範例。

插槽 (Slots)

Toolpad Core 使用插槽 (slots) 進行組件自訂。插槽允許您覆寫組件的特定部分，提供樣式和功能上的彈性。您也可以使用 slotProps prop 將額外的 props 傳遞到特定的插槽。

以下是使用 SignInPage 組件的範例

import { SignInPage } from '@toolpad/core/SignInPage';
function MyComponent() {
  return (
    <SignInPage
      slots={{
        emailField: CustomEmailField,

      }}
      slotProps={{
        passwordField: {
          variant: 'outlined',
        },
      }}
    >
      Custom Button
    </Button>
  );
}

在此範例中

  • slots prop 允許您替換組件的整個部分。
  • slotProps prop 讓您可以將額外的 props 傳遞到特定的插槽。

本地化 (Localization)

Toolpad 組件支援語言之間的翻譯。您可以透過幾種方式修改 Toolpad 組件內的文字和翻譯。

預設的語系是英文（美國）。要使用其他語系，請按照以下說明操作。

全域設定翻譯

使用主題

要翻譯所有 Toolpad 組件，您可以透過主題提供翻譯

import { createTheme, ThemeProvider } from '@mui/material/styles';
import { hiIN as coreHiIn } from '@mui/material/locale';
import hiIN from '@toolpad/core/locales/hiIN';

const theme = createTheme({
   {
    palette: {
      primary: { main: '#1976d2' },
    },
  },
  coreHiIn,
  hiIN,
});

 // ...
 <AppProvider theme={theme}>{children}</AppProvider>;

使用 localeText prop

如果您想在不使用 createTheme 的情況下傳遞語言翻譯，您可以直接透過 AppProvider 上的 localeText prop 提供它們

import { AppProvider } from '@toolpad/core/AppProvider';
import hiIN from '@toolpad/core/locales/hiIN';

function App({ children }) {
  return (
    <AppProvider
      localeText={hiIN.components.MuiLocalizationProvider.defaultProps.localeText}
    >
      {children}
    </AppProvider>
  );
}

如果您在應用程式中沒有使用 AppProvider，您可以直接使用 LocalizationProvider

import { LocalizationProvider } from '@toolpad/core/AppProvider';
import hiIN from '@toolpad/core/locales/hiIN';

function App({ children }) {
  return (
    <LocalizationProvider
      localeText={hiIN.components.MuiLocalizationProvider.defaultProps.localeText}
    >
      {children}
    </LocalizationProvider>
  );
}

本地設定翻譯

如果您想自訂特定組件上的一些翻譯，您可以使用所有組件公開的 localeText prop。

<SignInPage localeText={{ signInTitle: '...' }}></SignInPage>

優先順序

本地化系統在應用翻譯時遵循特定的優先順序

  1. 直接提供給特定組件的 localeText prop（最高優先順序）
  2. 直接提供給 AppProvider 的 localeText prop
  3. 透過主題提供的翻譯
  4. 預設英文翻譯（最低優先順序）

存取本地化鍵

您可以使用 useLocaleText() Hook 在自訂組件中存取您的本地化鍵。

import { useLocaleText } from '@toolpad/core/AppProvider';

function CustomMenu() {
  // ...
  const localeText = useLocaleText();
  // ...
}