# 시간대 구성

## Content

이벤트를 특정 IANA 시간대에 맞춰 표시하거나 편집해야 한다면 `timeZone`을 사용합니다. 이벤트 데이터와 스케줄러의 표시 방식은 일관된 시간대 처리 방식을 따르도록 구성하세요.

## 권장 저장 방식

* 서버에는 UTC 기준의 절대 시각을 저장합니다.
* 표시 및 편집에 사용할 시간대를 스케줄러에 설정합니다.
* 사용자가 입력한 현지 시각은 저장하기 전에 명시적으로 변환합니다.

하나의 필드에 현지 시각(wall-clock value)과 UTC 시각을 혼용해 저장하지 마세요.

## 스케줄러 시간대 설정

```ts
const scheduler = new wjScheduler.FlexScheduler('#scheduler', {
  itemsSource,
  displayDate: new Date('2026-05-06T01:00:00Z'),
  timeZone: 'Asia/Shanghai',
});
```

`timeZone`에는 `Asia/Shanghai`, `America/Los_Angeles`, `Europe/London`과 같이 브라우저의 `Intl.DateTimeFormat`에서 지원하는 시간대 식별자를 지정합니다. 기본값은 `null`이며, 이 경우 브라우저의 로컬 시간대를 사용합니다. 지원되는 식별자는 브라우저와 ICU 데이터에 따라 다르며, 유효하지 않은 식별자는 적용되지 않습니다. 가능하면 데이터를 불러오기 전에 시간대를 설정하세요.

## JavaScript의 Date 이해하기

JavaScript의 `Date`는 UTC 타임라인상의 특정 시점을 나타냅니다. 생성하거나 표시할 때 사용한 시간대 정보는 자체적으로 저장하지 않습니다. `scheduler.timeZone`을 변경하면 동일한 `Date` 값이 표시되고 해석되는 방식은 달라지지만, `itemsSource`의 `start` 또는 `end` 값 자체는 변경되지 않습니다.
이 설정은 이벤트 표시, `displayDate`, 표시 범위, 탐색, 선택, 생성, 편집, 이동 및 크기 조정에 영향을 줍니다. 서버에는 모호하지 않은 시각이나 오프셋을 포함한 시각을 저장하고, `Date` 값을 생성할 때는 일관된 변환 정책을 적용하세요.

## 시간대 변경 시 기존 이벤트 처리

기존 이벤트는 다시 정규화되지 않으며, 변경된 시간대에 맞춰 표시됩니다. 원본 `Date` 값은 그대로 유지되므로 시간대를 이전 설정으로 되돌리면 원래 표시가 복원됩니다.
예를 들어 `2026-03-29T00:00:00Z`부터 `2026-03-29T01:00:00Z`까지 저장된 이벤트는 상하이 시간대에서 `08:00-09:00`으로 표시됩니다. 반면 런던에서는 서머타임 전환으로 인해 `00:00-02:00`으로 표시됩니다. 실제 경과 시간은 여전히 1시간입니다.

## 서머타임 처리

서머타임 전환은 현지 시각을 입력할 때 두 가지 특수한 상황을 만듭니다. 스케줄러는 편집기나 선택, 드래그, 이동, 크기 조정을 통해 입력된 시각을 이벤트의 `Date`로 변환할 때 이러한 상황을 처리합니다. API를 통해 전달된 이벤트의 `Date`는 이미 절대 시각을 나타냅니다.

### 봄철 전환: 존재하지 않는 시간 구간

시계가 앞으로 이동하면 일부 현지 시각은 존재하지 않습니다. 예를 들어 런던에서는 2026년 3월 29일 `01:00-02:00` 구간이 생략됩니다.
이 구간에 새 시간을 입력하거나 기존 시간을 편집하면 스케줄러는 생략된 시간만큼 시각을 앞당겨 조정합니다. 이로 인해 종료 시각이 시작 시각과 같거나 더 이르게 되면, 종료 시각을 생략된 시간만큼 뒤로 이동시킵니다. 예를 들어 입력한 `00:30-01:00`은 유효한 시간 구간을 유지하기 위해 `00:30-02:00`으로 변환될 수 있습니다.

![봄철전환](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/8ecc18d2-feec-4d15-bd72-3d98a7b4cefa/8-1-20261019.d236b9.png)

### 가을철 전환: 중복되는 시간 구간

시계가 뒤로 이동하면 일부 현지 시각이 두 번 발생합니다. 런던에서는 2026년 10월 25일 `01:00-02:00` 구간이 서머타임과 표준시 기준으로 각각 한 번씩 나타납니다.
새 시간을 입력하거나 기존 시간을 편집하면 스케줄러는 시작 시각에 첫 번째 발생 시각을 사용합니다. 종료 시각에는 변환된 시작 시각보다 뒤에 있는 첫 번째 종료 시각을 사용합니다. 기존 시작 또는 종료 값이 변경되지 않았다면 원래의 절대 시각을 유지하므로 기존 발생 시각도 그대로 보존됩니다.
중복되는 시간 구간을 가로지르는 이벤트는 화면에 `01:00-02:00`으로 표시되더라도 실제 지속 시간은 2시간일 수 있습니다. 다른 시간대로 변경해 표시하더라도 실제 경과 시간은 유지됩니다.

![가을철전환](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/8ecc18d2-feec-4d15-bd72-3d98a7b4cefa/8-2-20261019.fab28c.png)

## 고정 시간 축 동작

시간 기반 뷰는 `00:00`부터 `24:00`까지 고정된 시간 축을 사용합니다. 존재하지 않는 시간 구간도 축에서 제거되지 않으며, 중복되는 시간 구간도 두 번 표시되지 않습니다. 이러한 구간에서도 사용자는 이벤트를 선택하고 생성하거나 편집할 수 있으며, 이동 및 크기 조정도 가능합니다. 따라서 서머타임 전환 구간을 포함하는 이벤트는 시간 축에서 실제 경과 시간보다 길거나 짧게 표시될 수 있지만, 저장된 절대 시각은 변경되지 않습니다.
리소스 일간 뷰를 포함한 단일 날짜의 세로 시간 기반 뷰에서는 서머타임의 영향을 받는 행 헤더에 DST 표시기가 나타납니다. 여러 날짜를 표시하는 뷰와 주간 뷰, 타임라인 뷰에는 이 표시기가 나타나지 않습니다. 이 표시기는 정보 제공용이며 해당 시간 슬롯을 비활성화하지 않습니다. 또한 선택, 생성, 편집, 드래그, 이동 및 크기 조정을 제한하지 않습니다.

## 애플리케이션 입력 검증

사용자가 현지 시각을 입력하는 경우, 구성된 시간대를 기준으로 값을 검증하고 존재하지 않거나 모호한 시각을 어떻게 처리할지 애플리케이션에서 정의하세요. 명시적인 변환 없이 하나의 컬렉션에 현지 시각과 UTC 기준의 절대 시각을 혼합해 저장하지 마세요. 저장된 일정에 대한 최종 검증은 서버에서 수행해야 합니다.