636 lines
15 KiB
Markdown
636 lines
15 KiB
Markdown
# ⏰ 시계 위젯 구현 계획
|
||
|
||
## 📋 개요
|
||
|
||
대시보드에 실시간 시계 위젯을 추가하여 사용자가 현재 시간을 한눈에 확인할 수 있도록 합니다.
|
||
|
||
---
|
||
|
||
## 🎯 목표
|
||
|
||
- 실시간으로 업데이트되는 시계 위젯 구현
|
||
- 다양한 시계 스타일 제공 (아날로그/디지털)
|
||
- 여러 시간대(타임존) 지원
|
||
- 깔끔하고 직관적인 UI
|
||
|
||
---
|
||
|
||
## 📦 구현 범위
|
||
|
||
### 1. 타입 정의 (`types.ts`)
|
||
|
||
```typescript
|
||
export type ElementSubtype =
|
||
| "bar"
|
||
| "pie"
|
||
| "line"
|
||
| "area"
|
||
| "stacked-bar"
|
||
| "donut"
|
||
| "combo" // 차트
|
||
| "exchange"
|
||
| "weather"
|
||
| "clock"; // 위젯 (+ clock 추가)
|
||
|
||
// 시계 위젯 설정
|
||
export interface ClockConfig {
|
||
style: "analog" | "digital" | "both"; // 시계 스타일
|
||
timezone: string; // 타임존 (예: 'Asia/Seoul', 'America/New_York')
|
||
showDate: boolean; // 날짜 표시 여부
|
||
showSeconds: boolean; // 초 표시 여부 (디지털)
|
||
format24h: boolean; // 24시간 형식 (true) vs 12시간 형식 (false)
|
||
theme: "light" | "dark" | "blue" | "gradient"; // 테마
|
||
}
|
||
|
||
// DashboardElement에 clockConfig 추가
|
||
export interface DashboardElement {
|
||
// ... 기존 필드
|
||
clockConfig?: ClockConfig; // 시계 설정
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 사이드바에 시계 위젯 추가 (`DashboardSidebar.tsx`)
|
||
|
||
```tsx
|
||
<DraggableItem
|
||
icon="⏰"
|
||
title="시계 위젯"
|
||
type="widget"
|
||
subtype="clock"
|
||
onDragStart={handleDragStart}
|
||
className="border-l-4 border-teal-500"
|
||
/>
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 시계 위젯 컴포넌트 생성
|
||
|
||
#### 📁 파일 구조
|
||
|
||
```
|
||
frontend/components/admin/dashboard/
|
||
├── widgets/
|
||
│ ├── ClockWidget.tsx # 메인 시계 컴포넌트
|
||
│ ├── AnalogClock.tsx # 아날로그 시계
|
||
│ ├── DigitalClock.tsx # 디지털 시계
|
||
│ └── ClockConfigModal.tsx # 시계 설정 모달
|
||
```
|
||
|
||
#### 📄 `ClockWidget.tsx` - 메인 컴포넌트
|
||
|
||
**기능:**
|
||
|
||
- 현재 시간을 1초마다 업데이트
|
||
- `clockConfig`에 따라 아날로그/디지털 시계 렌더링
|
||
- 타임존 지원 (`Intl.DateTimeFormat` 또는 `date-fns-tz` 사용)
|
||
|
||
**주요 코드:**
|
||
|
||
```tsx
|
||
"use client";
|
||
import { useState, useEffect } from "react";
|
||
import { DashboardElement } from "../types";
|
||
import { AnalogClock } from "./AnalogClock";
|
||
import { DigitalClock } from "./DigitalClock";
|
||
|
||
interface ClockWidgetProps {
|
||
element: DashboardElement;
|
||
}
|
||
|
||
export function ClockWidget({ element }: ClockWidgetProps) {
|
||
const [currentTime, setCurrentTime] = useState(new Date());
|
||
const config = element.clockConfig || {
|
||
style: "digital",
|
||
timezone: "Asia/Seoul",
|
||
showDate: true,
|
||
showSeconds: true,
|
||
format24h: true,
|
||
theme: "light",
|
||
};
|
||
|
||
useEffect(() => {
|
||
const timer = setInterval(() => {
|
||
setCurrentTime(new Date());
|
||
}, 1000);
|
||
|
||
return () => clearInterval(timer);
|
||
}, []);
|
||
|
||
return (
|
||
<div className="flex h-full flex-col items-center justify-center">
|
||
{(config.style === "analog" || config.style === "both") && (
|
||
<AnalogClock time={currentTime} theme={config.theme} />
|
||
)}
|
||
|
||
{(config.style === "digital" || config.style === "both") && (
|
||
<DigitalClock
|
||
time={currentTime}
|
||
timezone={config.timezone}
|
||
showDate={config.showDate}
|
||
showSeconds={config.showSeconds}
|
||
format24h={config.format24h}
|
||
theme={config.theme}
|
||
/>
|
||
)}
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 📄 `DigitalClock.tsx` - 디지털 시계
|
||
|
||
**기능:**
|
||
|
||
- 시간을 디지털 형식으로 표시
|
||
- 날짜 표시 옵션
|
||
- 12/24시간 형식 지원
|
||
- 초 표시 옵션
|
||
|
||
**UI 예시:**
|
||
|
||
```
|
||
┌─────────────────────┐
|
||
│ 2025년 1월 15일 │
|
||
│ │
|
||
│ 14:30:45 │
|
||
│ │
|
||
│ 서울 (KST) │
|
||
└─────────────────────┘
|
||
```
|
||
|
||
**주요 코드:**
|
||
|
||
```tsx
|
||
interface DigitalClockProps {
|
||
time: Date;
|
||
timezone: string;
|
||
showDate: boolean;
|
||
showSeconds: boolean;
|
||
format24h: boolean;
|
||
theme: string;
|
||
}
|
||
|
||
export function DigitalClock({ time, timezone, showDate, showSeconds, format24h, theme }: DigitalClockProps) {
|
||
// Intl.DateTimeFormat으로 타임존 처리
|
||
const timeString = new Intl.DateTimeFormat("ko-KR", {
|
||
timeZone: timezone,
|
||
hour: "2-digit",
|
||
minute: "2-digit",
|
||
second: showSeconds ? "2-digit" : undefined,
|
||
hour12: !format24h,
|
||
}).format(time);
|
||
|
||
const dateString = showDate
|
||
? new Intl.DateTimeFormat("ko-KR", {
|
||
timeZone: timezone,
|
||
year: "numeric",
|
||
month: "long",
|
||
day: "numeric",
|
||
weekday: "long",
|
||
}).format(time)
|
||
: null;
|
||
|
||
return (
|
||
<div className={`text-center ${getThemeClass(theme)}`}>
|
||
{showDate && <div className="mb-2 text-sm opacity-80">{dateString}</div>}
|
||
<div className="text-4xl font-bold tabular-nums">{timeString}</div>
|
||
<div className="mt-2 text-xs opacity-60">{getTimezoneLabel(timezone)}</div>
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 📄 `AnalogClock.tsx` - 아날로그 시계
|
||
|
||
**기능:**
|
||
|
||
- SVG로 아날로그 시계 그리기
|
||
- 시침, 분침, 초침 애니메이션
|
||
- 숫자/눈금 표시
|
||
|
||
**UI 예시:**
|
||
|
||
```
|
||
12
|
||
11 1
|
||
10 2
|
||
9 3
|
||
8 4
|
||
7 5
|
||
6
|
||
```
|
||
|
||
**주요 코드:**
|
||
|
||
```tsx
|
||
interface AnalogClockProps {
|
||
time: Date;
|
||
theme: string;
|
||
}
|
||
|
||
export function AnalogClock({ time, theme }: AnalogClockProps) {
|
||
const hours = time.getHours() % 12;
|
||
const minutes = time.getMinutes();
|
||
const seconds = time.getSeconds();
|
||
|
||
// 각도 계산
|
||
const secondAngle = seconds * 6 - 90; // 6도씩 회전
|
||
const minuteAngle = minutes * 6 + seconds * 0.1 - 90;
|
||
const hourAngle = hours * 30 + minutes * 0.5 - 90;
|
||
|
||
return (
|
||
<svg viewBox="0 0 200 200" className="w-full max-w-[200px]">
|
||
{/* 시계판 */}
|
||
<circle cx="100" cy="100" r="95" fill="white" stroke="black" strokeWidth="2" />
|
||
|
||
{/* 숫자 표시 */}
|
||
{[...Array(12)].map((_, i) => {
|
||
const angle = (i * 30 - 90) * (Math.PI / 180);
|
||
const x = 100 + 75 * Math.cos(angle);
|
||
const y = 100 + 75 * Math.sin(angle);
|
||
return (
|
||
<text key={i} x={x} y={y} textAnchor="middle" dy="5" fontSize="14">
|
||
{i === 0 ? 12 : i}
|
||
</text>
|
||
);
|
||
})}
|
||
|
||
{/* 시침 */}
|
||
<line
|
||
x1="100"
|
||
y1="100"
|
||
x2={100 + 40 * Math.cos((hourAngle * Math.PI) / 180)}
|
||
y2={100 + 40 * Math.sin((hourAngle * Math.PI) / 180)}
|
||
stroke="black"
|
||
strokeWidth="6"
|
||
strokeLinecap="round"
|
||
/>
|
||
|
||
{/* 분침 */}
|
||
<line
|
||
x1="100"
|
||
y1="100"
|
||
x2={100 + 60 * Math.cos((minuteAngle * Math.PI) / 180)}
|
||
y2={100 + 60 * Math.sin((minuteAngle * Math.PI) / 180)}
|
||
stroke="black"
|
||
strokeWidth="4"
|
||
strokeLinecap="round"
|
||
/>
|
||
|
||
{/* 초침 */}
|
||
<line
|
||
x1="100"
|
||
y1="100"
|
||
x2={100 + 70 * Math.cos((secondAngle * Math.PI) / 180)}
|
||
y2={100 + 70 * Math.sin((secondAngle * Math.PI) / 180)}
|
||
stroke="red"
|
||
strokeWidth="2"
|
||
strokeLinecap="round"
|
||
/>
|
||
|
||
{/* 중심점 */}
|
||
<circle cx="100" cy="100" r="5" fill="black" />
|
||
</svg>
|
||
);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 📄 `ClockConfigModal.tsx` - 설정 모달
|
||
|
||
**설정 항목:**
|
||
|
||
1. **시계 스타일**
|
||
- 아날로그
|
||
- 디지털
|
||
- 둘 다
|
||
|
||
2. **타임존 선택**
|
||
- 서울 (Asia/Seoul)
|
||
- 뉴욕 (America/New_York)
|
||
- 런던 (Europe/London)
|
||
- 도쿄 (Asia/Tokyo)
|
||
- 기타...
|
||
|
||
3. **디지털 시계 옵션**
|
||
- 날짜 표시
|
||
- 초 표시
|
||
- 24시간 형식 / 12시간 형식
|
||
|
||
4. **테마**
|
||
- Light
|
||
- Dark
|
||
- Blue
|
||
- Gradient
|
||
|
||
---
|
||
|
||
### 4. 기존 컴포넌트 수정
|
||
|
||
#### 📄 `CanvasElement.tsx`
|
||
|
||
시계 위젯을 렌더링하도록 수정:
|
||
|
||
```tsx
|
||
import { ClockWidget } from "./widgets/ClockWidget";
|
||
|
||
// 렌더링 부분
|
||
{
|
||
element.type === "widget" && element.subtype === "clock" && <ClockWidget element={element} />;
|
||
}
|
||
```
|
||
|
||
#### 📄 `DashboardDesigner.tsx`
|
||
|
||
시계 위젯 기본 설정 추가:
|
||
|
||
```tsx
|
||
function getElementContent(type: ElementType, subtype: ElementSubtype): string {
|
||
// ...
|
||
if (type === "widget") {
|
||
if (subtype === "clock") return "clock";
|
||
// ...
|
||
}
|
||
}
|
||
|
||
function getElementTitle(type: ElementType, subtype: ElementSubtype): string {
|
||
// ...
|
||
if (type === "widget") {
|
||
if (subtype === "clock") return "⏰ 시계";
|
||
// ...
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🎨 디자인 가이드
|
||
|
||
### 테마별 색상
|
||
|
||
```typescript
|
||
const themes = {
|
||
light: {
|
||
background: "bg-white",
|
||
text: "text-gray-900",
|
||
border: "border-gray-200",
|
||
},
|
||
dark: {
|
||
background: "bg-gray-900",
|
||
text: "text-white",
|
||
border: "border-gray-700",
|
||
},
|
||
blue: {
|
||
background: "bg-gradient-to-br from-blue-400 to-blue-600",
|
||
text: "text-white",
|
||
border: "border-blue-500",
|
||
},
|
||
gradient: {
|
||
background: "bg-gradient-to-br from-purple-400 via-pink-500 to-red-500",
|
||
text: "text-white",
|
||
border: "border-pink-500",
|
||
},
|
||
};
|
||
```
|
||
|
||
### 크기 가이드
|
||
|
||
- **최소 크기**: 2×2 셀 (디지털만)
|
||
- **권장 크기**: 3×3 셀 (아날로그 + 디지털)
|
||
- **최대 크기**: 4×4 셀
|
||
|
||
---
|
||
|
||
## 🔧 기술 스택
|
||
|
||
### 사용 라이브러리
|
||
|
||
**Option 1: 순수 JavaScript (권장)**
|
||
|
||
- `Date` 객체
|
||
- `Intl.DateTimeFormat` - 타임존 처리
|
||
- `setInterval` - 1초마다 업데이트
|
||
|
||
**Option 2: 외부 라이브러리**
|
||
|
||
- `date-fns` + `date-fns-tz` - 날짜/시간 처리
|
||
- `moment-timezone` - 타임존 처리 (무겁지만 강력)
|
||
|
||
**추천: Option 1 (순수 JavaScript)**
|
||
|
||
- 외부 의존성 없음
|
||
- 가볍고 빠름
|
||
- 브라우저 네이티브 API 사용
|
||
|
||
---
|
||
|
||
## 📝 구현 순서
|
||
|
||
### Step 1: 타입 정의
|
||
|
||
- [x] `types.ts`에 `'clock'` 추가
|
||
- [x] `ClockConfig` 인터페이스 정의
|
||
- [x] `DashboardElement`에 `clockConfig` 추가
|
||
|
||
### Step 2: UI 추가
|
||
|
||
- [x] `DashboardSidebar.tsx`에 시계 위젯 아이템 추가
|
||
|
||
### Step 3: 디지털 시계 구현
|
||
|
||
- [x] `DigitalClock.tsx` 생성
|
||
- [x] 시간 포맷팅 구현
|
||
- [x] 타임존 처리 구현
|
||
- [x] 테마 스타일 적용
|
||
|
||
### Step 4: 아날로그 시계 구현
|
||
|
||
- [x] `AnalogClock.tsx` 생성
|
||
- [x] SVG 시계판 그리기
|
||
- [x] 시침/분침/초침 계산 및 렌더링
|
||
- [x] 애니메이션 적용
|
||
|
||
### Step 5: 메인 위젯 컴포넌트
|
||
|
||
- [x] `ClockWidget.tsx` 생성
|
||
- [x] 실시간 업데이트 로직 구현
|
||
- [x] 아날로그/디지털 조건부 렌더링
|
||
|
||
### Step 6: 설정 모달
|
||
|
||
- [x] `ClockConfigModal.tsx` 생성 ✨
|
||
- [x] 스타일 선택 UI (아날로그/디지털/둘다) ✨
|
||
- [x] 타임존 선택 UI (8개 주요 도시) ✨
|
||
- [x] 옵션 토글 UI (날짜/초/24시간) ✨
|
||
- [x] 테마 선택 UI (light/dark/blue/gradient) ✨
|
||
- [x] ElementConfigModal 통합 ✨
|
||
|
||
### Step 7: 통합
|
||
|
||
- [x] `CanvasElement.tsx`에 시계 위젯 렌더링 추가
|
||
- [x] `DashboardDesigner.tsx`에 기본값 추가
|
||
- [x] ClockWidget 임포트 및 조건부 렌더링 추가
|
||
|
||
### Step 8: 테스트 & 최적화
|
||
|
||
- [x] 기본 구현 완료
|
||
- [x] 린터 에러 체크 완료
|
||
- [ ] 브라우저 테스트 필요 (사용자 테스트)
|
||
- [ ] 다양한 타임존 테스트 (향후)
|
||
- [ ] 성능 최적화 (향후)
|
||
- [ ] 테마 전환 테스트 (향후)
|
||
|
||
---
|
||
|
||
## 🚀 향후 개선 사항
|
||
|
||
### 추가 기능
|
||
|
||
- [ ] **세계 시계**: 여러 타임존 동시 표시
|
||
- [ ] **알람 기능**: 특정 시간에 알림
|
||
- [ ] **타이머/스톱워치**: 시간 측정 기능
|
||
- [ ] **애니메이션**: 부드러운 시계 애니메이션
|
||
- [ ] **사운드**: 정각마다 종소리
|
||
|
||
### 디자인 개선
|
||
|
||
- [ ] 더 많은 테마 추가
|
||
- [ ] 커스텀 색상 선택
|
||
- [ ] 폰트 선택 옵션
|
||
- [ ] 배경 이미지 지원
|
||
|
||
---
|
||
|
||
## 📚 참고 자료
|
||
|
||
### 타임존 목록
|
||
|
||
```typescript
|
||
const TIMEZONES = [
|
||
{ label: "서울", value: "Asia/Seoul", offset: "+9" },
|
||
{ label: "도쿄", value: "Asia/Tokyo", offset: "+9" },
|
||
{ label: "베이징", value: "Asia/Shanghai", offset: "+8" },
|
||
{ label: "뉴욕", value: "America/New_York", offset: "-5" },
|
||
{ label: "런던", value: "Europe/London", offset: "+0" },
|
||
{ label: "LA", value: "America/Los_Angeles", offset: "-8" },
|
||
{ label: "파리", value: "Europe/Paris", offset: "+1" },
|
||
{ label: "시드니", value: "Australia/Sydney", offset: "+11" },
|
||
];
|
||
```
|
||
|
||
### Date Format 예시
|
||
|
||
```typescript
|
||
// 24시간 형식
|
||
"14:30:45";
|
||
|
||
// 12시간 형식
|
||
"2:30:45 PM";
|
||
|
||
// 날짜 포함
|
||
"2025년 1월 15일 (수) 14:30:45";
|
||
|
||
// 영문 날짜
|
||
"Wednesday, January 15, 2025 2:30:45 PM";
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 완료 기준
|
||
|
||
- [x] 시계가 실시간으로 정확하게 업데이트됨 (1초마다 업데이트)
|
||
- [x] 아날로그/디지털 스타일 모두 정상 작동 (코드 구현 완료)
|
||
- [x] 타임존 변경이 즉시 반영됨 (Intl.DateTimeFormat 사용)
|
||
- [x] 설정 모달에서 모든 옵션 변경 가능 ✨ (ClockConfigModal 완성!)
|
||
- [x] 테마 전환이 자연스러움 (4가지 테마 구현)
|
||
- [x] 메모리 누수 없음 (컴포넌트 unmount 시 타이머 정리 - useEffect cleanup)
|
||
- [x] 크기 조절 시 레이아웃이 깨지지 않음 (그리드 스냅 적용)
|
||
|
||
---
|
||
|
||
## 💡 팁
|
||
|
||
### 성능 최적화
|
||
|
||
```tsx
|
||
// ❌ 나쁜 예: 컴포넌트 전체 리렌더링
|
||
setInterval(() => {
|
||
setTime(new Date());
|
||
}, 1000);
|
||
|
||
// ✅ 좋은 예: 필요한 부분만 업데이트 + cleanup
|
||
useEffect(() => {
|
||
const timer = setInterval(() => {
|
||
setTime(new Date());
|
||
}, 1000);
|
||
|
||
return () => clearInterval(timer); // cleanup
|
||
}, []);
|
||
```
|
||
|
||
### 타임존 처리
|
||
|
||
```typescript
|
||
// Intl.DateTimeFormat 사용 (권장)
|
||
const formatter = new Intl.DateTimeFormat("ko-KR", {
|
||
timeZone: "America/New_York",
|
||
hour: "2-digit",
|
||
minute: "2-digit",
|
||
});
|
||
console.log(formatter.format(new Date())); // "05:30"
|
||
```
|
||
|
||
---
|
||
|
||
---
|
||
|
||
## 🎉 구현 완료!
|
||
|
||
**구현 날짜**: 2025년 1월 15일
|
||
|
||
### ✅ 완료된 기능
|
||
|
||
1. **타입 정의** - `ClockConfig` 인터페이스 및 `'clock'` subtype 추가
|
||
2. **디지털 시계** - 타임존, 날짜, 초 표시, 12/24시간 형식 지원
|
||
3. **아날로그 시계** - SVG 기반 시계판, 시침/분침/초침 애니메이션
|
||
4. **메인 위젯** - 실시간 업데이트, 스타일별 조건부 렌더링
|
||
5. **통합** - CanvasElement, DashboardDesigner, Sidebar 연동
|
||
6. **테마** - light, dark, blue, gradient 4가지 테마
|
||
|
||
### ✅ 최종 완료 기능
|
||
|
||
1. **시계 위젯 컴포넌트** - 아날로그/디지털/둘다
|
||
2. **실시간 업데이트** - 1초마다 정확한 시간
|
||
3. **타임존 지원** - 8개 주요 도시
|
||
4. **4가지 테마** - light, dark, blue, gradient
|
||
5. **설정 모달** - 모든 옵션 UI로 변경 가능 ✨
|
||
|
||
### 🔜 향후 추가 예정
|
||
|
||
- 세계 시계 (여러 타임존 동시 표시)
|
||
- 알람 기능
|
||
- 타이머/스톱워치
|
||
- 커스텀 색상 선택
|
||
|
||
---
|
||
|
||
## 🎯 사용 방법
|
||
|
||
1. **시계 추가**: 우측 사이드바에서 "⏰ 시계 위젯" 드래그
|
||
2. **설정 변경**: 시계 위에 마우스 올리고 ⚙️ 버튼 클릭
|
||
3. **옵션 선택**:
|
||
- 스타일 (디지털/아날로그/둘다)
|
||
- 타임존 (서울, 뉴욕, 런던 등)
|
||
- 테마 (4가지)
|
||
- 날짜/초/24시간 형식
|
||
|
||
이제 완벽하게 작동하는 시계 위젯을 사용할 수 있습니다! 🚀⏰
|