344 lines
7.6 KiB
Plaintext
344 lines
7.6 KiB
Plaintext
|
# 고정 헤더 테이블 표준 가이드
|
||
|
|
|
||
|
|
## 개요
|
||
|
|
|
||
|
|
스크롤 가능한 테이블에서 헤더를 상단에 고정하는 표준 구조입니다.
|
||
|
|
플로우 위젯의 스텝 데이터 리스트 테이블을 참조 기준으로 합니다.
|
||
|
|
|
||
|
|
## 필수 구조
|
||
|
|
|
||
|
|
### 1. 기본 HTML 구조
|
||
|
|
|
||
|
|
```tsx
|
||
|
|
<div className="relative overflow-auto" style={{ height: "450px" }}>
|
||
|
|
<Table noWrapper>
|
||
|
|
<TableHeader>
|
||
|
|
<TableRow>
|
||
|
|
<TableHead className="bg-background sticky top-0 z-10 border-b shadow-[0_1px_0_0_rgb(0,0,0,0.1)]">
|
||
|
|
헤더 1
|
||
|
|
</TableHead>
|
||
|
|
<TableHead className="bg-background sticky top-0 z-10 border-b shadow-[0_1px_0_0_rgb(0,0,0,0.1)]">
|
||
|
|
헤더 2
|
||
|
|
</TableHead>
|
||
|
|
</TableRow>
|
||
|
|
</TableHeader>
|
||
|
|
<TableBody>{/* 데이터 행들 */}</TableBody>
|
||
|
|
</Table>
|
||
|
|
</div>
|
||
|
|
```
|
||
|
|
|
||
|
|
### 2. 필수 클래스 설명
|
||
|
|
|
||
|
|
#### 스크롤 컨테이너 (외부 div)
|
||
|
|
|
||
|
|
```tsx
|
||
|
|
className="relative overflow-auto"
|
||
|
|
style={{ height: "450px" }}
|
||
|
|
```
|
||
|
|
|
||
|
|
**필수 요소:**
|
||
|
|
|
||
|
|
- `relative`: sticky positioning의 기준점
|
||
|
|
- `overflow-auto`: 스크롤 활성화
|
||
|
|
- `height`: 고정 높이 (인라인 스타일 또는 Tailwind 클래스)
|
||
|
|
|
||
|
|
#### Table 컴포넌트
|
||
|
|
|
||
|
|
```tsx
|
||
|
|
<Table noWrapper>
|
||
|
|
```
|
||
|
|
|
||
|
|
**필수 props:**
|
||
|
|
|
||
|
|
- `noWrapper`: Table 컴포넌트의 내부 wrapper 제거 (매우 중요!)
|
||
|
|
- 이것이 없으면 sticky header가 작동하지 않음
|
||
|
|
|
||
|
|
#### TableHead (헤더 셀)
|
||
|
|
|
||
|
|
```tsx
|
||
|
|
className =
|
||
|
|
"bg-background sticky top-0 z-10 border-b shadow-[0_1px_0_0_rgb(0,0,0,0.1)]";
|
||
|
|
```
|
||
|
|
|
||
|
|
**필수 클래스:**
|
||
|
|
|
||
|
|
- `bg-background`: 배경색 (스크롤 시 데이터가 보이지 않도록)
|
||
|
|
- `sticky top-0`: 상단 고정
|
||
|
|
- `z-10`: 다른 요소 위에 표시
|
||
|
|
- `border-b`: 하단 테두리
|
||
|
|
- `shadow-[0_1px_0_0_rgb(0,0,0,0.1)]`: 얇은 그림자 (헤더와 본문 구분)
|
||
|
|
|
||
|
|
### 3. 왼쪽 열 고정 (체크박스 등)
|
||
|
|
|
||
|
|
첫 번째 열도 고정하려면:
|
||
|
|
|
||
|
|
```tsx
|
||
|
|
<TableHead className="bg-background sticky top-0 left-0 z-20 border-b shadow-[0_1px_0_0_rgb(0,0,0,0.1)]">
|
||
|
|
<Checkbox />
|
||
|
|
</TableHead>
|
||
|
|
```
|
||
|
|
|
||
|
|
**z-index 규칙:**
|
||
|
|
|
||
|
|
- 왼쪽+상단 고정: `z-20`
|
||
|
|
- 상단만 고정: `z-10`
|
||
|
|
- 왼쪽만 고정: `z-10`
|
||
|
|
- 일반 셀: z-index 없음
|
||
|
|
|
||
|
|
### 4. 완전한 예제 (체크박스 포함)
|
||
|
|
|
||
|
|
```tsx
|
||
|
|
<div className="relative overflow-auto" style={{ height: "450px" }}>
|
||
|
|
<Table noWrapper>
|
||
|
|
<TableHeader>
|
||
|
|
<TableRow>
|
||
|
|
{/* 왼쪽 고정 체크박스 열 */}
|
||
|
|
<TableHead className="bg-background sticky top-0 left-0 z-20 w-12 border-b px-3 py-2 text-center shadow-[0_1px_0_0_rgb(0,0,0,0.1)]">
|
||
|
|
<Checkbox checked={allSelected} onCheckedChange={handleSelectAll} />
|
||
|
|
</TableHead>
|
||
|
|
|
||
|
|
{/* 일반 헤더 열들 */}
|
||
|
|
{columns.map((col) => (
|
||
|
|
<TableHead
|
||
|
|
key={col}
|
||
|
|
className="bg-background sticky top-0 z-10 border-b px-3 py-2 text-xs font-semibold whitespace-nowrap shadow-[0_1px_0_0_rgb(0,0,0,0.1)] sm:text-sm"
|
||
|
|
>
|
||
|
|
{col}
|
||
|
|
</TableHead>
|
||
|
|
))}
|
||
|
|
</TableRow>
|
||
|
|
</TableHeader>
|
||
|
|
|
||
|
|
<TableBody>
|
||
|
|
{data.map((row, index) => (
|
||
|
|
<TableRow key={index}>
|
||
|
|
{/* 왼쪽 고정 체크박스 */}
|
||
|
|
<TableCell className="bg-background sticky left-0 z-10 border-b px-3 py-2 text-center">
|
||
|
|
<Checkbox
|
||
|
|
checked={selectedRows.has(index)}
|
||
|
|
onCheckedChange={() => toggleRow(index)}
|
||
|
|
/>
|
||
|
|
</TableCell>
|
||
|
|
|
||
|
|
{/* 데이터 셀들 */}
|
||
|
|
{columns.map((col) => (
|
||
|
|
<TableCell key={col} className="border-b px-3 py-2">
|
||
|
|
{row[col]}
|
||
|
|
</TableCell>
|
||
|
|
))}
|
||
|
|
</TableRow>
|
||
|
|
))}
|
||
|
|
</TableBody>
|
||
|
|
</Table>
|
||
|
|
</div>
|
||
|
|
```
|
||
|
|
|
||
|
|
## 반응형 대응
|
||
|
|
|
||
|
|
### 모바일: 카드 뷰
|
||
|
|
|
||
|
|
```tsx
|
||
|
|
{
|
||
|
|
/* 모바일: 카드 뷰 */
|
||
|
|
}
|
||
|
|
<div className="overflow-y-auto sm:hidden" style={{ height: "450px" }}>
|
||
|
|
<div className="space-y-2 p-3">
|
||
|
|
{data.map((item, index) => (
|
||
|
|
<div key={index} className="bg-card rounded-md border p-3">
|
||
|
|
{/* 카드 내용 */}
|
||
|
|
</div>
|
||
|
|
))}
|
||
|
|
</div>
|
||
|
|
</div>;
|
||
|
|
|
||
|
|
{
|
||
|
|
/* 데스크톱: 테이블 뷰 */
|
||
|
|
}
|
||
|
|
<div
|
||
|
|
className="relative hidden overflow-auto sm:block"
|
||
|
|
style={{ height: "450px" }}
|
||
|
|
>
|
||
|
|
<Table noWrapper>{/* 위의 테이블 구조 */}</Table>
|
||
|
|
</div>;
|
||
|
|
```
|
||
|
|
|
||
|
|
## 자주하는 실수
|
||
|
|
|
||
|
|
### ❌ 잘못된 예시
|
||
|
|
|
||
|
|
```tsx
|
||
|
|
{
|
||
|
|
/* 1. noWrapper 없음 - sticky 작동 안함 */
|
||
|
|
}
|
||
|
|
<Table>
|
||
|
|
<TableHeader>...</TableHeader>
|
||
|
|
</Table>;
|
||
|
|
|
||
|
|
{
|
||
|
|
/* 2. 배경색 없음 - 스크롤 시 데이터가 보임 */
|
||
|
|
}
|
||
|
|
<TableHead className="sticky top-0">헤더</TableHead>;
|
||
|
|
|
||
|
|
{
|
||
|
|
/* 3. relative 없음 - sticky 기준점 없음 */
|
||
|
|
}
|
||
|
|
<div className="overflow-auto">
|
||
|
|
<Table noWrapper>...</Table>
|
||
|
|
</div>;
|
||
|
|
|
||
|
|
{
|
||
|
|
/* 4. 고정 높이 없음 - 스크롤 발생 안함 */
|
||
|
|
}
|
||
|
|
<div className="relative overflow-auto">
|
||
|
|
<Table noWrapper>...</Table>
|
||
|
|
</div>;
|
||
|
|
```
|
||
|
|
|
||
|
|
### ✅ 올바른 예시
|
||
|
|
|
||
|
|
```tsx
|
||
|
|
{
|
||
|
|
/* 모든 필수 요소 포함 */
|
||
|
|
}
|
||
|
|
<div className="relative overflow-auto" style={{ height: "450px" }}>
|
||
|
|
<Table noWrapper>
|
||
|
|
<TableHeader>
|
||
|
|
<TableRow>
|
||
|
|
<TableHead className="bg-background sticky top-0 z-10 border-b shadow-[0_1px_0_0_rgb(0,0,0,0.1)]">
|
||
|
|
헤더
|
||
|
|
</TableHead>
|
||
|
|
</TableRow>
|
||
|
|
</TableHeader>
|
||
|
|
<TableBody>...</TableBody>
|
||
|
|
</Table>
|
||
|
|
</div>;
|
||
|
|
```
|
||
|
|
|
||
|
|
## 높이 설정 가이드
|
||
|
|
|
||
|
|
### 권장 높이값
|
||
|
|
|
||
|
|
- **소형 리스트**: `300px` ~ `400px`
|
||
|
|
- **중형 리스트**: `450px` ~ `600px` (플로우 위젯 기준)
|
||
|
|
- **대형 리스트**: `calc(100vh - 200px)` (화면 높이 기준)
|
||
|
|
|
||
|
|
### 동적 높이 계산
|
||
|
|
|
||
|
|
```tsx
|
||
|
|
// 화면 높이의 60%
|
||
|
|
style={{ height: "60vh" }}
|
||
|
|
|
||
|
|
// 화면 높이 - 헤더/푸터 제외
|
||
|
|
style={{ height: "calc(100vh - 250px)" }}
|
||
|
|
|
||
|
|
// 부모 요소 기준
|
||
|
|
className="h-full overflow-auto"
|
||
|
|
```
|
||
|
|
|
||
|
|
## 성능 최적화
|
||
|
|
|
||
|
|
### 1. 가상 스크롤 (대량 데이터)
|
||
|
|
|
||
|
|
데이터가 1000건 이상인 경우 `react-virtual` 사용 권장:
|
||
|
|
|
||
|
|
```tsx
|
||
|
|
import { useVirtualizer } from "@tanstack/react-virtual";
|
||
|
|
|
||
|
|
const parentRef = useRef<HTMLDivElement>(null);
|
||
|
|
|
||
|
|
const rowVirtualizer = useVirtualizer({
|
||
|
|
count: data.length,
|
||
|
|
getScrollElement: () => parentRef.current,
|
||
|
|
estimateSize: () => 50, // 행 높이
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
### 2. 페이지네이션
|
||
|
|
|
||
|
|
대량 데이터는 페이지 단위로 렌더링:
|
||
|
|
|
||
|
|
```tsx
|
||
|
|
const paginatedData = data.slice((page - 1) * pageSize, page * pageSize);
|
||
|
|
```
|
||
|
|
|
||
|
|
## 접근성
|
||
|
|
|
||
|
|
### ARIA 레이블
|
||
|
|
|
||
|
|
```tsx
|
||
|
|
<div
|
||
|
|
className="relative overflow-auto"
|
||
|
|
style={{ height: "450px" }}
|
||
|
|
role="region"
|
||
|
|
aria-label="스크롤 가능한 데이터 테이블"
|
||
|
|
tabIndex={0}
|
||
|
|
>
|
||
|
|
<Table noWrapper aria-label="데이터 목록">
|
||
|
|
{/* 테이블 내용 */}
|
||
|
|
</Table>
|
||
|
|
</div>
|
||
|
|
```
|
||
|
|
|
||
|
|
### 키보드 네비게이션
|
||
|
|
|
||
|
|
```tsx
|
||
|
|
<TableRow
|
||
|
|
tabIndex={0}
|
||
|
|
onKeyDown={(e) => {
|
||
|
|
if (e.key === "Enter" || e.key === " ") {
|
||
|
|
handleRowClick();
|
||
|
|
}
|
||
|
|
}}
|
||
|
|
>
|
||
|
|
{/* 행 내용 */}
|
||
|
|
</TableRow>
|
||
|
|
```
|
||
|
|
|
||
|
|
## 다크 모드 대응
|
||
|
|
|
||
|
|
### 배경색
|
||
|
|
|
||
|
|
```tsx
|
||
|
|
{
|
||
|
|
/* 라이트/다크 모드 모두 대응 */
|
||
|
|
}
|
||
|
|
className = "bg-background"; // ✅ 권장
|
||
|
|
|
||
|
|
{
|
||
|
|
/* 고정 색상 - 다크 모드 문제 */
|
||
|
|
}
|
||
|
|
className = "bg-white"; // ❌ 비권장
|
||
|
|
```
|
||
|
|
|
||
|
|
### 그림자
|
||
|
|
|
||
|
|
```tsx
|
||
|
|
{
|
||
|
|
/* 다크 모드에서도 보이는 그림자 */
|
||
|
|
}
|
||
|
|
className = "shadow-[0_1px_0_0_hsl(var(--border))]";
|
||
|
|
|
||
|
|
{
|
||
|
|
/* 또는 */
|
||
|
|
}
|
||
|
|
className = "shadow-[0_1px_0_0_rgb(0,0,0,0.1)]";
|
||
|
|
```
|
||
|
|
|
||
|
|
## 참조 파일
|
||
|
|
|
||
|
|
- **구현 예시**: `frontend/components/screen/widgets/FlowWidget.tsx` (line 760-820)
|
||
|
|
- **Table 컴포넌트**: `frontend/components/ui/table.tsx`
|
||
|
|
|
||
|
|
## 체크리스트
|
||
|
|
|
||
|
|
테이블 구현 시 다음을 확인하세요:
|
||
|
|
|
||
|
|
- [ ] 외부 div에 `relative overflow-auto` 적용
|
||
|
|
- [ ] 외부 div에 고정 높이 설정
|
||
|
|
- [ ] `<Table noWrapper>` 사용
|
||
|
|
- [ ] TableHead에 `bg-background sticky top-0 z-10` 적용
|
||
|
|
- [ ] TableHead에 `border-b shadow-[...]` 적용
|
||
|
|
- [ ] 왼쪽 고정 열은 `z-20` 사용
|
||
|
|
- [ ] 모바일 반응형 대응 (카드 뷰)
|
||
|
|
- [ ] 다크 모드 호환 색상 사용
|