Drag Selector Libs

The project of Drag Selector UI library.

This project has been created by Vessel CLI. For a simple and quick reference about it, click here.

About

마우스로 드래그하여 화면 엘리먼트를 선택하는 기능의 라이브러리. 마우스 클릭으로 엘리먼트를 선택하거나 드래그하여 범위 내 엘리먼트들을 선택 및 선택해제 할 수 있다. CTRL키(Windows) 혹은 CMD키(MacOS)를 누른 상태에서 마우스 클릭 혹은 드래그시 선택 영역 내의 엘리먼트가 merge되며, ALT키 혹은 SHIFT키로 선택해제 할 수 있다.

Installation

해당 모듈을 사용할 프로젝트에서는 아래와 같이 설치한다.

$ npm install --save @mornya/drag-selector-libs
or
$ yarn add @mornya/drag-selector-libs

Usage

React.js 혹은 Vue.js 내부 라이프 사이클과는 별개로 작동하므로 컴포넌트 mount 시점에 라이브러리를 초기화 하고 unmount 시점에 라이브러리를 해제하여 준다.

선택적으로 라이브러리 내 SCSS 파일을 적용 할 수 있다. 아래와 같이 import 해주거나, 해당 파일을 참조하여 커스터마이징해서 별도 파일로써 적용해준다.

각 <span class="drag-selector-item">으로 생성되는 엘리먼트들은 아래와 같은 속성값을 전달해 줄 수 있다.

• data-id="문자열": 라이브러리의 setSelection() 메소드를 통해 선택/선택해제 할 대상을 지정하기 위해 고유의 ID값을 부여한다. 지정하지 않으면 해당 엘리먼트의 순서 번호가 할당된다.
• data-selected=" true or false ": 라이브러리 초기화 시점에 해당 엘리먼트가 선택된 상태로 표시된다.
• data-disabled=" true or false ": 해당 엘리먼트는 표시되어도 선택이 불가능하도록 한다.

<div class="drag-selector">
  <span class="drag-selector-item" data-id="no_1" data-selected="true">No 1</span>
  <span class="drag-selector-item" data-id="no_2" data-disabled="true">No 2</span>
  ...
</div>

Example for Vue.js

<template>
  <!-- ... -->
  <div class="drag-selector">
    <template v-for="(item, index) in data">
      <span
        :key="index"
        class="drag-selector-item"
        :data-selected="item.isSelected"
        :data-disabled="false"
      >
        {{ item.label }} {{ index + 1 }}
      </span>
    </template>
  </div>
  <!-- ... -->
</template>

<script>
import { DragSelector } from '@mornya/drag-selector-libs'

export default {
  data () {
    return {
      ds: null,
      data: [
        /* ... */
        { id: 'ID1', label: '엘리먼트1', isSelected: true },
        { id: 'ID2', label: '엘리먼트2', isSelected: false },
        /* ... */
      ],
    }
  },
  mounted () {
    this.ds = new DragSelector()
  },
  beforeDestroy () {
    this.ds?.destroy()
  },
}
</script>

<style lang="scss">
  @import "~@mornya/drag-selector-libs/dist/drag-selector.scss";
</style>

Example for React.js

import React, { useRef, useMemo, useEffect } from 'react';
import { DragSelector } from '@mornya/drag-selector-libs';
import type { IDragSelector } from '@mornya/drag-selector-libs';
import '@mornya/drag-selector-libs/dist/drag-selector.scss';

type Data = {
  id: string;
  label: string;
  isSelected: boolean;
};

const DragSelectors: React.FC = () => {
  const dragSelector = useRef<IDragSelector>();
  const datas: Data[] = [
    /* ... */
    { id: 'ID1', label: '엘리먼트1', isSelected: true },
    { id: 'ID2', label: '엘리먼트2', isSelected: false },
    /* ... */
  ];

  useEffect(() => {
    if (!dragSelector.current) {
      dragSelector.current = new DragSelector();
    }
    return () => {
      dragSelector.current?.destroy();
    };
  }, []);

  return (
    <>
      {/* ... */}
      <div className="drag-selector">
        {datas.map((item, index) =>
          <span
            key={`${item.id}-${index}`}
            className="drag-selector-item"
            data-selected={item.isSelected}
            data-disabled={false}
          >
            {`${item.label} ${index + 1}`}
          </span>
        )}
      </div>
      {/* ... */}
    </>
  );
};

export default DragSelectors;

Options

드래그 셀렉터 라이브러리를 일반적으로 사용할 때는 별도의 옵션은 필요하지 않지만 필요시 아래와 같이 옵션을 지정 할 수 있다.

// 각 값들은 디폴트 설정 값임.
const option: IDragSelectorOption = {
  data: [],
  isAllowOverSelection: true,
  onSelected (data) {},
};

data

실행 초기 기본적으로 선택된 상태를 나타내기 위한 데이터셋 (boolean[]). 각 아이템 순서대로 boolean 값을 나열한 배열을 전달해주면 된다.

isAllowOverSelection

아이템을 마우스 드래깅으로 선택할 때 선택 영역 레이어가 나타나는 범위를 제한한다. true로 지정하면 선택 영역 레이어가 .drag-selector 영역을 벗어나지 않도록하며, false로 지정하면 영역을 벗어나도 표시가 된다.

onSelected

아이템을 추가/빼기 했을 때 발생하는 콜백 이벤트이며, 모든 아이템의 선택여부를 boolean[] 형태의 데이터셋으로 되돌려준다.

Methods

DragSelector

DragSelector.getSelectables

선택 가능한 엘리먼트들의 갯수를 리턴한다. 전체 선택 가능한 갯수를 표시하는 등에 사용한다.

getSelectables();

DragSelector.getSelectableCount

파라미터로 전달된 ID들에 해당하는 선택가능한 엘리먼트 갯수를 리턴한다.

getSelectableCount(['no_1', 'no_2']);

DragSelector.getSelectedCount

파라미터로 전달된 ID들에 해당하는 선택된 엘리먼트 갯수를 리턴한다.

getSelectedCount(['no_3']);

DragSelector.setActive

드래그 셀렉터 기능을 활성화 하거나 비활성화 한다. 비활성화시 추가/빼기 된 아이템은 그대로 유지되지만 단지 선택하기 기능만 중지된다. 각 아이템이 하위 컴포넌트나 폼 요소 등의 기능이 있는 복합적인 UI 구조에서 해당 메소드를 이용하여 다중 작업을 할 수 있다. (default: true)

setActive(false); // 아이템 선택 기능 비활성화
setActive(true); // 아이템 선택 기능 활성화

DragSelector.isActive

setActive()로 설정된 드래그 셀렉터 기능 활성화 여부를 리턴한다.

isActive(); // true or false

DragSelector.setDisable

드래그 셀렉터의 모든 UI처리를 중지시키거나 재개한다. 중지시, 중첩된 외부 레이어 클릭 등으로부터 드래그 셀렉터 선택영역에 영향을 받지 않도록 쉴드 레이어가 노출된다. (default: false)

setDisable(true); // UI 기능 중지
setDisable(false); // UI 기능 재개

DragSelector.isDisable

setDisable()로 설정된 드래그 셀렉터 기능 중지 여부를 리턴한다.

isDisable(); // true or false

DragSelector.setSelection

파라미터로 전달된 ID들에 해당하는 엘리먼트를 선택하거나 선택해제 한다. ID를 지정하지 않으면 모든 엘리먼트가 대상이 된다 (setAllSelection과 동일하게 동작).

setSelection(true, ['no_1', 'no_3']); // 해당 엘리먼트 선택
setSelection(false, ['no_5']); // 해당 엘리먼트 선택해제
setSelection(true); // 전체 선택
setSelection(true, []); // 전체 선택

DragSelector.setAllSelection

선택된 모든 엘리먼트를 선택 혹은 선택해제 한다.

setAllSelection(true); // 전체 선택
setAllSelection(false); // 전체 선택해제

DragSelector.destroy

드래그 셀렉터 라이브러리에서 사용한 자원 및 리스너 등을 모두 해제할 때 사용. 컴포넌트의 unmount 혹은 destroy 라이프사이클이 진행되는 시점에 호출해주면 된다.

destroy();

Change Log

프로젝트 변경사항은 CHANGELOG.md 파일 참조.

License

프로젝트 라이센스는 LICENSE 파일 참조.