bar-of-progress(한국어)

작고, 사용하기 쉬우며, 의존성이 없는 로딩 바 컴포넌트입니다.

Features

  1. 의존성 없음: 특정 프레임워크에도 연결되어 있지 않습니다.

  2. 작은 크기: Brotli로 압축 시 < 500 바이트 (gzip으로 압축 시 < 600 바이트).

  3. 사용하기 쉬움: 몇 줄만 추가하면 바로 사용할 수 있습니다. TypeScript도 지원합니다.


Installation

"npm i @badrap/bar-of-progress"는 Node.js 패키지 관리자인 npm을 사용해 "@badrap/bar-of-progress"라는 패키지를 설치하는 명령입니다. 이 패키지는 작고, 사용하기 쉽고, 어떠한 프레임워크에도 의존성이 없는 진행 바 컴포넌트를 제공합니다. 설치 후에는 몇 줄의 코드만으로 진행 바를 사용할 수 있습니다. TypeScript도 지원합니다.

주의 사항

"@badrap/bar-of-progress" 패키지의 사용에 관한 특별한 주의 사항이 명시되지 않았습니다. 하지만 일반적인 Node.js 패키지 사용시에 고려해야 할 몇 가지 주의 사항들이 있습니다:

  • Name
    호환성
    Type
    주의 사항
    Description

    "@badrap/bar-of-progress" 패키지가 현재 사용중인 Node.js의 버전과 호환되는지 확인해야 합니다.

  • Name
    의존성 관리
    Type
    주의 사항
    Description

    이 패키지가 설치되면 자동으로 package.json 파일에 추가됩니다. 이 파일을 통해 프로젝트의 의존성을 관리하고, 필요한 버전의 패키지가 항상 설치되도록 해야 합니다.

  • Name
    보안
    Type
    주의 사항
    Description

    npm 패키지를 설치할 때는 항상 신뢰할 수 있는 출처에서 제공하는 패키지인지 확인해야 합니다. 알려지지 않은 출처의 패키지는 코드에 보안 위험을 초래할 수 있습니다.

  • Name
    유지 보수
    Type
    주의 사항
    Description

    패키지의 최신 버전을 유지하고, 버전 업데이트시 발생할 수 있는 호환성 문제에 대비해야 합니다.

Installation

npm i @badrap/bar-of-progress

Usage

패키지를 불러오고 진행 바 인스턴스를 생성하세요.

  • Name
    .start() 메소드를 호출
    Type
    사용법
    Description

    .start() 메소드를 호출하여 진행 바를 보여주고 애니메이션을 시작하세요.

  • Name
    .finish() 메소드를 호출
    Type
    사용법
    Description

    .finish() 메소드를 호출하여 진행 바 애니메이션을 끝내세요.

주의 사항

  • Name
    빠른 작업
    Type
    주의 사항
    Description

    .start()가 호출되었을 때 진행 바가 바로 보이지 않습니다. 대신에, 매우 빠르게 완료되는 작업들이 진행 바를 표시하지 않도록 80밀리초의 유예 시간이 있습니다. 이 (및 다른) 행동을 수정할 수 있습니다, 커스터마이제이션을 참조하세요.

  • Name
    재사용
    Type
    주의 사항
    Description

    진행 바 인스턴스 사용 시 페이지 이동마다 애니메이션을 처음부터 시작합니다.

Usage

import ProgressBar from "@badrap/bar-of-progress";

const progress = new ProgressBar();

.start()

progress.start();

.finish()

  setTimeout(() => {
    progress.finish();
  }, 1000);

Customization

진행 바의 모양과 동작은 생성자 매개변수를 통해 (약간) 커스터마이징할 수 있습니다. 다음은 각 옵션과 그들의 기본값입니다:

설명

  • Name
    size
    Type
    설명서
    Description
    • 진행 바의 크기(두께)입니다.

    • 숫자 값은 픽셀(px)로 변환됩니다.

  • Name
    color
    Type
    설명서
    Description
    • 진행 바의 색상입니다.

    • 또한 바 주변의 발광 효과에도 사용 가능합니다.

  • Name
    class
    Type
    설명서
    Description
    • 진행 바 요소에 사용되는 클래스 이름입니다.
  • Name
    delay
    Type
    설명서
    Description
    • .start()를 호출한 후 진행 바 애니메이션이 시작하기 전까지 기다려야 하는 밀리초 수입니다.

Customization

const progress = new ProgressBar({

  // The size (height) of the progress bar.
  // Numeric values get converted to px.
  size: 2,

  // Color of the progress bar.
  // Also used for the glow around the bar.
  color: "#29e",

  // Class name used for the progress bar element.
  className: "bar-of-progress",

  // How many milliseconds to wait before the progress bar
  // animation starts after calling .start().
  delay: 80,
});

Example

Next.js의 라우팅 이벤트를 활용하여 페이지 전환 시에 진행 바 애니메이션을 보여주는 방식입니다. 여기서 사용된 Router.events는 Next.js의 Router 객체에서 제공하는 이벤트들을 나타냅니다.

추가 설명

  • Name
    routeChangeStart
    Type
    예시
    Description

    라우트 변경이 시작될 때 발생하는 이벤트입니다. 이 이벤트가 발생하면 progress.start()가 호출되어 진행 바 애니메이션이 시작됩니다.

  • Name
    routeChangeComplete
    Type
    예시
    Description

    라우트 변경이 완료될 때 발생하는 이벤트입니다. 이 이벤트가 발생하면 progress.finish()가 호출되어 진행 바 애니메이션이 끝납니다.

  • Name
    routeChangeError
    Type
    예시
    Description

    라우트 변경 도중에 에러가 발생했을 때 발생하는 이벤트입니다. 이 이벤트가 발생하면 progress.finish()가 호출되어 진행 바 애니메이션이 끝납니다.


useEffect는 React의 Hook으로서, 컴포넌트가 마운트되었을 때(또는 router.events가 변경되었을 때) 그 내부의 코드를 실행합니다. 이 코드 내부에서는 위에서 설명한 각 이벤트에 대해 핸들러를 등록했습니다.

또한, useEffect는 정리(clean-up) 함수를 반환합니다. 이 함수는 컴포넌트가 언마운트 될 때나 다음번 useEffect가 실행되기 전에 호출됩니다. 코드를 통해 메모리 누수를 방지했습니다.

_app.js

Router.events.on('routeChangeStart', onRouteChange)

Router.events.on('hashChangeStart', onRouteChange)

const progress = new ProgressBar({
size: 4,
color: '#F7AB0A',
className: 'z-50',
delay: 100,
})

Router.events.on('routeChangeStart', () => progress.start())
Router.events.on('routeChangeComplete', () => progress.finish())
Router.events.on('routeChangeError', () => progress.finish())

useEffect(() => {
const handleRouteChangeStart = () => {
  progress.start()
}

const handleRouteChangeComplete = () => {
  progress.finish()
}

const handleRouteChangeError = () => {
  progress.finish()
}

router.events.on('routeChangeStart', handleRouteChangeStart)
router.events.on('routeChangeComplete', handleRouteChangeComplete)
router.events.on('routeChangeError', handleRouteChangeError)

return () => {
  router.events.off('routeChangeStart', handleRouteChangeStart)
  router.events.off('routeChangeComplete', handleRouteChangeComplete)
  router.events.off('routeChangeError', handleRouteChangeError)
}

}, [router.events])