커스텀 컴포넌트 등록 및 사용

이 문서에서는 Hops에서 커스텀 컴포넌트를 등록하고 페이지에서 실제로 사용하는 방법을 설명합니다.

커스텀 컴포넌트 관리화면 접근하기

커스텀 컴포넌트를 생성하고 관리하려면 먼저 커스텀 컴포넌트 관리 화면에 접근해야 합니다.

1. 왼쪽 사이드바 메뉴에서 커스텀 컴포넌트 메뉴를 선택합니다.

새 커스텀 컴포넌트 생성하기

새로운 커스텀 컴포넌트를 생성하는 방법은 다음과 같습니다:

1. 커스텀 컴포넌트 목록에서 오른쪽 상단의 [+] 버튼을 클릭합니다.
2. 생성 옵션을 선택합니다:
   • 빈 컴포넌트 추가: 빈 템플릿으로 시작
   • 컴포넌트 템플릿 추가: 기본 샘플 코드가 포함된 템플릿으로 시작
3. 선택 후 컴포넌트가 추가되며 에디터 화면으로 이동합니다.

커스텀 컴포넌트 에디터 사용하기

커스텀 컴포넌트 에디터는 크게 세 영역으로 구성되어 있습니다:

1. 미리보기: 작성한 컴포넌트를 실시간으로 확인하는 영역
2. 코드 에디터: React 컴포넌트 코드를 작성하는 영역
3. 디버그 정보: 컴포넌트의 실행 결과, 로그를 표시하는 영역

컴포넌트 정보 설정하기

컴포넌트의 기본 정보를 설정합니다. 코드 에디터 영역에서 상단의 톱니바퀴 모양 아이콘을 누르면 확인할 수 있습니다:

• 표시 이름: 커스텀 컴포넌트 목록과 슬래시 컴포넌트 목록 등에서 표시되는 커스텀 컴포넌트의 이름
• 식별자: 컴포넌트의 고유 식별자 (영문, 숫자, _ 사용, 영문자로만 시작 가능)
• 설명: 컴포넌트의 용도, 특징 및 사용 사례 (동료 개발자들의 이해를 돕기 위한 용도로 활용 가능)
• 기본 props: 컴포넌트에 전달되는 초기 속성값 (React 컴포넌트의 props로 전달)

기본 props 설정하기

기본 props 섹션에서 컴포넌트의 기본 프로퍼티 값을 설정할 수 있습니다:

{
  "label": "이름",
  "defaultValue": "김홉스"
}

이 설정은 페이지 에디터에서 컴포넌트를 처음 추가할 때 기본 props 프로퍼티의 기본 값으로 사용됩니다.

내장된 props 활용

모든 커스텀 컴포넌트에는 기본적으로 제공되는 프로퍼티들이 있습니다. 예를 들어 name 프로퍼티는 컴포넌트의 식별자로 사용되며, isHidden 프로퍼티를 통해 페이지에서 컴포넌트를 동적으로 숨기거나 표시할 수 있습니다.

커스텀 컴포넌트를 에디터에 추가할 때 설정할 수 있습니다.

코드 작성하기

에디터에서 React 기반의 코드를 작성합니다. 코드 작성 방법에 대한 자세한 내용은 커스텀 컴포넌트 작성하기 문서를 참조하세요.

기본 구조는 다음과 같습니다:

import { memo, ReactElement } from 'react';

import { CustomComponentRenderProps, useComponentState, useLogger } from '@hops/custom-component';
import { FormControl, FormLabel, Input } from '@hops/design-system';

// 컴포넌트 Props 타입 정의
interface OwnProps {
  label: string;
  defaultValue: string;
}

// 컴포넌트 구현
function Component(props: CustomComponentRenderProps<OwnProps>): ReactElement {
  // 컴포넌트 프로퍼티 읽기
  const { defaultValue, label } = props;

  // 로거 사용
  const logger = useLogger();

  // 상태 관리
  const [value, setValue] = useComponentState<string>('inputValue', defaultValue);

  return (
    <FormControl>
      <FormLabel>{label}</FormLabel>
      <Input
        value={value}
        onChange={(e) => {
          setValue(e.target.value);
          logger.debug(`onChange called: ${e.target.value}`);
        }}
      />
    </FormControl>
  );
}

export default memo(Component);

테스트 props 설정하기

디버그 정보 영역에서 상단의 톱니바퀴 모양 아이콘을 누르면 테스트 props를 설정할 수 있습니다.

이 설정은 컴포넌트 에디터의 미리보기 섹션에서만 사용되며, 실제 페이지에는 적용되지 않습니다.

테스트 props 섹션에서는 미리보기에 사용될 프로퍼티 값을 JSON 형식으로 설정할 수 있습니다:

{
  "label": "Test Label",
  "defaultValue": "Test Value"
}

컴포넌트 저장 및 배포

작업을 완료한 후:

1. 오른쪽 상단의 저장 버튼을 클릭하여 컴포넌트를 저장합니다. (작업 중 변경 사항은 자동 저장)

페이지 에디터에서 커스텀 컴포넌트 사용하기

저장한 커스텀 컴포넌트는 페이지 에디터에서 일반 컴포넌트와 동일하게 사용할 수 있습니다:

에디터에서 바로 사용

1. 페이지 에디터에서 /를 입력한 뒤 커스텀 컴포넌트의 표시이름과 식별자로 검색이 가능합니다.
2. 엔터 키를 누르면 입력한 커스텀 컴포넌트가 추가됩니다.

컴포넌트 목록에서 사용

1. 좌측 사이드바에서 컴포넌트 버튼을 선택합니다.
2. 컴포넌트 목록에서 맨 아래의 커스텀 컴포넌트 그룹을 찾습니다.
3. 사용하려는 커스텀 컴포넌트를 드래그해 에디터에 놓습니다.

커스텀 컴포넌트 기본 Props 설정

페이지 에디터에서 커스텀 컴포넌트를 선택하면 오른쪽 프로퍼티 패널에서 기본 props를 설정할 수 있습니다:

1. 코드를 입력해서 커스텀 컴포넌트에 props 전달 가능
2. 컴포넌트 및 워크플로우 상태를 입력하여 동적인 값 사용 가능

커스텀 컴포넌트 상태 사용하기

커스텀 컴포넌트 구현 시 useComponentState로 정의한 상태는 외부에서도 접근할 수 있습니다.

// 상태 관리
const [value, setValue] = useComponentState<string>('inputValue', defaultValue);

필요한 곳에서 컴포넌트_이름.상태_이름 형식의 접근자로 커스텀 컴포넌트의 상태에 접근합니다.

customComponent1.inputValue;

커스텀 컴포넌트 업데이트 및 관리

컴포넌트 업데이트

1. 커스텀 컴포넌트 목록 화면에서 수정할 컴포넌트를 클릭합니다.
2. 에디터에서 필요한 변경 사항을 적용합니다.
3. 변경 사항은 자동으로 저장됩니다.

컴포넌트 복제

기존 컴포넌트를 기반으로 새 컴포넌트를 만들려면:

1. 커스텀 컴포넌트 목록에서 복제할 컴포넌트의 옵션 메뉴(⋮)를 클릭합니다.
2. 복제 옵션을 선택합니다.
3. 새 이름과 제목을 입력하고 복제를 완료합니다.

컴포넌트 삭제

더 이상 사용하지 않는 컴포넌트를 삭제하려면:

1. 커스텀 컴포넌트 목록에서 삭제할 컴포넌트의 옵션 메뉴(⋮)를 클릭합니다.
2. 삭제 옵션을 선택합니다.
3. 확인 대화 상자에서 확인을 클릭하여 삭제를 완료합니다.

경고

컴포넌트를 삭제하면 해당 컴포넌트를 사용하는 모든 페이지에서 오류가 발생할 수 있습니다. 삭제 전에 해당 컴포넌트를 사용하는 페이지가 없는지 확인하세요.

커스텀 컴포넌트에 대해 더 자세히 알아보려면 다음 문서를 참조하세요:

• 커스텀 컴포넌트 작성하기
• API 레퍼런스
• 고급 사용법