Skip to content

Commit fbc6c9c

Browse files
committed
docs: add AutoTypeTable for ClusterMarkerProp with Korean JSDoc
1 parent 2d4aeb6 commit fbc6c9c

File tree

2 files changed

+20
-117
lines changed

2 files changed

+20
-117
lines changed

docs/content/docs/marker-clustering.mdx

Lines changed: 4 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ const clusterMarkers: ClusterMarkerProp[] = [
3535
height: 40,
3636
},
3737
{
38-
identifier: 'marker-2',
38+
identifier: 'marker-2',
3939
latitude: 37.5675,
4040
longitude: 126.9785,
4141
image: { symbol: 'blue' },
@@ -127,25 +127,6 @@ const multiClusters = useMemo(() => [
127127
], [regularMarkers, specialMarkers]);
128128
```
129129

130-
### 동적 마커 이미지
131-
132-
마커 이미지를 동적으로 생성하여 사용할 수 있습니다:
133-
134-
```tsx
135-
const dynamicMarkers = useMemo(() => {
136-
return markerData.map((marker, index) => ({
137-
identifier: marker.id,
138-
latitude: marker.latitude,
139-
longitude: marker.longitude,
140-
image: {
141-
httpUri: `https://api.example.com/marker-image/${marker.category}/${marker.id}`,
142-
},
143-
width: 40,
144-
height: 40,
145-
}));
146-
}, [markerData]);
147-
```
148-
149130
## 클러스터 이벤트 처리
150131

151132
### 개별 마커 클릭 이벤트
@@ -163,102 +144,8 @@ const dynamicMarkers = useMemo(() => {
163144
/>
164145
```
165146

166-
## 성능 최적화
167-
168-
### 화면 영역 기반 마커 필터링
169-
170-
많은 수의 마커가 있을 때는 현재 화면에 보이는 영역의 마커만 클러스터링에 포함시켜 성능을 향상시킬 수 있습니다:
171-
172-
```tsx
173-
const useViewportMarkers = (allMarkers: MarkerData[], region: Region) => {
174-
return useMemo(() => {
175-
const padding = 0.1; // 화면 영역 패딩
176-
177-
return allMarkers.filter(marker => {
178-
const isInView =
179-
marker.latitude >= region.latitude - region.latitudeDelta - padding &&
180-
marker.latitude <= region.latitude + region.latitudeDelta + padding &&
181-
marker.longitude >= region.longitude - region.longitudeDelta - padding &&
182-
marker.longitude <= region.longitude + region.longitudeDelta + padding;
183-
184-
return isInView;
185-
});
186-
}, [allMarkers, region]);
187-
};
188-
189-
const OptimizedClusteringExample = () => {
190-
const [currentRegion, setCurrentRegion] = useState(initialRegion);
191-
const viewportMarkers = useViewportMarkers(allMarkers, currentRegion);
192-
193-
const clusters = useMemo(() => [
194-
{
195-
width: 40,
196-
height: 40,
197-
markers: viewportMarkers.map(marker => ({
198-
identifier: marker.id,
199-
latitude: marker.latitude,
200-
longitude: marker.longitude,
201-
image: marker.image,
202-
width: 40,
203-
height: 40,
204-
})),
205-
screenDistance: 40,
206-
animate: true,
207-
}
208-
], [viewportMarkers]);
209-
210-
return (
211-
<NaverMapView
212-
clusters={clusters}
213-
onCameraChanged={({ region }) => {
214-
setCurrentRegion(region);
215-
}}
216-
/>
217-
);
218-
};
219-
```
220-
221-
## 클러스터링 파라미터 가이드
222-
223-
<Callout type="info">
224-
**클러스터링 파라미터 설명:**
225-
226-
- `width`, `height`: 클러스터 마커의 크기 (픽셀)
227-
- `screenDistance`: 두 마커가 화면상에서 이 거리(픽셀) 이내에 있으면 클러스터링됨
228-
- `minZoom`: 이 줌 레벨보다 낮으면 클러스터링하지 않음
229-
- `maxZoom`: 이 줌 레벨보다 높으면 클러스터링하지 않음
230-
- `animate`: 줌 변경 시 클러스터 펼침/합침 애니메이션 여부
231-
</Callout>
232-
233-
### 권장 설정값
234-
235-
```tsx
236-
const recommendedClusterConfig = {
237-
width: 50, // 적당한 클러스터 마커 크기
238-
height: 50,
239-
screenDistance: 40, // 너무 작으면 클러스터링이 적게 됨, 너무 크면 과도하게 됨
240-
minZoom: 5, // 너무 축소된 상태에서는 클러스터링 비활성화
241-
maxZoom: 18, // 충분히 확대된 상태에서는 개별 마커 표시
242-
animate: true, // 사용자 경험 향상을 위한 애니메이션
243-
};
244-
```
245-
246-
## 문제 해결
247-
248-
### 클러스터가 표시되지 않는 경우
249-
250-
- `ClusterMarkerProp``identifier` 값이 고유한지 확인
251-
- `latitude`, `longitude` 좌표값이 올바른지 확인
252-
- `width`, `height` 값이 0보다 큰 값인지 확인
253-
- 마커 이미지 경로가 올바른지 확인
254-
255-
### 성능이 느린 경우
256-
257-
- `screenDistance` 값을 늘려 클러스터 생성을 줄임
258-
- 화면 영역 기반 필터링 적용
259-
- 마커 수를 줄이거나 페이지네이션 적용
260-
- `animate: false`로 설정하여 애니메이션 비활성화
147+
## Props
261148

262-
### 클러스터 마커가 원하는 모양이 아닌 경우
149+
`ClusterMarkerProp`
263150

264-
현재 네이버 지도 라이브러리는 기본 클러스터 마커 스타일을 사용합니다. 커스텀 클러스터 마커 디자인이 필요한 경우, 클러스터링 레벨에 따라 개별 마커를 조건부로 표시하는 방법을 고려해보세요.
151+
<AutoTypeTable path="../src/types/ClusterMarkerProp.ts" name="ClusterMarkerProp" />

src/types/ClusterMarkerProp.ts

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,25 @@
11
import type { Coord } from './Coord';
22
import type { MarkerImageProp } from './MarkerImageProp';
33

4+
/**
5+
* 클러스터에 포함될 수 있는 마커의 속성입니다.
6+
*/
47
export interface ClusterMarkerProp extends Coord {
8+
/**
9+
* 클러스터 내에서 마커를 구분하는 고유 식별자입니다.
10+
* 클러스터 이벤트에서 개별 마커를 식별하는 데 사용됩니다.
11+
*/
512
identifier: string;
13+
614
image?: MarkerImageProp;
15+
16+
/**
17+
* 마커의 너비 (픽셀 단위).
18+
*/
719
width?: number;
20+
21+
/**
22+
* 마커의 높이 (픽셀 단위).
23+
*/
824
height?: number;
925
}

0 commit comments

Comments
 (0)