본문으로 건너뛰기

캔버스

캔버스는 축소된 상태에서 Blockstudio로 관리되는 모든 페이지를 Figma처럼 한눈에 보여줍니다. 각 페이지는 가로 한 줄에 실시간 iframe 아트보드로 표시됩니다. 트랙패드로 이동하고, 핀치 또는 Ctrl+스크롤로 확대·축소하세요.

활성화

캔버스는 숨겨진 관리자 페이지로 제공됩니다. 다음 위치로 이동하세요:

코드
/wp-admin/admin.php?page=blockstudio-canvas

dev.canvas.enabled이 true이고 현재 사용자에게 edit_posts 권한이 있어야 페이지에 액세스할 수 있습니다.

설정

테마의 blockstudio.json에서 캔버스를 활성화하고 동작을 구성합니다:

JSON
{
  "dev": {
    "canvas": {
      "enabled": true,
      "adminBar": false
    }
  }
}
속성 유형 기본값 설명
enabled boolean false 캔버스 기능을 활성화합니다.
adminBar boolean true 아트보드 iframe 안에 WordPress 관리자 표시줄을 표시합니다. 더 깔끔하게 미리 보려면 false로 설정하세요.

두 설정은 필터로도 사용할 수 있습니다:

PHP
add_filter('blockstudio/settings/dev/canvas/enabled', '__return_true');
add_filter('blockstudio/settings/dev/canvas/admin_bar', '__return_false');

보기

오른쪽 상단의 드롭다운 메뉴에서 보기를 전환합니다.

  • 페이지: Blockstudio로 관리되는 모든 페이지를 가로 한 줄에 전체 너비 아트보드로 표시합니다.
  • 블록: 등록된 Blockstudio 블록을 모두 격자에 표시하고 각각 기본 속성값으로 렌더링합니다.

공개 인벤토리 및 문서 API

Canvas는 동일하게 등록된 콘텐츠를 재구성하지 않고도 Blockstudio의 검색 또는 렌더링 로직을 사용할 수 있어야 하는 도구를 위해 버전이 지정된 소비자 중립적인 PHP 계약을 제공합니다:

PHP
use Blockstudio\Canvas;

$all = Canvas::inventory();

$changed = Canvas::inventory([
  'blocks' => ['theme/hero'],
  'pages' => ['about'],
]);

$documents = Canvas::documents([
  'patterns' => ['theme/featured'],
  'templates' => ['front-page'],
]);

현재 버전은 Canvas::SCHEMA_VERSION로 제공됩니다. 인벤토리 결과에는 다음이 포함됩니다:

  • inventory: 정규화된 pages, blocks, patterns, templates, parts 및 공개 ui 계열 예제
  • order: 유형 간에 안정적으로 유지되는 표시 순서
  • sources: 각 레코드의 출처 정보가 포함된 정확한 선택 소스 경로. 페이지 레코드의 source는 안정적인 소스 ID이고 path은 실제 렌더링 템플릿 경로입니다.
  • warnings 및 errors: 출력 결과 대신 구조화된 문제
  • deleted: 더 이상 존재하지 않는 요청 ID
  • selection: 정규화된 선택 항목과 대상 지정 여부

Canvas::documents()은 선택된 레코드마다 완전한 렌더링 문서를 하나씩 추가합니다. 각 문서에는 본문, 조합된 HTML, 종속성까지 포함된 블록 이름, 정확한 CSS 및 JavaScript, 모듈, 상호작용 부트스트랩, 번들된 UI 전역 및 Tailwind 출력이 포함됩니다. 페이지 문서는 의미에 맞는 <main> 콘텐츠 래퍼를 사용하며, 호출자는 공통 Render 문서 옵션으로 이를 재정의하거나 사용 중지할 수 있습니다. 선택된 각 페이지는 자체 복원된 프런트엔드 WordPress 컨텍스트에서 렌더링되므로 쿼리 조건문, body 클래스 필터, 쇼트코드, 레이아웃, 리디렉션 및 wp_enqueue_scripts 콜백은 Canvas 결과를 요청한 관리자 또는 REST 요청이 아니라 해당 페이지를 기준으로 동작합니다. 호출자가 제공한 body 클래스는 페이지의 컨텍스트 클래스와 병합되며 프런트엔드 enqueue 레지스트리는 문서별로 분리됩니다. Canvas는 공개 WordPress 함수 이름으로 이러한 라이프사이클 콜백을 확인하므로 Blockstudio을 Composer 또는 이동된 애플리케이션 네임스페이스를 통해 로드해도 동일한 컨텍스트가 유지됩니다.

정확한 선택 동작

선택은 엄격하게 적용됩니다:

  • 인식된 유형 키가 없으면 모든 유형을 로드합니다.
  • true, null 또는 "*"이면 해당 유형의 모든 레코드를 로드합니다.
  • 문자열 또는 목록을 지정하면 정확히 일치하는 ID, 이름, 슬러그, 경로 또는 소스 경로만 로드합니다.
  • 빈 문자열/목록 또는 false이면 해당 유형의 항목을 로드하지 않습니다.
  • 유형 키를 하나라도 지정하면 생략된 유형은 검색, 동기화, 렌더링 또는 컴파일되지 않습니다.

따라서 대규모 프로젝트에서도 변경된 항목만 요청해 안전하게 처리할 수 있습니다. 기존 블록과 페이지는 정식 레지스트리를 통해 확인됩니다. 프런트엔드 요청에 저장된 페이지 프로젝션만 로드된 경우 Canvas는 읽기 전용 소스 검색을 수행하고 콘텐츠를 동기화하지 않은 채 일치하는 게시물 ID와 퍼머링크를 병합합니다. 논리적 검색 소스가 소스 기반 레지스트리를 먼저 채우는 경우에도 동일한 ID 병합이 적용되므로 컨텍스트 페이지 렌더링은 일치하는 관리 대상 WordPress 게시물을 계속 사용합니다. 새 라이브 세션 토폴로지는 변경된 디렉터리 주변에서만 검색되며 선택된 패턴 및 Site Editor 템플릿 소스는 선택 후에만 컴파일됩니다.

REST 새로고침 엔드포인트도 기존 blocks 및 pages 쿼리 매개변수에 같은 규칙을 적용합니다. 예를 들어 ?blocks=theme/hero은 해당 블록만 반환하고 페이지는 반환하지 않습니다. 혼합 응답을 원하면 두 매개변수를 모두 사용하세요. 두 매개변수 없이 엔드포인트를 호출하면 기존 전체 응답이 유지됩니다.

라이브 모드

라이브 모드는 Server-Sent Events(SSE)를 사용해 파일 변경을 감지하고 캔버스를 실시간으로 업데이트합니다. 블록 템플릿, 페이지 템플릿 또는 스타일시트를 편집하면 해당 아트보드가 약 1초 이내에 자동으로 새로고침됩니다.

드롭다운 메뉴에서 라이브 모드를 전환합니다. 활성화되면 초록색 표시기가 깜박입니다. 설정은 localStorage를 통해 세션이 바뀌어도 유지됩니다.

라이브 모드는 블록 및 페이지 디렉터리 내의 .php, .json, .css, .scss, .js, .twig 및 .html 파일 변경을 추적합니다. 알려진 편집은 등록된 블록이나 페이지만 새로고침합니다. 완전히 새로운 블록이나 페이지가 생기면 해당 디렉터리 범위의 토폴로지 검사를 한 번 수행하므로 열린 라이브 세션 중 콘텐츠를 만들어도 관련 없는 소스를 다시 검색하지 않고 반영됩니다.

포커스 모드

아트보드 레이블을 클릭하면 포커스 모드로 전환됩니다. 선택한 아트보드가 전체 너비로 뷰포트를 채우며 세로로 스크롤할 수 있습니다. 개요로 돌아가려면 Escape를 누르거나 닫기 버튼을 클릭하세요.

컨트롤

동작 입력
이동 스크롤 / 트랙패드 두 손가락 드래그
확대/축소 Ctrl+스크롤 또는 핀치
화면에 맞추기 드롭다운 메뉴
100%로 확대 드롭다운 메뉴
아트보드에 포커스 아트보드 레이블 클릭
포커스 종료 Escape / 닫기 버튼

보안

캔버스 스크립트와 페이지 데이터는 모든 조건이 충족될 때만 로드됩니다:

  • dev.canvas.enabled 설정이 true입니다.
  • 현재 사용자에게 edit_posts 권한이 있습니다.

일반 방문자에게는 캔버스 스크립트나 페이지 메타데이터가 표시되지 않습니다.