개발하는데 다 이유가 있겠지

프로젝트에서 필요한 마인드맵을 구현하기 위해 라이브러리를 찾던 중 가장 적합한 라이브러리에 대해서 학습한 내용을 정리하고자 한다.

 

요구사항

1. 노드의 크기가 3개 이상일 것
2. 엣지 커스텀 유무
3. 데이터를 자유롭게 추가, 삭제 가능

---

마인드맵 라이브러리

다양한 라이브러리를 찾아봤는데 커스텀에 용이하고 대규모 그래프를 위한 레이아웃 엔진을 제공하는 `Cytoscape`로 선정했다.

 

Cytoscape(Github / Cytoscape.js)

• 대규모 그래프를 위한 레이아웃 엔진 내장
• 그래프 데이터 구조와 스타일을 JSON 형식으로 관리 가능
• 복잡한 노드 스타일링과 인터랙션 지원

---

Cytoscape 라이브러리

기본 세팅

1. next 프로젝트 생성

npx create-next-app@latest .

2. cytoscape 라이브러리 및 타입 설치

npm i cytoscape
npm i @types/cytoscape

3. next 코드 작성

'use client'

import { useEffect, useState, useRef } from "react";
import cytoscape from "cytoscape";

export default function CytoscapeGraph() {
    const cyRef = useRef<HTMLDivElement | null>(null);
    const [cytoscapeGraph, setCytoscapeGraph] = useState<cytoscape.Core | null>(null);

    useEffect(() => {
        if (!cyRef.current) return;

        const cy = cytoscape({
            container: cyRef.current,
            elements: [
                { data: { id: "ex1" } },
                { data: { id: "ex2" } },
                { data: { id: "ex3" } },
                { data: { id: "ex1-ex2", source: "ex1", target: "ex2" } }
            ],
            style: [
                {
                    selector: "node",
                    style: {
                        "background-color": "#666",
                        "label": "data(id)",
                    }
                },
                {
                    selector: "edge",
                    style: {
                        "width": 3,
                        'line-color': '#ccc',
                        'target-arrow-color': '#ccc',
                        'target-arrow-shape': 'triangle',
                        'curve-style': 'bezier',
                    }
                }
            ],
            layout: {
                name: 'cose',
                randomize: true,
            }
        });

        setCytoscapeGraph(cy);

        return () => {
            cy.destroy();
        };
    }, []);

    return (
        <div ref={cyRef} style={{ width: "100%", height: "100vh" }} />
    );
}

'use client': Cytoscape는 클라이언트 측에서 실행되므로 클라이언트 컴포넌트로 지정해야 함
useState: Cytoscape 인스턴스를 상태로 관리하여 필요할 때 참조할 수 있도록 함
width, height: 너비와 높이를 지정하지 않으면 그래프가 올바르게 렌더링되지 않음

코드 실행 결과

---

다양한 초기화 옵션

const cy = cytoscape({
  // 기본 옵션
  container: undefined, // Cytoscape를 렌더링할 DOM 요소 (현재 undefined)
  elements: [ /* ... */ ], // 그래프의 노드 및 엣지 데이터
  style: [ /* ... */ ], // 노드 및 엣지의 스타일 지정
  layout: { name: 'grid' /* , ... */ }, // 초기 레이아웃 (grid 사용)
  data: { /* ... */ }, // 그래프 전체에 적용되는 데이터

  // 초기 뷰포트 설정
  zoom: 1, // 초기 줌 레벨
  pan: { x: 0, y: 0 }, // 초기 화면 이동 좌표

  // 상호작용 설정
  minZoom: 1e-50, // 최소 줌 값 (매우 확대 가능)
  maxZoom: 1e50, // 최대 줌 값 (매우 축소 가능)
  zoomingEnabled: true, // 줌 기능 활성화 여부
  userZoomingEnabled: true, // 사용자가 줌을 조작할 수 있는지 여부
  panningEnabled: true, // 팬(이동) 기능 활성화 여부
  userPanningEnabled: true, // 사용자가 화면을 이동할 수 있는지 여부
  boxSelectionEnabled: true, // 드래그하여 여러 요소를 선택할 수 있는지 여부
  selectionType: 'single', // 선택 방식 ('single' → 한 번에 하나씩 선택 가능)
  touchTapThreshold: 8, // 터치 입력 시 탭 감지 임계값 (8px)
  desktopTapThreshold: 4, // 데스크톱 마우스 클릭 감지 임계값 (4px)
  autolock: false, // 노드가 자동으로 잠기는지 여부
  autoungrabify: false, // 노드를 드래그할 수 없는 상태로 설정
  autounselectify: false, // 사용자가 노드를 선택할 수 없도록 설정
  multiClickDebounceTime: 250, // 여러 번 클릭 시 디바운스 시간 (250ms)

  // 렌더링 옵션
  headless: false, // 렌더링 없이 데이터만 사용할지 여부 (false → 렌더링함)
  styleEnabled: true, // 스타일 활성화 여부
  hideEdgesOnViewport: false, // 뷰포트 이동 시 엣지를 숨길지 여부
  textureOnViewport: false, // 텍스처 렌더링 활성화 여부
  motionBlur: false, // 애니메이션 시 모션 블러 효과 적용 여부
  motionBlurOpacity: 0.2, // 모션 블러 효과의 투명도
  wheelSensitivity: 1, // 마우스 휠 줌 감도
  pixelRatio: 'auto' // 픽셀 밀도 설정 ('auto' → 자동 조정)
});

---

그래프 조작

추가하기 : cy.add()

'use client'

import {useEffect, useState, useRef, ChangeEvent} from "react";
import cytoscape from "cytoscape";

export default function CytoscapeGraph() {
    const cyRef = useRef<HTMLDivElement | null>(null);
    const [cytoscapeGraph, setCytoscapeGraph] = useState<cytoscape.Core | null>(null);
    const [nodes, setNodes] = useState<string[]>([]);

    const [inputData, setInputData] = useState<string>("");
    const [parent, setParent] = useState<string | null>("");
    const [depth, setDepth] = useState<number>(1);

    useEffect(() => {
        if (!cyRef.current) return;

        const cy = cytoscape({
            container: cyRef.current,
            elements: [
                {data: {id: "ex1"}},
                {data: {id: "ex2"}},
                {data: {id: "ex3"}},
                {data: {id: "ex1-ex2", source: "ex1", target: "ex2"}}
            ],
            style: [
                {
                    selector: "node",
                    style: {
                        "background-color": "#666",
                        "label": "data(id)",
                        "width": 30,
                        "height": 30,
                    }
                },
                {
                    selector: "edge",
                    style: {
                        "width": 3,
                        'line-color': '#ccc',
                        'target-arrow-color': '#ccc',
                        'target-arrow-shape': 'triangle',
                        'curve-style': 'bezier',
                    }
                }
            ],
            layout: {
                name: 'cose',
                randomize: true,
            }
        });

        setCytoscapeGraph(cy);
        setNodes(cy.nodes().map(node => node.id()));

        return () => {
            cy.destroy();
        };
    }, []);

    function handleChangeInputData(e: ChangeEvent<HTMLInputElement>) {
        setInputData(e.target.value);
    }

    function handleSelectParent(e: ChangeEvent<HTMLSelectElement>) {
        setParent(e.target.value);
    }

    function handleSelectDepth(e: ChangeEvent<HTMLSelectElement>) {
        setDepth(Number(e.target.value));
    }

    function handleAddButton() {
        if (!cytoscapeGraph) return;

        const style = {
            "width": depth === 3 ? 30 : depth === 2 ? 20 : 10,
            "height": depth === 3 ? 30 : depth === 2 ? 20 : 10,
        }
        if (parent === "") {
            cytoscapeGraph.add({
                group: "nodes",
                data: {id: inputData},
                style: style
            });
        } else {
            cytoscapeGraph.add([
                {
                    group: "nodes",
                    data: {id: inputData},
                    style: style
                },
                {
                    group: "edges",
                    data: {id: `${parent}-${inputData}`, source: parent, target: inputData}
                }
            ]);
        }

        setNodes(prevNodes => [...prevNodes, inputData]);
        setInputData("");
        setParent("");
        setDepth(1); // depth 초기화

        cytoscapeGraph.elements().layout({
            name: 'cose',
            animate: true,
            animationDuration: 1000,
            animationEasing: 'ease-in-out'
        }).run();
    }

    return (
        <div>
            <div ref={cyRef} style={{width: "100%", height: "80vh"}}/>
            키워드<input type='text' value={inputData} onChange={(e) => handleChangeInputData(e)}
                      style={{border: '1px solid black'}}/><br/>
            상위 키워드<select value={parent || ""} onChange={(e) => handleSelectParent(e)}
                          style={{border: '1px solid black'}}>
            <option key={0}>없음</option>
            {nodes.map((node, idx) =>
                <option key={idx}>{node}</option>)}
        </select><br/>
            단계<select value={depth} onChange={(e) => handleSelectDepth(e)}
                      style={{border: '1px solid black'}}>
            {[1, 2, 3].map((i, idx) =>
                <option key={idx} value={i}>{i}단계</option>)}
        </select><br/>
            <button onClick={handleAddButton}>추가</button>
        </div>
    );
}

- 부모가 있으면 부모에 노드를 연결해서 추가 후 위치 재조정
- 부모가 없다면 추가 후 위치 재조정
- 각 단계별로 원 크기 조정

코드 실행 결과

 

제거하기 : cy.remove()

// 삭제 로직 추가
function handleDeleteButton() {
    if (!cytoscapeGraph) return;

    // 선택된 노드나 부모-자식 관계 삭제
    if (inputData) {
        const nodeToDelete = cytoscapeGraph.getElementById(inputData);
        if (nodeToDelete) {
            nodeToDelete.remove();
        }
    }

    setNodes(nodes.filter(node => node !== inputData));
    setInputData("");
    setParent("");
    setDepth(1);
}

코드 실행 결과

---

그룹화하기 : cy.collection()

// 빈 컬렉션(그룹) 생성
let collection = cy.collection();

cy.nodes().on('click', function (e) {
    const clickedNode = e.target;
	
    // 이미 컬렉션에 선택한 노드가 있다면
    if (collection.contains(clickedNode)) {
    	// 노드를 컬렉션에서 제거
        collection = collection.difference(clickedNode);
        // 색상 원상복구
        clickedNode.style({
            'background-color': '#666',
        })
    } else {
    	// 컬렉션에 노드가 없다면 추가
        collection = collection.union(clickedNode);
    }
	
    // 컬렉션 색깔
    collection.nodes().style({
        'background-color': '#afe',
    })
})

cy.collection() : 빈 컬렉션 생성
collection.union(node) : 컬렉션에 노드 추가
collection.difference(node) : 컬렉션에서 노드 제거

코드 실행 결과

---

선택자(Selector)

1. cy.$(selector)
그래프에서 특정 선택자(selector)에 맞는 요소(노드 또는 엣지)를 가져옴

cy.$('node') // 모든 노드를 가져옴
cy.$('edge') // 모든 엣지를 가져옴
cy.$('#ex1') // id가 'ex1'인 요소를 가져옴
cy.$('[book="book1"]') // book 속성이 'book1'인 요소를 가져옴

 

2. cy.elements(selector)
그래프에서 특정 선택자(selector)에 맞는 모든 요소(노드 + 엣지)를 가져옴

cy.elements() // 모든 요소(노드 + 엣지) 가져오기
cy.elements('[book="book2"]') // book이 'book2'인 모든 요소 가져오기

 

3. cy.nodes(selector)
그래프에서 특정 선택자(selector)에 맞는 모든 노드를 가져옴

cy.nodes() // 모든 노드를 가져옴
cy.nodes('[book="book1"]') // book 속성이 'book1'인 노드만 가져옴
cy.nodes('#ex1') // id가 'ex1'인 노드 가져오기

 

4. cy.edges(selector)
그래프에서 특정 선택자(selector)에 맞는 모든 엣지(선)를 가져옴

cy.edges() // 모든 엣지를 가져옴
cy.edges('[source="ex1"]') // 출발 노드가 'ex1'인 엣지만 가져오기

 

 

5. cy.filter(selector)
특정 선택자(selector)에 맞는 요소를 필터링함

cy.elements().filter('[book="book1"]') // book 속성이 'book1'인 요소만 필터링
cy.nodes().filter('#ex2') // id가 'ex2'인 노드만 필터링

 

6. cy.filter(function(ele, i, eles))
사용자 정의 함수로 필터링

// book 속성이 'book1'인 노드만 가져오기
cy.nodes().filter((ele) => ele.data('book') === 'book1') 

// 출발 노드(source)가 'ex1'인 엣지만 가져오기
cy.edges().filter((ele) => ele.data('source') === 'ex1')

---

요소 스타일 일괄 변경 : cy.batch()

요소 스타일을 변경할 때 한 번에 변경하여 리렌더링을 줄여 성능을 향상시킴

 

1. cy.batch(callback)
- 여러 개의 노드/엣지 속성을 한 번에 변경할 때 사용
- `callback` 안에서 여러 개의 스타일 변경을 하면 한 번만 스타일을 계산하고, 한 번만 화면을 다시 그림(리렌더링 1번 발생)

cy.batch(() => {
  cy.$('#j')
    .data('weight', '70')   // 데이터 변경
    .addClass('funny')      // funny 클래스 추가
    .removeClass('serious') // serious 클래스 제거
});

 

2. cy.startBatch() & cy.endBatch()
- 비동기 작업이 필요한 경우 사용
- `startBatch()` : 여러 스타일 변경 시작
- `endBatch()` : 모든 변경을 한 번에 적용

cy.startBatch();

cy.$('#j')
  .data('weight', '70')
  .addClass('funny')
  .removeClass('serious');

cy.endBatch();

 

📌 cy.batch() 사용 시 주의할 점

🚨 batch 안에서 하면 안 되는 것들
- cy.layout() 실행 ❌ → 레이아웃 변경 X
- ele.style() 읽기 ❌ → 스타일이 최신 상태가 아닐 수도 있음
- ele.boundingBox() 읽기 ❌ → 요소 크기가 바뀌었을 수도 있음
- ele.animation() 실행 ❌ → 애니메이션 적용 X

✅ batch 안에서 하면 좋은 것들
- ele.data() 변경
- ele.addClass(), ele.removeClass()
- eles.union(), eles.difference() 같은 컬렉션 조작

---

그래프 동적 추가 및 제거 : cy.mount(), cy.unmount(), cy.destroy()

cy.unmount(); // 그래프를 화면에서 숨김

1. cy.mount(container) : 그래프 HTML 요소에 붙이기
- cytoscape 그래프를 특정 `div`요소 안에 표시할 때 사용
- 원래 화면에 없던(headless) 그래프도 mount하면 화면에 나타남

const cy = cytoscape({
  elements: [
    { data: { id: 'a' } },
    { data: { id: 'b' } },
    { data: { id: 'a-b', source: 'a', target: 'b' } }
  ],
  layout: { name: 'grid' },
  style: [{ selector: 'node', style: { 'background-color': '#666' } }]
});

// 특정 div 안에 그래프를 붙이기!
cy.mount(document.getElementById('cy-container'));

 

2. cy.unmount() : 그래프 숨기기 (삭제 아님❗️)
- 화면에서 그래프를 없애지만, 데이터는 그대로 유지
- 다시 cy.mount(container)하면 그래프가 다시 보임

cy.unmount(); // 그래프를 화면에서 숨김

 

3. cy.destroy() : 그래프 완전히 삭제
- 그래프 데이터를 포함한 모든 것을 삭제하고 메모리를 정리
- cy.unmount()와 다르게, 삭제된 후 다시 mount할 수 없음

cy.destroy(); // Cytoscape 인스턴스 완전히 삭제

 

4. cy.destroyed() : 그래프가 삭제되었는지 확인
- 그래프가 destroy()로 삭제되었는지 확인 가능

console.log(cy.destroyed()); // true면 삭제됨, false면 아직 살아있음