본문으로 건너뛰기

에셋 등록

페이지에서 블록을 사용할 때 Blockstudio는 .css, .scss, .js로 끝나는 모든 파일을 자동으로 등록합니다. 다음 파일 이름 중 하나를 사용해 에셋 등록 방식을 지정할 수 있습니다. *는 원하는 문자열로 바꿀 수 있는 와일드카드입니다.

블록 CSS 및 SCSS 파일에서 %selector%는 블록 범위 래퍼 클래스로 확장됩니다. 따라서 파일이 범위 지정 에셋이 아니더라도 bs_get_scoped_class()가 적용되는 동일한 요소를 선택할 수 있습니다.

패턴 동작
*.(s)css 편집기와 프런트엔드에서 <link> 태그로 등록
*.inline.(s)css 편집기와 프런트엔드에서 콘텐츠를 인라인 <style> 태그에 등록
*.editor.(s)css 편집기에서만 <link> 태그로 등록
*.scoped.(s)css 편집기와 프런트엔드에서 범위가 지정된 콘텐츠를 인라인 <style> 태그에 등록
*.js 편집기와 프런트엔드에서 <script> 태그로 등록
*.inline.js 편집기와 프런트엔드에서 콘텐츠를 인라인 <script> 태그에 등록
*.editor.js 편집기에서만 <script> 태그로 등록
*.view.js 프런트엔드에서만 <script> 태그로 등록

참고

대시 표기법(*-inline.css, *-editor.css 등)은 이전 버전과의 호환성을 위해 계속 지원되지만 더 이상 권장되지 않습니다. 새 블록에는 점 표기법을 사용하세요.

인라인

인라인 스타일과 스크립트는 페이지 안에서 스타일 또는 스크립트 태그로 직접 렌더링되는 큰 장점이 있습니다. 별도로 요청해야 할 항목을 줄여 로딩 시간을 단축할 수 있습니다.

  • .js 파일은 body 끝에 인라인으로 삽입됩니다
  • .(s)css 파일은 head 끝에 인라인으로 삽입됩니다
  • 각 파일은 한 번만 인라인으로 삽입됩니다

작은 스타일시트 인라인 삽입

*.(s)css 파일은 기본적으로 링크되며, 파일마다 요청이 하나씩 발생합니다. assets.inlineLimit 설정을 사용하면 작은 스타일시트를 대신 인라인으로 출력합니다. 이는 WordPress가 자체 스타일에 적용하는 규칙을 따릅니다. 페이지의 외부 블록 스타일시트를 크기가 작은 순서대로 가져와, 누적 크기가 한도 이내인 동안 <style>로 출력합니다. 나머지 파일은 모두 <link> 태그를 유지합니다.

JSON
{
  "assets": {
    "inlineLimit": 40000
  }
}

한도는 바이트 단위이며 기본값인 0은 이 동작을 끕니다. 한도는 <link>가 불러올 컴파일된 파일의 크기를 측정하며, assets.minify.css가 켜져 있으면 축소된 파일을 기준으로 합니다. 크기에 따라 <link>와 <style> 중 무엇을 선택할지만 달라집니다. 각 태그는 <link>가 원래 있었을 위치에 그대로 있으므로 로드 순서와 캐스케이드는 바뀌지 않습니다. 요소의 id도 유지됩니다.

이 설정은 항상 인라인으로 삽입되는 *.inline.(s)css 및 *.scoped.(s)css 파일, 편집기 및 관리자 에셋, 가져온 JavaScript 모듈에서 추출한 스타일시트에는 적용되지 않습니다. 전역 스타일시트는 블록 스타일시트와 동일하게 계산됩니다. 인라인 삽입으로 파일 내용이 달라지는 경우에는 계속 링크된 상태로 유지됩니다.

  • URL 상대 경로를 url() 또는 @import에 포함하며, 연결된 경우 스타일시트를 기준으로, 인라인인 경우 페이지를 기준으로 경로가 확인됩니다. 절대 경로, 전체 URL, data: URI 및 # 프래그먼트는 괜찮습니다.
  • image-set()를 사용하거나 닫는 </style 시퀀스를 포함합니다.
  • CSS 이스케이프, HTML 주석 시작 기호 또는 @charset 선언을 포함합니다. 이런 파일은 URL 변경이나 문서 파싱 문제를 일으킬 위험을 피하기 위해 보수적으로 연결된 상태로 유지됩니다.

설정 필터를 사용하면 PHP에서 한도를 변경할 수 있습니다.

PHP
add_filter('blockstudio/settings/assets/inline_limit', fn() => 40000);

인라인으로 삽입된 CSS는 페이지 HTML의 일부가 됩니다. 스타일시트를 변경한 뒤에는 페이지 캐시를 비워야 하며, 브라우저가 페이지 간에 해당 바이트를 캐시할 수도 없습니다. 따라서 한도는 페이지당 총량으로 적용됩니다.

범위 지정

범위 지정 스타일도 인라인으로 삽입되지만, 블록마다 고유한 ID가 접두사로 붙습니다. 템플릿에 클래스를 추가하려면 bs_get_scoped_class 함수를 사용하세요.

PHP
<section class="hero <?php echo bs_get_scoped_class($b['name']); ?>">
  <h1 class="hero__title">Scope me!</h1>
</section>
CSS
%selector% {
  --hero-gap: var(--wp--preset--spacing--space-10);
}

%selector%.hero {
  border-bottom: 1px solid currentColor;
}

.hero__title {
  color: red;
}

위 설정은 다음과 같은 범위 지정 스타일을 생성합니다:

HTML
<style>
  .bs-62df71e6cc9a {
    --hero-gap: var(--wp--preset--spacing--space-10);
  }

  .bs-62df71e6cc9a.hero {
    border-bottom: 1px solid currentColor;
  }

  .bs-62df71e6cc9a .hero__title {
    color: red;
  }
</style>

<section class="hero bs-62df71e6cc9a">
  <h1 class="hero__title">Scope me!</h1>
</section>

범위 지정 파일의 일반 선택자는 계속 범위 지정 래퍼의 하위 요소를 대상으로 합니다. 래퍼 자체에 스타일을 적용하려면 %selector%를 사용하세요.

전역

블록별 에셋 외에도 전역 에셋을 등록할 수 있습니다. 블록이 있는지와 관계없이 모든 페이지에서 사용할 수 있습니다. 전역 에셋을 등록하려면 파일 이름에 global- 접두사를 추가합니다. 접미사(e.g. -inline)는 어떤 조합으로든 사용할 수 있습니다.

사용 가능한 조합은 다음과 같습니다:

  • global-styles.(s)css
  • global-styles.inline.(s)css
  • global-styles.editor.(s)css
  • global-styles.scoped.(s)css
  • global-scripts.js
  • global-scripts.inline.js
  • global-scripts.editor.js
  • global-scripts.view.js

관리자

관리자 에셋은 WordPress 관리자 영역에서만 등록됩니다. 관리자 에셋을 지정하려면 admin- 접두사를 사용합니다.

  • admin-styles.(s)css
  • admin-scripts.js

블록 편집기

블록 편집기 에셋은 블록 편집기에서만 등록됩니다. 블록 편집기 에셋을 지정하려면 block-editor- 접두사를 사용합니다.

  • block-editor-styles.(s)css
  • block-editor-scripts.js

참고

WordPress가 apiVersion가 3보다 낮게 등록된 클라이언트 측 블록 때문에 편집기 iframe을 비활성화하면 편집기 캔버스와 WordPress 관리자 UI가 같은 문서를 공유합니다. window, document, body, 휠 이벤트 또는 문서 스크롤에 연결되는 전역 또는 편집기 스크립트는 body.block-editor-page를 방지하거나 .interface-complementary-area 및 .interface-navigable-region 같은 WordPress 편집기 영역을 제외해야 합니다.

로드 순서

프런트엔드에서 에셋 자동 등록과 출력 버퍼링이 활성화되어 있으면 Blockstudio는 블록의 CSS <link> 및 <style> 태그를 wp_enqueue_style()에 등록하는 대신 버퍼링된 페이지의 닫는 </head> 태그 바로 앞에 추가합니다. 따라서 블록 CSS는 WordPress가 head에 이미 출력한 스타일시트 뒤에 배치됩니다. 여기에는 wp_enqueue_style()로 등록된 테마 및 플러그인 스타일도 포함되며, 등록 우선순위나 종속성과 관계없이 적용됩니다. 관리자 및 block-editor- 에셋은 대신 WordPress의 등록 시스템을 사용합니다.

중요도, 캐스케이드 레이어, 특이성이 같으면 블록 스타일시트가 테마 스타일시트보다 우선합니다. 이 순서를 바꾸려면 테마 규칙의 특이성을 높이거나 Blockstudio가 생성한 head에 blockstudio/render/head 필터를 사용해 테마 스타일시트를 추가하세요. 필터로 추가된 콘텐츠는 블록 에셋 뒤에 배치됩니다. 스타일시트가 두 번 로드되지 않도록 WordPress에서도 등록을 취소하세요.

PHP
add_action('wp_enqueue_scripts', function() {
  wp_dequeue_style('theme-overrides');
}, 100);

add_filter('blockstudio/render/head', function($head) {
  return $head . '<link rel="stylesheet" href="' . esc_url(get_theme_file_uri('overrides.css')) . '">';
});

head 필터는 Blockstudio가 페이지를 버퍼링할 때만 실행됩니다. 커스터마이저 미리보기에서는 버퍼링이 꺼져 있으며, blockstudio/buffer/enabled가 false를 반환할 때도 꺼져 있습니다. bs_is_buffering()을 사용하면 현재 어떤 경우인지 확인할 수 있으므로, 테마는 페이지가 버퍼링될 때 필터를 통해 스타일시트를 추가하고 그렇지 않을 때는 WordPress로 대기열에 추가할 수 있습니다. 이 값은 wp_enqueue_scripts부터 사용할 수 있으며 template_redirect 전에 false됩니다.

PHP
add_action('wp_enqueue_scripts', function() {
  $url = get_theme_file_uri('overrides.css');

  if (bs_is_buffering()) {
    add_filter('blockstudio/render/head', function($head) use ($url) {
      return $head . '<link rel="stylesheet" href="' . esc_url($url) . '">';
    });
    return;
  }

  wp_enqueue_style('theme-overrides', $url);
});

최종 문서의 순서를 다르게 재구성해야 한다면 blockstudio/buffer/output를 사용하세요.

등록 비활성화

assets/enqueue 설정으로 에셋 자동 등록을 비활성화할 수 있습니다. 모든 에셋 등록을 직접 처리하려는 경우에 유용합니다.

PHP
add_filter('blockstudio/settings', function($settings) {
  $settings['assets']['enqueue'] = false;
  return $settings;
});

블록별

블록 템플릿이 아무것도 반환하지 않으면 Blockstudio는 해당 블록의 에셋을 등록하지 않습니다. 특정 조건에서 등록을 비활성화할 때 편리합니다.

PHP

PHP
<?php
  if ( !$a['slides'] ) {
    // or return '';
    return false;
  }
?>

<div>my slider</div>

Twig

Twig
{% if not a.slides %}
  <div>my slider</div>
{% endif %}