Upgrade to Grid v2
Upgrade to Grid v2 (Grid v2로 업그레이드)
이 가이드는 GridLegacy 컴포넌트에서 Grid 컴포넌트로 마이그레이션하는 방법과 그 이유를 설명해요.
출처: 문서
본문
Grid component versions (Grid 컴포넌트 버전)
Material UI v7에서 GridLegacy 컴포넌트는 더 이상 사용되지 않으며(deprecated), 몇 가지 새로운 기능과 개발자 경험(developer experience)의 큰 개선을 제공하는 Grid로 대체되었어요. 이 가이드는 GridLegacy에서 Grid로 업그레이드하는 방법을 설명하고, Material UI v5, v6, v7에 대한 세부 내용을 포함해요.
Why you should upgrade (왜 업그레이드해야 하나요)
Grid는 GridLegacy에 비해 다음과 같은 개선을 제공해요:
- CSS 변수를 사용해서 클래스 선택자의 CSS 특이성(specificity)을 제거해요.
sxprop을 사용해 원하는 어떤 스타일이든 제어할 수 있어요. - 모든 그리드는
itemprop을 지정하지 않아도 item으로 간주돼요. - 오프셋 기능은 위치(positioning)에 더 큰 유연성을 제공해요.
- 중첩 그리드(Nested grids)는 이제 깊이 제한이 없어요.
- 구현이 음수 마진(negative margins)을 사용하지 않기 때문에 넘치지 않아요.
How to upgrade (업그레이드 방법)
Prerequisites (사전 요구사항)
이 업그레이드를 진행하기 전에:
- Material UI v5+를 사용하고 있어야 해요.
- Material UI 버전을 업그레이드하는 과정 중이라면, 먼저 해당 업그레이드를 완료해야 해요.
1. Update the import (import 업데이트)
사용 중인 Material UI 버전에 따라 import를 다음과 같이 업데이트해야 해요:
// The legacy Grid component is named GridLegacy
-import Grid from '@mui/material/GridLegacy';
// The updated Grid component is named Grid
+import Grid from '@mui/material/Grid';
// The legacy Grid component is named Grid
-import Grid from '@mui/material/Grid';
// The updated Grid component is named Grid2
+import Grid from '@mui/material/Grid2';
// The legacy Grid component is named Grid
-import Grid from '@mui/material/Grid';
// The updated Grid component is named Unstable_Grid2
+import Grid from '@mui/material/Unstable_Grid2';
2. Remove legacy props (레거시 props 제거)
item과 zeroMinWidth props는 업데이트된 Grid에서 제거되었어요. 안전하게 제거할 수 있어요:
-<Grid item zeroMinWidth>
+<Grid>
3. Update the size props (size props 업데이트)
:::warning Material UI v5를 사용 중이라면 이 단계를 건너뛰세요. :::
GridLegacy 컴포넌트에서 size props는 테마의 브레이크포인트와 대응하도록 명명되었어요. 기본 테마에서는 xs, sm, md, lg, xl이었어요.
Material UI v6부터 이 props는 업데이트된 Grid에서 size로 이름이 변경되었어요:
<Grid
- xs={12}
- sm={6}
+ size={{ xs: 12, sm: 6 }}
>
모든 브레이크포인트에서 크기가 같다면, 단일 값을 사용할 수 있어요:
-<Grid xs={6}>
+<Grid size={6}>
또한, size props의 true 값은 "grow"로 이름이 바뀌었어요:
-<Grid xs>
+<Grid size="grow">
size props를 업데이트하려면 다음 codemod를 사용할 수 있어요:
npx @mui/codemod@latest v7.0.0/grid-props <path/to/folder>
npx @mui/codemod@latest v6.0.0/grid-v2-props <path/to/folder>
Skip this step if you're using Material UI v5.
:::warning 이 codemod는 사전에 import를 업데이트해야 해요. :::
4. Opt in to legacy negative margins (레거시 음수 마진 사용 설정)
:::warning Material UI v6 또는 v7을 사용 중이라면 이 단계를 건너뛰세요. :::
Material UI v5를 사용 중이고 GridLegacy와 유사한 음수 마진을 적용하려면, 그리드 컨테이너에 disableEqualOverflow={true}를 지정해요. 모든 그리드에 적용하려면, 테마에 기본 props를 추가해요:
import { createTheme, ThemeProvider } from '@mui/material/styles';
import Grid from '@mui/material/Unstable_Grid2';
const theme = createTheme({
components: {
MuiGrid2: {
defaultProps: {
// all grids under this theme will apply
// negative margin on the top and left sides.
disableEqualOverflow: true,
},
},
},
});
function Demo() {
return (
<ThemeProvider theme={theme}>
<Grid container>...grids</Grid>
</ThemeProvider>
);
}
Common issues (흔한 문제들)
Column direction (컬럼 방향)
direction="column" 또는 direction="column-reverse" 사용은 지원되지 않아요. 레이아웃이 이런 값으로 GridLegacy를 사용했다면, 업데이트된 Grid로 전환할 때 깨질 수 있어요. 세로 레이아웃이 필요하다면 Grid 문서의 지침을 따라보세요.
Container width (컨테이너 너비)
업데이트된 Grid 컴포넌트는 기본적으로 컨테이너의 전체 너비로 자라지 않아요. 그리드가 전체 너비로 자라도록 하려면 sx prop을 사용할 수 있어요:
-<GridLegacy container>
+<Grid container sx={{ width: '100%' }}>
// alternatively, if the Grid's parent is a flex container:
-<GridLegacy container>
+<Grid container sx={{ flexGrow: 1 }}>
Codemod not covering wrapped Grid components (코드모드가 감싸진 Grid 컴포넌트를 다루지 못함)
제공된 codemod는 다른 컴포넌트에 감싸져 있거나 styled 처리된 Grid 컴포넌트를 다루지 못해요:
// The codemod won't cover StyledGrid
const StyledGrid = styled(Grid)({
// styles
});
// The codemod won't cover WrappedGrid
const WrappedGrid = (props) => <Grid {...props} />;
이 컴포넌트들은 직접 수동으로 업데이트해야 해요.
Documentation pages (문서 페이지)
- Grid: