Getting started

Getting started

@mantine/dates 패키지를 설치하고 사용하기 시작하는 방법을 안내하는 문서예요. 설치 후 스타일을 임포트하는 방법, 날짜 값 형식, DatesProvider, dayjs 사용에 대해 다뤄요.

출처: 문서

본문

설치 후 애플리케이션의 루트에 패키지 스타일을 임포트해요.

import '@mantine/core/styles.css';
// ‼️ core 패키지 스타일 다음에 dates 스타일을 임포트해요
import '@mantine/dates/styles.css';

스타일 임포트를 잊지 마세요 (Do not forget to import styles)

위 설치 지침을 따랐는데도 무언가 동작하지 않는다면(캘린더와 날짜 선택기에 스타일이 없어 깨져 보인다면), dates 스타일을 임포트하지 않은 것이 원인이에요. 이 문제를 해결하려면 애플리케이션 루트에 dates 스타일을 임포트해요.

import '@mantine/dates/styles.css';

사용법 (Usage)

@mantine/dates 패키지를 설치하고 스타일을 임포트한 후에는 패키지의 모든 컴포넌트를 사용할 수 있어요.

import { useState } from 'react';
import { DatePickerInput } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<Date | null>(null);
  return (
    <DatePickerInput
      label="Pick date"
      placeholder="Pick date"
      value={value}
      onChange={setValue}
    />
  );
}

날짜 값을 문자열로 (Date values as strings)

@mantine/dates 컴포넌트는 날짜 문자열과 함께 동작해요. 컴포넌트에 따라 YYYY-MM-DD 또는 YYYY-MM-DD HH:mm:ss 형식이에요. 이 문자열에는 시간대(timezone) 관련 정보가 포함되지 않아요.

dayjs

@mantine/dates 컴포넌트는 내부적으로 날짜 조작과 서식 지정에 dayjs를 사용해요. dayjs는 필수 의존성이므로 다른 날짜 라이브러리로 바꿀 수 없어요. 애플리케이션에서 다른 날짜 라이브러리를 사용하려면 별도로 설치해야 해요.

DatesProvider

DatesProvider 컴포넌트를 사용하면 @mantine/dates 패키지에서 내보내는 모든 컴포넌트에 공유되는 다양한 설정을 지정할 수 있어요. DatesProvider는 다음 설정을 지원해요.

• locale – dayjs locale. dayjs에서 해당 locale 모듈도 임포트해야 한다는 점에 주의해요. 기본값은 en
• firstDayOfWeek – 0~6 사이의 숫자, 0은 일요일, 6은 토요일. 기본값은 1(월요일)
• weekendDays – 0~6 사이의 숫자 배열, 0은 일요일, 6은 토요일. 기본값은 [0, 6](토요일·일요일)
• consistentWeeks – boolean. true이면 모든 달에 6주가 있어요. 기본값은 false

import 'dayjs/locale/ru';
import { DatesProvider, MonthPickerInput, DatePickerInput } from '@mantine/dates';

function Demo() {
  return (
    <DatesProvider settings={{ locale: 'ru', firstDayOfWeek: 1, weekendDays: [0, 6] }}>
      <MonthPickerInput label="Pick month" />
      <DatePickerInput label="Pick date" />
    </DatesProvider>
  );
}

일관된 주 (Consistent weeks)

레이아웃 이동을 피하려면 DatesProvider 설정에서 consistentWeeks: true를 설정해요. 그러면 밖의 날짜(outside days)가 같은 달이 아니어도 모든 달에 6주가 보장돼요.

import { DatePicker, DatesProvider } from '@mantine/dates';

function Demo() {
  return (
    <DatesProvider settings={{ consistentWeeks: true }}>
      <DatePicker />
    </DatesProvider>
  );
}

dayjs 없이 서식 지정 (Formatting without dayjs)

모든 서식 지정 props는 dayjs format 문자열 외에 함수도 받아요. 함수는 날짜를 YYYY-MM-DD 문자열로(시간을 포함하는 컴포넌트는 YYYY-MM-DD HH:mm:ss) 받아 표시할 라벨을 반환해요. dayjs 대신 Intl.DateTimeFormat으로 날짜를 서식 지정하는 데 사용해요. 이렇게 하면 애플리케이션이 지원하는 모든 언어에 대해 dayjs/locale/* 모듈을 임포트할 필요가 없어요.

import { DatePickerInput, DatesProvider } from '@mantine/dates';

const locale = 'de';

// 'YYYY-MM-DD'는 Date 생성자에서 UTC로 파싱되므로,
// 로컬 시간대로 파싱하려면 시간 부분을 추가해요
const toDate = (value: string) => new Date(`${value}T00:00:00`);

function Demo() {
  return (
    <DatePickerInput
      valueFormat={(date) =>
        typeof date === 'string'
          ? new Intl.DateTimeFormat(locale, { dateStyle: 'long' }).format(toDate(date))
          : ''
      }
      monthLabelFormat={(date) =>
        new Intl.DateTimeFormat(locale, { month: 'long', year: 'numeric' }).format(toDate(date))
      }
      weekdayFormat={(date) =>
        new Intl.DateTimeFormat(locale, { weekday: 'short' }).format(toDate(date))
      }
      monthsListFormat={(date) =>
        new Intl.DateTimeFormat(locale, { month: 'short' }).format(toDate(date))
      }
      yearsListFormat={(date) =>
        new Intl.DateTimeFormat(locale, { year: 'numeric' }).format(toDate(date))
      }
    />
  );
}

함수를 받는 props:

DateInput.valueFormat은 사용자 입력을 파싱하는 데에도 사용된다는 점에 주의해요. 함수로 설정하면 컴포넌트는 임의의 형식을 더 이상 파싱할 수 없어요. 입력된 값을 처리하려면 dateParser prop을 설정해요.

모든 인스턴스에 포매터를 적용하려면 사용할 때마다 설정하는 대신 theme.components에서 정의해요.

import { createTheme, MantineProvider } from '@mantine/core';
import { DateFormatter } from '@mantine/dates';

const valueFormatter: DateFormatter = ({ date, locale }) =>
  typeof date === 'string'
    ? new Intl.DateTimeFormat(locale, { dateStyle: 'long' }).format(new Date(`${date}T00:00:00`))
    : '';

const theme = createTheme({
  components: {
    DatePickerInput: {
      defaultProps: { valueFormatter },
    },
  },
});

포매터는 dayjs 의존성을 제거하지 않아요. dayjs는 여전히 내부적으로 날짜 파싱과 연산에 사용돼요. 포매터가 제거하는 것은 지원하는 언어별로 dayjs locale 모듈을 임포트해야 하는 필요성이에요.

커스텀 파싱 형식 (Custom parse format)

DateInput 같은 일부 컴포넌트는 custom parse format dayjs 플러그인이 필요해요. 플러그인이 필요한 컴포넌트를 사용하기 전에 dayjs를 이 플러그인으로 확장해야 해요. 이는 보통 애플리케이션 루트 파일에서 한 번만 하면 되므로 매번 할 필요는 없어요.

import dayjs from 'dayjs';
import customParseFormat from 'dayjs/plugin/customParseFormat';

dayjs.extend(customParseFormat);

로컬라이제이션과 서버 컴포넌트 (Localization and server components)

로컬라이제이션을 추가하려면 애플리케이션에서 import 'dayjs/locale/x';를 임포트하고(x는 locale 이름) DatesProvider나 개별 컴포넌트에 locale을 설정해야 해요.

DatesProvider에 locale을 설정하는 예시:

import 'dayjs/locale/ru';

import { DatesProvider } from '@mantine/dates';

function Demo() {
  return (
    <DatesProvider settings={{ locale: 'ru' }}>
      {/* Your app */}
    </DatesProvider>
  );
}

위 코드는 Next.js app router를 제외한 모든 환경에서 동작해요. Next.js app router를 사용한다면 dayjs/locale/x를 임포트하는 파일 상단에 'use client';를 추가해야 해요. locale 데이터는 클라이언트와 서버 모두에 필요해요.

'use client';

import 'dayjs/locale/ru';

import { DatesProvider } from '@mantine/dates';

더 알아보기 (Learn more)

• Mantine extensions
• DatePicker
• DateInput