[react-dom 번역] Common components (e.g. <div>)

출처: https://react.dev/reference/react-dom/components/common

Reference

Common components (e.g. `<div>`)

<div className="wrapper">Some content</div>

Props

이 특수 React props들은 모든 내장 컴포넌트에서 지원됩니다:

children: React 노드(JSX 엘리먼트, 문자열, 숫자, 포털, null/undefined/boolean, 또는 React 노드 배열). 컴포넌트 내부에 표시할 내용을 지정합니다. JSX를 사용할 때는 <div><span /></div>처럼 태그를 중첩하면 암묵적으로 children이 지정됩니다.
dangerouslySetInnerHTML: { __html: '<p>some html</p>' } 형태의 객체. DOM 노드의 innerHTML을 직접 덮어씁니다. 매우 주의해서 사용해야 합니다! 신뢰할 수 없는 데이터(예: 사용자 입력 등)에 사용하면 XSS 취약점이 발생할 수 있습니다.
ref: useRef, createRef, ref 콜백 함수, (레거시) 문자열 ref 모두 지원. 해당 DOM 노드에 직접 접근할 수 있습니다.
suppressContentEditableWarning: contentEditable={true}와 children을 동시에 쓸 때 React의 경고를 숨깁니다. 텍스트 에디터 라이브러리 등에서 수동 관리 시 사용합니다.
suppressHydrationWarning: 서버 렌더링 시 서버/클라이언트 내용 불일치 경고를 억제합니다. (escape hatch, 남용 금지)
style: { fontWeight: 'bold', margin: 20 } 형태의 객체. CSS 속성명은 camelCase(fontWeight 등)로 작성. 값이 숫자면 px 단위가 자동 적용됩니다. 동적 스타일에만 사용 권장, 정적 스타일은 className 사용 권장.

이 외에도 모든 내장 컴포넌트에서 지원하는 표준 DOM props:

accessKey, aria-*, autoCapitalize, className, contentEditable, data-*, dir, draggable, enterKeyHint, htmlFor, hidden, id, inputMode, lang 등 HTML 표준 속성 대부분 지원

주요 이벤트 핸들러

마우스: onClick, onMouseDown, onMouseUp, onMouseEnter, onMouseLeave, onMouseOver
포인터: onPointerDown, onPointerUp, onPointerEnter, onPointerLeave, onPointerMove
포커스: onFocus, onBlur
키보드: onKeyDown, onKeyUp
기타: onAnimationEnd, onTransitionEnd 등

사용법

CSS 스타일 적용

<div style={{ fontWeight: 'bold', margin: 20 }}>텍스트</div>

style 객체의 속성명은 camelCase로 작성해야 하며, 숫자 값은 px 단위가 자동 적용됩니다.

ref로 DOM 노드 조작

import { useRef } from 'react';

function Example() {
  const inputRef = useRef(null);
  function handleClick() {
    inputRef.current.focus();
  }
  return (
    <>
      <input ref={inputRef} />
      <button onClick={handleClick}>포커스 이동</button>
    </>
  );
}

ref 콜백 함수도 지원합니다.

dangerouslySetInnerHTML로 HTML 삽입

const markup = { __html: '<p>raw html</p>' };
return <div dangerouslySetInnerHTML={markup} />;

주의: 신뢰할 수 없는 데이터에 사용하면 XSS 공격에 취약합니다. 반드시 신뢰할 수 있는/필요 최소한의 데이터만 사용하세요.

마우스 이벤트 핸들링

<div
  onMouseEnter={e => console.log('onMouseEnter (parent)')}
  onMouseLeave={e => console.log('onMouseLeave (parent)')}
>
  <button
    onClick={e => console.log('onClick (first button)')}
    onMouseDown={e => console.log('onMouseDown (first button)')}
    onMouseEnter={e => console.log('onMouseEnter (first button)')}
    onMouseLeave={e => console.log('onMouseLeave (first button)')}
    onMouseOver={e => console.log('onMouseOver (first button)')}
    onMouseUp={e => console.log('onMouseUp (first button)')}
  >
    첫 번째 버튼
  </button>
  <button
    onClick={e => console.log('onClick (second button)')}
    onMouseDown={e => console.log('onMouseDown (second button)')}
    onMouseEnter={e => console.log('onMouseEnter (second button)')}
    onMouseLeave={e => console.log('onMouseLeave (second button)')}
    onMouseOver={e => console.log('onMouseOver (second button)')}
    onMouseUp={e => console.log('onMouseUp (second button)')}
  >
    두 번째 버튼
  </button>
</div>

포인터 이벤트 핸들링

<div
  onPointerEnter={e => console.log('onPointerEnter (parent)')}
  onPointerLeave={e => console.log('onPointerLeave (parent)')}
  style={{ padding: 20, backgroundColor: '#ddd' }}
>
  <div
    onPointerDown={e => console.log('onPointerDown (first child)')}
    onPointerEnter={e => console.log('onPointerEnter (first child)')}
    onPointerLeave={e => console.log('onPointerLeave (first child)')}
    onPointerMove={e => console.log('onPointerMove (first child)')}
    onPointerUp={e => console.log('onPointerUp (first child)')}
    style={{ padding: 20, backgroundColor: 'lightyellow' }}
  >
    첫 번째 자식
  </div>
  <div
    onPointerDown={e => console.log('onPointerDown (second child)')}
    onPointerEnter={e => console.log('onPointerEnter (second child)')}
    onPointerLeave={e => console.log('onPointerLeave (second child)')}
    onPointerMove={e => console.log('onPointerMove (second child)')}
    onPointerUp={e => console.log('onPointerUp (second child)')}
    style={{ padding: 20, backgroundColor: 'lightblue' }}
  >
    두 번째 자식
  </div>
</div>

포커스 이벤트 핸들링

<div
  tabIndex={1}
  onFocus={(e) => {
    if (e.currentTarget === e.target) {
      console.log('부모에 포커스');
    } else {
      console.log('자식에 포커스', e.target.name);
    }
    if (!e.currentTarget.contains(e.relatedTarget)) {
      // 자식 간 포커스 이동이 아닐 때만
      console.log('부모로 포커스 진입');
    }
  }}
  onBlur={(e) => {
    if (e.currentTarget === e.target) {
      console.log('부모 포커스 해제');
    } else {
      console.log('자식 포커스 해제', e.target.name);
    }
    if (!e.currentTarget.contains(e.relatedTarget)) {
      // 자식 간 포커스 이동이 아닐 때만
      console.log('부모에서 포커스 이탈');
    }
  }}
>
  <label>
    이름:
    <input name="firstName" />
  </label>
  <label>
    성:
    <input name="lastName" />
  </label>
</div>

키보드 이벤트 핸들링

<label>
  이름:
  <input
    name="firstName"
    onKeyDown={e => console.log('onKeyDown:', e.key, e.code)}
    onKeyUp={e => console.log('onKeyUp:', e.key, e.code)}
  />
</label>

트러블슈팅 및 보안 주의사항

dangerouslySetInnerHTML은 반드시 신뢰할 수 있는 데이터에만 사용하세요. 사용자 입력 등 외부 데이터에는 절대 사용하지 마세요(XSS 위험).
style은 동적 스타일에만 사용하고, 정적 스타일은 className을 권장합니다.
ref는 DOM 노드에 직접 접근이 필요할 때만 사용하세요.