[FullCalendar] 풀캘린더(FullCalendar) 속성 - 1, 기본 설정 (General Settings)

자바스크립트 기반의 오픈소스 FullCalendar

 

 

 

 

 

풀캘린더(FullCalendar) 속성 - 1

 

 

 

 

 

---

FullCalendar JS를 활용하다 보면 굉장히 다양한 속성과 이벤트를 볼 수 있다. 여러 속성들이 어떤 특징들을 가지고 있는지, 풀캘린더가 가지고 있는 이벤트에는 어떤 것들이 있으며 해당 이벤트는 어떤 동작들을 포함하고 있는지 등등에 대해서 잘 모를 때가 많다. FullCalendar JS 공식 홈페이지에서 제공하는 Documents 파일을 보긴 하지만 Docs 문서들을 확인하는 게 아직 익숙지 않은 사람은 문서 보는 방법조차 어려울 수 있다. 그래서 FullCalendar JS에서 사용할 수 있는 속성들을 하나식 살펴보고자 한다. 물론 100% 모든 속성들을 전부 보면 좋겠지만, 가장 중요한 속성들 위주로 확인해 보고 그 외에 속성들은 직접 Documents를 확인해 보길 바란다.

 

var calendarEl = document.getElementById('calendar');
var calendar = new FullCalendar.Calendar(calendarEl, {
    // 여러 속성들
});
calendar.render();

 

위 코드블록에서 설명하듯이, Calendar 객체를 만들기 위해서 설정하기 위한 여러 속성들이 존재합니다. 각 속성들은 default값이 존재하기도 또는 존재하지 않기도 하는데 해당 값들에 따라서 Calendar 객체가 다양하게 만들어질 수 있다. 여러 속성들은 '// 여러 속성들'이라고 주석 표시해둔 위치에 들어가는데 가용할 수 있는 속성들 중 Demo에서 제공하고 있는 속성들 그리고 그 외 다양한 속성들을 확인해 보자.

 

 

 

 

 

📅 1. 기본 설정 (General Settings)

---

 

 

 

 

 

initialView

' 캘린더가 load 될 때, 초기 보기 설정 '

---

캘린더가 load 될 때, 초기 보기 설정을 initialView 속성을 통해서 설정할 수 있다. 초기 보기 설정은 설정하지 않는 경우에 defualt값인 'dayGridMonth'로 설정된다. 보기 설정에는 다양한 값이 존재하는데, 'dayGridYear', 'dayGridMonth', 'dayGridWeek', 'dayGridDay', 'dayGrid', 'timeGridWeek', 'timeGridDay', 'timeGrid', 'listYear', 'listMonth', 'listWeek', 'listDay', 'list'가 사용될 수 있다. 그 외에 timeline 종류 또는 resource 종류는 기본 번들에서는 사용할 수 없다. (사용 시, 스크립트 에러발생)

 

기본 번들에서 사용 가능한 속성 값

종류 1) 'dayGridYear', 'dayGridMonth', 'dayGridWeek', 'dayGridDay', 'dayGrid'

종류 2) 'timeGridWeek', 'timeGridDay', 'timeGrid'

종류 3) 'listYear', 'listMonth', 'listWeek', 'listDay', 'list'

 

document.addEventListener('DOMContentLoaded', function() {
    var calendarEl = document.getElementById('calendar');
    var calendar = new FullCalendar.Calendar(calendarEl, {
        initialView : 'dayGridMonth',
    });
    calendar.render();
});

 

initialView 속성을 이용한 FullCalendar 만들기

 

총 이미지 3장 중, 왼쪽 상단 이미지는 ' dayGridYear ' 로 설정한 이미지이고, 오른쪽 상단 이미지는 ' dayGridMonth ' 로 설정한 이미지이고, 하단 이미지는 ' dayGridWeek ' 로 설장한 이미지이다. 각 속성에 다른 속성 값들을 넣을 때마다 각각 초기 설정 화면이 달라지는 걸 확인할 수 있다. dayGridYear는 현재 날짜를 기준으로 설명하자면 2024년도 1월부터 12월까지의 달력이 한꺼번에 출력된다. dayGridMonth는 2024년도 현재 달을 기준으로 1달씩 출력된다. dayGridWeek는 2024년도 해당 달의 주 단위로 출력된다. 

 

 

 

 

 

initialDate

' 캘린더가 load 될 때, 초기 날짜 설정 '

---

캘린더가 load 될 때, 초기 날짜 설정을 initialDate 속성을 통해서 설정할 수 있다. 초기 날짜 설정은 설정하지 않는 경우엔, default 값에 해당하는 현재 날짜가 설정된다. 날짜 데이터는 ISO8601 인코딩으로 날짜 문자열을 포함하여 Date로 구문분석이 가능하도록 되어 있다. 문자열에 해당하는 날짜 데이터를 해당 속성 값으로 입력만 해주면 된다.

 

ISO8601 문자열로 출력하기

- 2024-06-17 

- 2024-06-17T12:30:00 

- 2024-06-17T12:30:00-14:00

 

밀리초 시간으로 출력하기

- 1537302134028     // Tue Sep 18 2018 16:22:14 GMT-0400

 

기본 Javascript 날짜로 출력하기

- new Date(2024,6,10)

- new Date(Date.UTC(2024,6,10))

 

document.addEventListener('DOMContentLoaded', function() {
    var calendarEl = document.getElementById('calendar');
    var calendar = new FullCalendar.Calendar(calendarEl, {
        timeZone : 'local',
        initialDate : '2024-08-01'
        // initialDate : '2024-08-01'
        // initialDate : '2024-08-01'
        // initialDate : 1537302134028 // Tue Sep 18 2018 16:22:14
        // initialDate : new Date(2019, 10, 1)
        // initialDate : new Date(Date.UTC(2024, 10, 10))
    });
    calendar.render();
});

 

ISO8601 문자열로 출력 시, '2024-06-17'과 같은 문자열은 허용되지만 '20240617'과 같은 문자열은 허용되지 않는다. 기본적인 timeZone은 사용자가 사용 중인 운영체제 설정에 따라 결정되는 기본 시간대인 'local'로 설정된다. 이는 '현지' 시간대로 간주된다. 

 

 

 

 

 

locale

' 언어 및 지역화 설정 '

---

locale 속성은 FullCalendar의 언어 및 지역화 설정을 변경하는데 사용합니다. 해당 속성을 통해 날짜 형식, 요일 이름, 버튼 텍스트 등을 사용자의 언어에 맞게 표시할 수 있습니다.

 

document.addEventListener('DOMContentLoaded', function() {
    var calendarEl = document.getElementById('calendar');
    var calendar = new FullCalendar.Calendar(calendarEl, {
        locale: 'ko',  // 한국어 설정
    });
    calendar.render();
});

 

대표적인 locale 코드로는 en(영어:기본값), ko(한국어), fr(프랑스어), ja(일본어), zh-cn(중국어:간체), de(독일어), es(스페인어) 등이 있습니다. FullCalendar는 Moment.js의 Locale을 기반으로 하기 떄문에 대부분의 Locale은 기본적으로 포함되어 있습니다. 하지만, 전체적인 Locale을 사용해야 한다면 아래 cdn을 설정합니다.

<script src="https://cdn.jsdelivr.net/npm/fullcalendar@6.1.8/locales-all.min.js"></script>

 

위 스크립트를 설정한다면 전체적인 Locale을 사용할 수 있습니다.

 

 

주요 Locale 코드 예시

영어 (기본)	en	독일어	de
한국어	ko	프랑스어	fr
일본어	ja	스페인어	es
중국어 (간체)	zh-cn	이탈리아어	it
중국어 (번체)	zh-tw	포르투갈어	pt
러시아어	ru	네덜란드어	nl
아랍어	ar	히브리어	he
태국어	th	터키어	tr
베트남어	vi	폴란드어	pl
인도네시아어	id	스웨덴어	sv
핀란드어	fi	체코어	cs
헝가리어	hu	크로아티아어	hr
우크라이나어	uk	슬로바키아어	sk
루마니아어	ro	불가리아어	bg
덴마크어	da	리투아니아어	lt
노르웨이어	no 또는 nb	에스토니아어	et
카탈루냐어	ca	슬로베니아어	sl
불가리아어	bg	라트비아어	lv
말레이어	ms	세르비아어	sr
갈리시아어	gl	바스크어	eu

 

 

 

 

 

timeZone

' 시간대 설정 '

---

timeZone 속성은 캘린더의 시간대를 설정하는데 사용됩니다. 해당 속성을 통해 이벤트 시간 및 날짜가 특정 시간대에 맞게 표시되도록 할 수 있습니다. 기본적으로는 브라우저의 로컬 시간대를 사용하지만, 필요에 따라 UTC나 특정 시간대로 변경할 수 있습니다.

 

document.addEventListener('DOMContentLoaded', function() {
    var calendarEl = document.getElementById('calendar');
    var calendar = new FullCalendar.Calendar(calendarEl, {
        timeZone: 'local', // 기본값: 브라우저의 로컬 시간대 사용
    });
    calendar.render();
});

 

timeZone 속성은 대표적으로 3가지 방식으로 설정할 수 있습니다.

1. local : 사용자의 브라우저 시간대에 맞게 표시 (기본값)
2. UTC : 세계 협정시(Universal Time Coordinated)로 표시
3. IANA 시간대 : 'Asia/Seoul', 'America/New_York', 'Europe/London' 등으로 지정 가능

 

1. locale 사용법 (기본값)

timeZone : 'local'

 

모든 브라우저에는 기본 시간대가 있으며, 이는 일반적으로 사용자의 운영 체제 설정에 따라 결정됩니다. 이는 로컬 시간대로 간주되고 캘린더 사용자마다 다르며, 거주지 또는 컴퓨터 구성 방식에 따라 달라집니다. 

이벤트 날짜가 UTC를 기준으로 정의된 경우, 밀리초 시간 또는 UTC 오프셋이 있는 ISO8601 문자열을 통해 날짜가 사용자의 로컬 시간대로 표시되도록 적절히 변경됩니다. 날짜가 UTC 오프셋이 없는 ISO8601 문자열로 제공된 경우 로컬인 것처럼 구문 분석됩니다.

 

2. UTC 사용법

timeZone : 'UTC'

 

로컬 시간대는 브라우저마다 다르지만 UTC 시간대는 모든 브라우저에서 동일하도록 보장됩니다. 또한 일광 절약 시간제를 경험하지 않습니다. UTC 시간대는 이런 방식으로 설계되었으며 다른 시간대가 상대적으로 정의하는 시간대 역할을 합니다. 

이벤트 날짜가 UTC 오프셋이 있는 ISO8601 문자열로 정의된 경우 날짜가 00:00 오프셋으로 표시되도록 적절히 이동합니다. 날짜가 시간대 오프셋 없이 ISO8601 문자열로 제공된 경우 UTC인 것처럼 구문 분석됩니다. 그리고 API에서 방출된 날짜를 사용 시, Date 객체의 메서드를 통해 UTC값에 액세스하고 싶은 경우가 있습니다. .getURCMonth(), .getUTCHours(), .toUTCString() 메소드를 통해 설정할 수 있습니다.

timeZone 속성을 'UTC'로 설정함으로 사용자의 로컬 시간대와 상관없이 모든 이벤트가 브라우저에서 일관되게 표시되기를 원한다면 UTC가 적절한 설정일것입니다.

 

즉, 쉽게 말해서 timeZone 속성을 'UTC'로 설정하면 모든 날짜와 시간이 협정 세계시(UTC) 기준으로 표시되고 처리됩니다. 이는 시간대 변환 없이 모든 이벤트가 동일한 시간 기준으로 유지되므로 글로벌 사용자, 서버-클라이언트 동기화, 국제 일정 관리에 유용할 것입니다.

var calendar = new FullCalendar.Calendar(calendarEl, {
  initialView: 'timeGridWeek',
  timeZone: 'UTC',  // 시간대를 UTC로 설정
  events: [
    { title: 'UTC 회의', start: '2025-02-07T12:00:00Z' }  // UTC 기준
  ]
});
calendar.render();

 

'UTC' 설정 소스를 보는바와 같이, 브라우저의 로컬 시간에 관계없이 UTC 시간대로 표시되고 시간 값 뒤에는 'Z'가 붙는데 이는 'UTC' 시간대를 의미합니다. (2025-02-07T12:00:00Z → UTC 12시)

 

 

 

local과 UTC의 차이점

시간 기준	브라우저(사용자) 로컬 시간대	UTC(세계 표준 시간) 기준
시간 표시 방식	로컬 시간으로 자동 변환	변환 없이 UTC 그대로 표시
글로벌 사용자 대응	시간대 차이로 혼란 가능	모든 사용자에게 동일한 시간으로 표시
서버와의 시간 동기화	서버-클라이언트 간 시간대 변환 필요	서버의 UTC 시간과 바로 일치

 

3. IANA 시간대 사용법

timeZone : 'Asia/Seoul'

 

명명된 시간대는 'America/New_York', 'Asia/Seoul' 과 같은 문자열로 지정된 세계의 특정 지역입니다. UTC 시간대와 마찬가지로 모호함이 없기 때문에 모든 브라우저에서 일관되게 표시됩니다. 그러나 모든 브라우저가 로컬 또는 UTC와 같은 방식으로 명명된 시단대를 기본적으로 지원하지는 않습니다. 더 구체적으로 네이티브 Date 객체는 시간대 오프셋을 계산하는 방법을 모릅니다. 따라서 명명된 시간대를 사용하려는 경우 FullCalendar가 플러그인 형태로 제공되는 어떤 시간대 구현을 사용해야 하는지 결정해야 합니다.

 

 

 

• '대륙/도시'의 형태를 가지며 'Asia/Seoul', 'America/Los_Angeles' 등 처럼 표기할 수 있다.
• 서머타임(DST) 자동 처리 : 해당 시간대의 일광 절약 시간제(서머타임)가 자동 적용된다.
• 브라우저의 Local 시간대가 달라진다 하더라도 시간대가 달리지지 않고 IANA로 설정된 시간대에 맞춰진다.

 

UTC, local, IANA 비교

기준 시간대	브라우저 로컬 시간대	UTC (세계 표준 시간)	특정 도시/국가 시간대 기준
시간대 자동 변환	브라우저 시간에 따라 변환	UTC로 고정	해당 지역 시간대에 따라 표시
서머타임 처리	브라우저가 자동 처리	없음	자동 적용 (DST 반영)
글로벌 일정 관리	❌ 시간대 혼동 가능	⚠️ UTC 이해 필요	✅ 지역 시간에 최적화

 

 

IANA 시간대 표기 목록

---

1. 아시아 (Asia)

한국	Asia/Seoul	한국 표준시 (KST)
일본	Asia/Tokyo	일본 표준시 (JST)
중국	Asia/Shanghai	중국 표준시 (CST)
홍콩	Asia/Hong_Kong	홍콩 표준시 (HKT)
대만	Asia/Taipei	대만 표준시 (CST)
인도	Asia/Kolkata	인도 표준시 (IST)
싱가포르	Asia/Singapore	싱가포르 표준시 (SGT)
태국	Asia/Bangkok	태국 표준시 (ICT)
인도네시아 (자카르타)	Asia/Jakarta	서부 인도네시아 시간 (WIB)
아랍에미리트	Asia/Dubai	걸프 표준시 (GST)

 

 

2. 유럽 (Europe)

영국	Europe/London	그리니치 표준시 (GMT) / 서머타임(BST)
독일	Europe/Berlin	중앙 유럽 시간 (CET) / 서머타임(CEST)
프랑스	Europe/Paris	중앙 유럽 시간 (CET)
이탈리아	Europe/Rome	중앙 유럽 시간 (CET)
스페인	Europe/Madrid	중앙 유럽 시간 (CET)
러시아 (모스크바)	Europe/Moscow	모스크바 표준시 (MSK)
핀란드	Europe/Helsinki	동유럽 시간 (EET)
터키	Europe/Istanbul	터키 표준시 (TRT)
폴란드	Europe/Warsaw	중앙 유럽 시간 (CET)
네덜란드	Europe/Amsterdam	중앙 유럽 시간 (CET)

 

3. 아메리카 (America)

미국 (뉴욕)	America/New_York	동부 표준시 (EST) / 서머타임(EDT)
미국 (시카고)	America/Chicago	중부 표준시 (CST) / 서머타임(CDT)
미국 (덴버)	America/Denver	산지 표준시 (MST) / 서머타임(MDT)
미국 (로스앤젤레스)	America/Los_Angeles	태평양 표준시 (PST) / 서머타임(PDT)
캐나다 (토론토)	America/Toronto	동부 표준시 (EST)
브라질 (상파울루)	America/Sao_Paulo	브라질 표준시 (BRT)
아르헨티나 (부에노스아이레스)	America/Argentina/Buenos_Aires	아르헨티나 시간 (ART)
칠레 (산티아고)	America/Santiago	칠레 표준시 (CLT)
멕시코 (멕시코시티)	America/Mexico_City	중앙 표준시 (CST)
페루 (리마)	America/Lima	페루 표준시 (PET)

 

 

4. 아프리카 (Africa)

이집트 (카이로)	Africa/Cairo	동유럽 시간 (EET)
남아프리카 (요하네스버그)	Africa/Johannesburg	남아프리카 표준시 (SAST)
나이지리아 (라고스)	Africa/Lagos	서아프리카 시간 (WAT)
케냐 (나이로비)	Africa/Nairobi	동아프리카 시간 (EAT)
알제리 (알제)	Africa/Algiers	중앙 유럽 시간 (CET)
모로코 (카사블랑카)	Africa/Casablanca	서유럽 시간 (WET)
튀니지 (튀니스)	Africa/Tunis	중앙 유럽 시간 (CET)

 

5. 오세아니아 (Australia/Pacific)

호주 (시드니)	Australia/Sydney	호주 동부 표준시 (AEST) / 서머타임(AEDT)
호주 (퍼스)	Australia/Perth	호주 서부 표준시 (AWST)
뉴질랜드 (오클랜드)	Pacific/Auckland	뉴질랜드 표준시 (NZST) / 서머타임(NZDT)
피지	Pacific/Fiji	피지 표준시 (FJT)
괌	Pacific/Guam	괌 표준시 (ChST)
하와이	Pacific/Honolulu	하와이 표준시 (HST)

 

6. UTC 및 기타 (Etc)

Etc/UTC	UTC (협정 세계시)
Etc/GMT+0	GMT+0 (UTC와 동일)
Etc/GMT+9	GMT+9 (한국 시간과 유사)
Etc/GMT-5	GMT-5 (EST와 유사)

 

 

 

 

 

weekends

' 모든 달력 보기에 토요일/일요일 열을 포함할지 여부 '

---

weekends 속성은 주말(토요일과 일요일)의 표시 여부를 제어하는 boolean 속성입니다. 기본값은 true이고 false로 설정하면 주말이 캘린더에서 숨겨집니다.

 

var calendar = new FullCalendar.Calendar(calendarEl, {
  initialView: 'dayGridMonth',
  weekends: true			// 주말 활성화
  // weekends: false        // 주말 비활성화
});
calendar.render();

 

주말 표기가 사라진 풀캘린더

 

 

 

 

 

height

' 캘린더 머리글과 바닥글을 포함한 전체 달력의 높이를 설정  '

---

기본적으로 해당 옵션은 설정되지 않으며 달력의 높이는 aspectRatio에 의해 계산됩니다. 정수가 지정되면 달력의 높이는 정확히 그 픽셀 높이가 보장됩니다. 내용이 높이에 맞지 않으면 스크롤바가 나타납니다. 'auto' 로 지정된 경우 뷰의 내용은 자연스러운 높이로 가정되고 스크롤바는 사용되지 않습니다. '100%' 로 지정된 경우 달력의 높이는 부모 컨테이너 요소의 높이와 일치합니다.

 

var calendar = new FullCalendar.Calendar(calendarEl, {
  initialView: 'dayGridMonth',
  height: 'auto',		// 높이를 auto로 설정
  // height: '100%'		// 높이를 100%로 설정
  // height: 650		// 높이를 650px로 설정
});
calendar.render();

 

캘린더 높이를 200px로 설정

 

height의 설정 방법

값 유형	설명	예제
숫자 (픽셀)	고정된 픽셀 값으로 설정	height: 700 (700px)
'auto'	캘린더 내용에 따라 높이가 자동으로 조절됨	height: 'auto'
'parent'	부모 요소의 높이에 맞게 자동 조절	height: 'parent'
CSS 퍼센트	CSS로 부모 요소에 % 단위로 설정 가능	style="height: 100%;"

 

 

 

 

 

contentHeight

' 캘린더 보기 영역의 높이를 설정  '

---

contentHeight 속성은 캘린더의 본문(Content) 영역의 높이를 설정하는데 사용됩니다. 본문 영역은 이벤트가 표시되는 부분으로 헤더와 푸터는 제외됩니다. 기본적으로 해당 옵션은 설정되지 않으며 달력의 높이는 aspectRatio에 의해 계산됩니다. 정수가 지정되면 뷰의 높이는 정확히 그 픽셀 높이가 보장됩니다. 내용이 높이에 맞지 않으면 스크롤바가 나타납니다. 'auto'로 지정된 경우 뷰의 내용은 자연스러운 높이로 가정되고 스크롤바는 사용되지 않습니다.

• height → 캘린더의 전체 높이 (헤다 + 분몬 + 푸터)
• contentHeight → 본문 영역의 높이만 조절

var calendar = new FullCalendar.Calendar(calendarEl, {
  initialView: 'dayGridMonth',
  contentHeight: 'auto',		// 본문 높이를 auto로 설정
  // contentHeight: 500		// 본문 높이를 500px로 설정
});
calendar.render();

 

contentHeight 설정 예시

 

 

 

 

 

aspectRatio

' 달력의 너비 대 높이 종횡비를 설정  '

---

aspectRatio 속성은 너비 대 높이의 종횡비를 설정하는 속성으로 설정의 기본값은 '1.35' 종횡비 입니다. 달력은 사용 가능한 전체 너비를 채우는 블록 수준 요소입니다. 그러나 달력의 높이는 너비 대 높이의 비율에 따라 결정됩니다. (종횡비 숫자가 클수록 높이가 작아집니다.)

 

Aspect Ratio 공식

 

var calendar = new FullCalendar.Calendar(calendarEl, {
  initialView: 'dayGridMonth',
  aspectRatio: 1.5, // 너비:높이 비율이 1.5:1
  events: [
    { title: '팀 회의', start: '2025-02-15' },
    { title: '프로젝트 마감', start: '2025-02-20' }
  ]
});
calendar.render();

 

주요 설정 값

aspectRatio 값	설명	결과 예시
1	너비와 높이가 동일한 정사각형 비율	1:1 정사각형 형태
1.5	가로가 세로보다 1.5배 넓음	표준 와이드 화면 느낌
2	가로가 세로의 2배로 매우 넓음	넓은 화면에 적합한 레이아웃
0.75	세로가 더 길어지는 비율	높이가 강조된 레이아웃

 

 

 

 

 

FullCalendar JS를 소개하는 내용은, FullCalendar 공식 홈페이지에 내용을 적극 참고하여 작성된 글임을 명시합니다. 모든 내용은 공식 홈페이지 메인 내용 및 Documents를 기반으로 작성하였습니다.

 

 

 

 

 

@Junesker

---