본문으로 건너뛰기

구성 요소

Blockstudio는 모든 빌드에 59 UI 구성 요소를 포함합니다. 구성 요소는 자동으로 등록되고 디자인 토큰으로 스타일이 지정되며, 다른 블록과 동일한 태그 구문으로 작성됩니다.

Blockstudio 7.3에는 WordPress 인터랙티비티 API로 구동되는 헤드리스 UI 블록 묶음이 포함되어 있습니다. 이 블록은 bsui/* 네임스페이스에 등록되며 템플릿, 파일 기반 페이지, 패턴, 글 콘텐츠에서 조합할 수 있습니다.

참고

UI 컴포넌트 세트, 이름, 동작, 프로젝트 사용 패턴에 대한 의견을 수렴하는 동안 해당 컴포넌트는 베타 버전으로 제공됩니다. 7.3에서 사용해 볼 수 있지만, 안정화로 표시되기 전에 API 인터페이스가 다듬어질 수 있습니다.

UI 컴포넌트 활성화

번들 UI 컴포넌트는 선택 기능입니다. 테마의 blockstudio.json에서 활성화하세요.

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "ui": {
    "enabled": true
  }
}

필터를 사용해 활성화할 수도 있습니다.

PHP
add_filter('blockstudio/settings/ui/enabled', '__return_true');

활성화하면 Blockstudio가 includes/ui/blocks의 번들 컴포넌트 라이브러리를 등록합니다.

공개 인벤토리 및 예제

번들 구현 블록은 일반 bsui/* 등록 항목으로 유지되지만, 컴포넌트 갤러리를 만들 때는 공개 패밀리 인벤토리를 사용해야 합니다.

PHP
use Blockstudio\Ui;

$families = Ui::inventory();
$examples = Ui::examples();

Ui::inventory()는 모든 복합 컴포넌트를 공개 루트별로 그룹화하고 각 패밀리에 필요한 구현 등록 항목을 나열합니다. Ui::examples()는 기본 데이터와 예시 데이터가 포함된 결정적이고 정규화된 선언을 추가합니다. 필수 루트 및 자식 관계를 유지하므로 결과를 Blockstudio\Render::document()에 바로 전달할 수 있습니다.

공개 Canvas 인벤토리는 ui 유형으로 이러한 예제를 노출하고, 일반 blocks 유형에서는 번들 구현 등록 항목을 제외합니다. 그 결과 내부 루트, 트리거, 팝업, 레이어 조각의 모음 대신 공개 컴포넌트 패밀리마다 완전한 예제 하나를 제공합니다.

이미 렌더링된 문서를 조립할 때 Ui::global_assets($block_names, $html)는 선택한 출력에서 UI 컴포넌트를 실제로 사용하는 경우에만 정확한 번들 전역 스타일과 스크립트를 반환합니다.

렌더링

일반 블록 태그 구문을 사용하세요.

HTML
<block name="bsui/button" label="Save" variant="default"></block>

더 짧은 <bs:> 구문도 사용할 수 있습니다.

HTML
<bs:bsui-button label="Save" variant="default" />

Blockstudio 템플릿에서는 블록 태그가 자동으로 렌더링됩니다. 파일 기반 페이지와 패턴에서는 네이티브 WordPress 블록으로 동기화됩니다. 글 콘텐츠나 위젯 영역에서 UI 컴포넌트를 직접 렌더링하려면 페이지 수준 블록 태그를 활성화하세요.

JSON
{
  "ui": {
    "enabled": true
  },
  "blockTags": {
    "enabled": true,
    "allow": ["bsui/*", "app/*"]
  }
}

기본 컴포넌트

간단한 컴포넌트는 단일 블록으로 렌더링됩니다.

HTML
<block name="bsui/button" label="Continue" variant="default"></block>
<block name="bsui/badge" label="Beta"></block>
<block
  name="bsui/input"
  nameAlt="email"
  type="email"
  placeholder="Email"
></block>
<block name="bsui/textarea" name="message" placeholder="Message"></block>
<block name="bsui/spinner"></block>

속성은 각 컴포넌트의 block.json 속성에 직접 매핑됩니다. 예를 들어 bsui/button은 label, icon, iconPosition, href, variant, size, disabled을 지원합니다.

PHP
bs_render_block([
  'name' => 'bsui/button',
  'data' => [
    'label' => 'Continue',
    'icon' => [
      'set' => 'heroicons',
      'subSet' => 'outline',
      'icon' => 'arrow-right',
    ],
    'iconPosition' => 'right',
  ],
]);

복합 컴포넌트

많은 UI 컴포넌트는 복합 블록입니다. 루트 블록이 상태를 관리하고 자식 블록이 부모를 지정합니다.

탭

HTML
<block name="bsui/tabs" defaultValue="tab1">
  <block name="bsui/tabs-list">
    <block name="bsui/tabs-trigger" value="tab1" title="Features"></block>
    <block name="bsui/tabs-trigger" value="tab2" title="Pricing"></block>
    <block name="bsui/tabs-trigger" value="tab3" title="FAQ"></block>
  </block>
  <block name="bsui/tabs-panel" value="tab1">
    <p>Features content.</p>
  </block>
  <block name="bsui/tabs-panel" value="tab2">
    <p>Pricing content.</p>
  </block>
  <block name="bsui/tabs-panel" value="tab3">
    <p>FAQ content.</p>
  </block>
</block>

대화상자

HTML
<block name="bsui/dialog">
  <block name="bsui/dialog-trigger" label="Open Dialog"></block>
  <block name="bsui/dialog-backdrop"></block>
  <block name="bsui/dialog-popup">
    <p>Dialog content.</p>
    <block name="bsui/dialog-close" label="Close"></block>
  </block>
</block>

선택 메뉴

HTML
<block name="bsui/select" placeholder="Choose a fruit" nameAlt="fruit">
  <block name="bsui/select-trigger"></block>
  <block name="bsui/select-popup">
    <block name="bsui/select-option" value="apple" label="Apple"></block>
    <block name="bsui/select-option" value="banana" label="Banana"></block>
    <block name="bsui/select-option" value="cherry" label="Cherry"></block>
  </block>
</block>

폼 필드

HTML
<block name="bsui/form" block="contact/form" successMessage="Thank you!">
  <block name="bsui/field">
    <block name="bsui/field-label" text="Email"></block>
    <block name="bsui/input" nameAlt="email" type="email"></block>
    <block name="bsui/field-error"></block>
  </block>
</block>

사용 가능한 블록

번들 UI 라이브러리에는 다음이 포함됩니다.

영역 블록
레이아웃 bsui/aspect-ratio, bsui/card, bsui/separator, bsui/stack, bsui/table
동작 bsui/button, bsui/button-group, bsui/toggle, bsui/toggle-group, bsui/toolbar
입력 bsui/checkbox, bsui/color-picker, bsui/date-input, bsui/file-upload, bsui/input, bsui/number-field, bsui/otp-input, bsui/password-input, bsui/phone-input, bsui/radio-group, bsui/rating, bsui/select, bsui/slider, bsui/switch, bsui/textarea, bsui/time-picker
오버레이 bsui/alert-dialog, bsui/dialog, bsui/drawer, bsui/menu, bsui/menubar, bsui/popover, bsui/preview-card, bsui/tooltip
탐색 bsui/accordion, bsui/breadcrumb, bsui/carousel, bsui/collapsible, bsui/context-menu, bsui/navigation-menu, bsui/pagination, bsui/tabs
피드백 bsui/badge, bsui/kbd, bsui/meter, bsui/progress, bsui/skeleton, bsui/spinner, bsui/text, bsui/toast
폼 bsui/field, bsui/field-group, bsui/form

복합 컴포넌트는 bsui/dialog-trigger, bsui/dialog-popup, bsui/tabs-list, bsui/tabs-trigger, bsui/tabs-panel, bsui/select-trigger, bsui/select-popup, bsui/select-option 등의 자식 블록도 노출합니다.

스타일 지정

UI 컴포넌트에는 --bs-ui-* 접두사를 사용하는 자체 CSS 사용자 지정 속성이 포함됩니다. 테마 CSS에서 재정의할 수 있습니다.

CSS
:root {
  --bs-ui-radius: 0.5rem;
  --bs-ui-primary: oklch(0.45 0.18 260);
  --bs-ui-primary-foreground: white;
}

컴포넌트는 동작 면에서 헤드리스이지만, 바로 사용할 수 있도록 적절한 기본값을 제공합니다. 먼저 토큰을 재정의한 다음 필요한 경우 컴포넌트별 CSS를 추가하세요.

번들 컴포넌트 CSS는 이름이 지정된 bsui 캐스케이드 레이어에 출력됩니다. 레이어가 없는 테마 CSS는 !important 없이 컴포넌트 규칙을 재정의할 수 있습니다.

CSS
.button-brand {
  background: var(--brand-primary);
}

사용자 지정 bsui/button 변형을 추가하려면 기존 속성 필터로 선택 옵션을 추가하고 blockstudio/ui/button/variants-style를 사용해 변형 CSS을 제공하세요.

PHP
add_filter('blockstudio/blocks/attributes', function($attribute, $block) {
  if (($block['name'] ?? '') === 'bsui/button' && ($attribute['id'] ?? '') === 'variant') {
    $attribute['options'][] = [
      'label' => 'Brand',
      'value' => 'brand',
    ];
  }

  return $attribute;
}, 10, 2);

add_filter('blockstudio/ui/button/variants-style', function($css) {
  return $css . '
[data-bsui-button][data-variant="brand"] {
  background: var(--brand-primary);
  color: white;
}';
});

모든 구성 요소

아코디언 한 번에 패널 하나씩 펼쳐지는 섹션입니다. 알림 대화상자 흐름을 중단하고 닫기 전에 응답이 필요한 모달입니다. 가로세로 비율 콘텐츠를 고정된 너비 대 높이 비율로 유지합니다. 아바타 로드에 실패하면 이니셜을 표시하는 사용자 이미지입니다. 배지 상태, 개수, 카테고리를 나타내는 작은 레이블입니다. 탐색 경로 현재 페이지의 계층 구조상 위치를 보여줍니다. 버튼 강조 수준별 변형을 제공하는 액션 트리거입니다. 버튼 그룹 관련 버튼을 하나의 분할 컨트롤로 묶습니다. 캘린더 날짜 하나를 선택하는 달력 그리드입니다. 카드 헤더, 본문, 푸터를 묶는 표면입니다. 캐러셀 키보드를 지원하는 스와이프 가능한 슬라이드 트랙입니다. 체크박스 불확정 상태도 지원하는 이진 선택 컨트롤입니다. 접기/펼치기 콘텐츠 영역 하나를 숨기거나 표시합니다. 색상 선택기 색상을 선택해 주변 양식과 함께 제출합니다. 콤보박스 입력하는 동안 옵션 목록을 필터링하는 텍스트 입력란입니다. 컨텍스트 메뉴 마우스 오른쪽 클릭 위치를 기준으로 표시되는 액션입니다. 날짜 입력란 날짜 선택기 없이 날짜를 입력하는 마스크 필드입니다. 대화상자 집중 작업 및 확인에 사용하는 모달 레이어입니다. 드로어 화면의 어느 가장자리에서든 밀려 들어오는 패널입니다. 필드 컨트롤 하나에 레이블, 설명, 오류 메시지를 연결합니다. 필드 그룹 관련 필드를 공통 제목 아래에 묶습니다. 파일 업로드 여러 파일을 지원하는 드롭 영역 및 파일 선택기입니다. 양식 페이지를 새로고침하지 않고 필드를 제출하고 성공 여부를 알립니다. 입력 일반적인 입력 유형을 모두 지원하는 한 줄 텍스트 필드입니다. 키보드 단축키 키보드 단축키를 별도의 키캡에 표시합니다. 라벨 레이블이 있는 모든 컴포넌트가 공유하는 컨트롤 캡션입니다. 메뉴 트리거에 고정된 액션 드롭다운 목록입니다. 메뉴 모음 데스크톱 애플리케이션처럼 메뉴를 가로 막대에 표시합니다. 미터 정해진 범위 안에서 측정값을 표시합니다. 탐색 메뉴 중첩 링크와 호버 패널을 제공하는 사이트 탐색 메뉴입니다. 숫자 필드 스테퍼와 범위 제한을 제공하는 숫자 입력란입니다. OTP 입력 일회용 암호를 입력하기 위한 분할 상자입니다. 페이지 매김 이전, 다음 및 생략 표시가 있는 페이지 링크입니다. 비밀번호 입력 표시 여부를 전환할 수 있는 비밀번호 입력란입니다. 전화번호 입력 국가 선택 및 형식 지정을 지원하는 전화번호 입력란입니다. 팝오버 트리거에 고정되고 바깥을 클릭하면 닫히는 리치 콘텐츠입니다. 미리보기 카드 링크가 가리키는 내용을 미리 보여주는 호버 카드입니다. 진행률 작업이 얼마나 진행되었는지 보여줍니다. 라디오 그룹 정확히 하나의 옵션을 선택할 수 있는 옵션 집합입니다. 평점 점수를 기록하는 별점 컨트롤입니다. 스크롤 영역 스타일이 적용된 오버레이 스크롤바가 있는 스크롤 컨테이너입니다. 선택 옵션 목록에서 선택하는 드롭다운입니다. 구분선 콘텐츠 또는 컨트롤 그룹을 나누는 선입니다. 스켈레톤 콘텐츠가 로드되는 동안 표시되는 플레이스홀더 모양입니다. 슬라이더 트랙을 따라 드래그해 값이나 범위를 선택합니다. 공간 간격 척도에 따른 고정된 세로 리듬 단위입니다. 스피너 예상 소요 시간을 알 수 없는 진행 중 작업을 나타냅니다. 스택 일정한 간격으로 자식 요소를 행이나 열에 배치합니다. 스위치 설정을 즉시 적용하고 전환합니다. 표 선택적으로 정렬 및 줄무늬 표시를 지원하는 표 형식 데이터입니다. 탭 같은 공간을 차지하는 패널 간에 전환합니다. Text 지정한 크기와 의미 요소로 본문 텍스트를 렌더링합니다. 텍스트 영역 행 수에 따라 높이가 늘어나는 여러 줄 텍스트 필드입니다. 시간 선택기 지정된 간격으로 하루 중 시간을 선택합니다. 토스트 제공자 화면 모서리에 일시적인 알림을 표시합니다. 전환 켜짐 상태를 나타내도록 눌린 상태로 유지되는 버튼입니다. 토글 그룹 하나 또는 여러 옵션을 선택할 수 있는 토글 집합입니다. 도구 모음 컨트롤 사이에서 포커스를 이동할 수 있는 컨트롤 행입니다. 툴팁 마우스를 올리거나 포커스할 때 표시되는 짧은 도움말입니다.