Przejdź do treści

Własne bloki w 3 plikach

Bez JavaScript, etapu budowania i zbędnego kodu.

Definiuj pola w JSON

Dodaj klucz blockstudio do block.json. Zdefiniuj atrybuty z typami, takimi jak text, toggle i color. Blockstudio automatycznie generuje edytor UI z 27 typami pól — od pól tekstowych po repeatery i edytory kodu — a także typami pól rejestrowanymi samodzielnie.

Pełna obsługa schematu JSON zapewnia uzupełnianie kodu i walidację w VS Code, PhpStorm oraz każdym zgodnym edytorze.

Każde pole może określać default dla nowych bloków oraz fallback, który szablon otrzymuje, gdy pole jest puste.

block.json
{
  "name": "starter/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading" },
      { "id": "showCta", "type": "toggle", "label": "Show CTA" },
      { "id": "background", "type": "color", "label": "Background" }
    ]
  }
}

Praca z 3 plikami

block.json do pól, szablon dla znaczników i opcjonalny arkusz stylów.

React w PHP

RichText, InnerBlocks i useBlockProps działają bezpośrednio w PHP, Twig lub Blade.

SCSS i Tailwind

Użyj CSS, SCSS lub Tailwind. SCSS obsługuje ścieżki importu i wspólny preambułę, a edycja zagnieżdżonego fragmentu powoduje ponowną kompilację każdego pliku, który go importuje.

27 typów pól

Tekst, kolor, obraz, powtarzalne pole, wybór, edytor kodu i więcej — konfigurujesz w JSON.

JSON Schema

Uzupełnianie kodu i walidacja w VS Code, PhpStorm oraz zgodnych edytorach.

Trzy języki szablonów

PHP, Twig i Blade korzystają z tych samych zmiennych i komponentów.

Importy npm

Importuj pakiety w script.js; w środowisku produkcyjnym lokalnie, a w edytorze z obsługą CDN.

Interactivity API

Włącz Interactivity API WordPress za pomocą jednej flagi.

Komponenty React w szablonach PHP

Użyj <RichText /> do edycji w tekście i statycznego interfejsu HTML, <InnerBlocks /> dla bloków podrzędnych oraz useBlockProps dla kontenera — wszystko w jednym szablonie.

W edytorze stają się one prawdziwymi komponentami React. Interfejs renderuje je po stronie serwera jako HTML, bez wysyłania do odwiedzających JavaScript.

index.php
<div useBlockProps class="container">
  <RichText
    class="text-xl font-semibold"
    tag="h1"
    attribute="headline"
    placeholder="Enter headline"
  />

  <?php if ($a['showCta']): ?>
    <a href="<?= esc_url($a['ctaUrl']) ?>">
      <?= esc_html($a['ctaLabel']) ?>
    </a>
  <?php endif; ?>

  <InnerBlocks class="mt-4 p-4 border" />
</div>

Pisz w PHP, Twig lub Blade

Używaj znanego Ci języka szablonów. PHP działa od razu po instalacji, Twig uruchamia się po zainstalowaniu Timber, a Blade działa na illuminate/view od 8 do 12 za pośrednictwem Blockstudio\Blade_Renderer. Zmienne, komponenty i działanie pozostają takie same.

$a (atrybuty), $b (blok), $c (kontekst) i $innerBlocks są dostępne w każdym języku.

Twig szablony również otrzymują pełny kontekst Timber. Blade renderuje także strony, wzorce i szablony Edytora witryny. Starszy wrapper jenssegers/blade nie działa z illuminate/view 10 i nowszymi wersjami, dlatego używaj Blade_Renderer.

index.twig
<div useBlockProps class="card">
  <RichText tag="h2" attribute="title" placeholder="Card title" />
  {% if a.image %}
    <img src="{{ a.image.url|esc_url }}"
      alt="{{ a.image.alt|esc_attr }}" />
  {% endif %}
  <div class="card__body">{{ a.description|esc_html }}</div>
  <InnerBlocks allowedBlocks='["core/button"]' />
</div>

Logika warunkowa i opcje dynamiczne

Pokazuj i ukrywaj pola za pomocą operatorów takich jak ==, !=, includes, empty oraz porównań. Łącz warunki za pomocą logiki OR.

Opcje mogą zależeć od innego pola. Dodaj {attributes.post_type.value} do argumentów wypełniania, a lista zostanie ponownie wczytana po zmianie tego pola. Dodaj fetch: true, aby wyszukiwać wpisy podczas pisania przez edytora.

Udostępniaj jedną listę opcji między blokami za pomocą type: custom i filtra blockstudio/blocks/attributes/populate, a własne warunki globalne, takie jak sprawdzanie zakupu, rejestruj przez blockstudio/blocks/conditions.

block.json
{
  "name": "starter/posts",
  "title": "Posts",
  "blockstudio": {
    "attributes": [
      {
        "id": "post_type",
        "type": "select",
        "label": "Post type",
        "options": [
          { "value": "page", "label": "Pages" },
          { "value": "post", "label": "Posts" }
        ]
      },
      {
        "id": "selected_post",
        "type": "select",
        "label": "Post",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": { "post_type": "{attributes.post_type.value}" }
        }
      },
      {
        "id": "style",
        "type": "select",
        "label": "Style",
        "populate": { "type": "custom", "custom": "cardStyles" },
        "conditions": [[
          { "type": "purchasedProduct", "operator": "==", "value": "yes" }
        ]]
      }
    ]
  }
}

Repeatery, nad którymi łatwo zapanować

Ustaw min i max, rozpoczynaj nowe bloki z default wierszami i zwijaj istniejące wiersze za pomocą minimized. textMinimized oznacza zwinięty wiersz wartością jednego z jego pól, na przykład nazwą.

Wiersze obsługują wszystkie typy pól poza kartami, w tym zagnieżdżone repeatery. Warunek wewnątrz wiersza sprawdza pole spoza niego za pomocą "context": "main", a <RichText /> i <MediaPlaceholder /> edytują pojedynczy wiersz, gdy ich attribute wskazuje na repeaterId[index].fieldId.

block.json
{
  "name": "starter/team",
  "title": "Team",
  "blockstudio": {
    "attributes": [
      {
        "id": "members",
        "type": "repeater",
        "label": "Team members",
        "min": 1,
        "max": 12,
        "minimized": true,
        "textMinimized": { "id": "name", "fallback": "Team member" },
        "attributes": [
          { "id": "name", "type": "text", "label": "Name" },
          { "id": "bio", "type": "richtext", "label": "Bio" }
        ]
      }
    ]
  }
}

Zestawy pól wielokrotnego użytku

Zdefiniuj grupę pól raz w field.json i odwołuj się do niej z dowolnego bloku za pomocą "type": "custom/cta". Pola są wstawiane bezpośrednio, więc szablony odczytują je jak każdy inny atrybut.

Użyj tego samego zestawu dwa razy za pomocą idStructure, na przykład hero_{id}, a etykiety, wartości domyślne lub warunki zmieniaj dla każdego bloku przez overrides. Typ pola block robi to samo z całym blokiem: rozwija jego pola bezpośrednio i zwraca wyrenderowane HTML tego bloku.

fields/cta/field.json
{
  "name": "cta",
  "title": "Call to action",
  "attributes": [
    { "id": "label", "type": "text", "label": "Button label", "default": "Learn more" },
    { "id": "url", "type": "link", "label": "Button URL" }
  ]
}

Moduły ES bez etapu budowania

Dodaj script.js, a zostanie załadowany jako moduł ES. Importuj pakiety npm z prefiksem npm:, a Blockstudio pobierze je lokalnie na potrzeby środowiska produkcyjnego.

Edytor natychmiast wyświetla podgląd, a interfejs korzysta z lokalnych modułów bez zależności zewnętrznych; są one dołączane tylko raz.

Arkusze stylów importuje się tak samo. import "npm:swiper@11.0.0/swiper.min.css" pobiera plik i dodaje go do kolejki raz dla każdej wersji, nawet jeśli korzysta z niego kilka bloków.

script.js
import Swiper from "npm:swiper@11.0.0";
import "npm:swiper@11.0.0/swiper.min.css";

for (const el of document.querySelectorAll(".swiper")) {
  new Swiper(el, {
    slidesPerView: 3,
    spaceBetween: 20,
    loop: true,
  });
}

Tagi bloków poza szablonami

Przypisz krótki prefiks do przestrzeni nazw w blockstudio.json albo jeden tag do jednego bloku za pomocą filtra aliasów, a <acme-card> wyrenderuje acme/card. Włącz blockTags.enabled, aby renderować tagi w treści wpisów i widżetach, z ograniczeniem do wzorców allow i deny.

Atrybuty data-* trafiają do elementu głównego bloku, a atrybuty html-* docierają tam bez prefiksu. Dodawaj własne konstruktory tagów za pomocą blockstudio/block_tags/builders i przepisuj skrócone zapisy na przenośną postać <bs:acme-card> poleceniem migrate-block-tags.

blockstudio.json
{
  "blockTags": {
    "enabled": true,
    "prefixes": {
      "acme": ["acme"],
      "ui": ["acme-ui"]
    },
    "deny": ["acme-ui/admin-*"]
  }
}

Niestandardowe typy pól

Zarejestruj własne pole sterujące i używaj go jak wbudowanego pola.

Wyspy bloków

Zapisz całą stronę w pamięci podręcznej i renderuj jeden blok w ramach żądania odwiedzającego.

Warunkowa rejestracja

Rejestruj blok tylko dla danego typu wpisu, roli użytkownika lub innego warunku globalnego albo pomiń go, gdy brakuje wymaganej wtyczki lub jej wersji.

Metadane wpisów i opcje

Przechowuj wartości w metadanych wpisu lub opcjach obok atrybutów bloku.

Logika warunkowa

Wyświetlaj pola na podstawie wartości, korzystając z równości, zawierania, pustych wartości i porównań.

Dynamiczne źródła danych

Wypełniaj opcje danymi z wpisów, użytkowników, taksonomii, funkcji lub API.

Nadpisywanie

Ustaw override: true wraz z nazwą wspólnego bloku, aby scalać atrybuty według identyfikatora, zastępować zasoby o pasujących nazwach plików i podmieniać szablon. Szablony Twig mogą nadpisywać pojedyncze bloki za pomocą extends.

Warianty

Zadeklaruj warianty w block.json, aby ustawiały wstępnie wartości pól, i ukryj pole, które nimi steruje, za pomocą hidden.

Komponenty

Ustaw component: true dla bloku renderowanego wyłącznie z PHP lub tagów bloków. Zachowuje pola, szablony, zasoby i Tailwind, ale nigdy nie pojawia się w inserterze.

Zasady InnerBlocks

Zezwalaj na bloki z tokenami namespace/*, category: i @theme, zmieniaj szablon wewnętrzny za pomocą opcji select i usuwaj wrapper na stronie przez filtr.

Zasoby pola kodu

Pole kodu z asset: true zamienia dane wejściowe edytora na CSS, SCSS lub JavaScript dla danego bloku, ograniczone do instancji przez %selector%.

Zasoby według nazwy pliku

*.view.js ładuje plik tylko na stronie, a prefiksy global-, admin- i block-editor- ładują plik na każdej stronie, w wp-admin lub w edytorze bloków.

Ikony i foldery bloków

Nadaj blokowi własną ikonę SVG lub HTML, zmień miejsce wyszukiwania za pomocą filtra blockstudio/path i dodawaj foldery przez Blockstudio\Build::init().

Wartości ACF i Meta Box

Szablony otrzymują $post_id, więc get_field() i rwmb_get_value() odczytują edytowany wpis, a refreshOn odświeża podgląd po zapisaniu.

Kontekst pętli zapytań

W pętli zapytań $block[‘context’][‘postId’] podąża za bieżącym elementem, a $block[‘postId’] pozostaje wpisem, który jest wyświetlany.

WPML

wp bs wpml config zapisuje wpml-config.xml, które oznacza pola tekstowe jako tłumaczalne, a obrazy zapisane w polach trafiają do zadań tłumaczeniowych WPML wraz z tekstami alternatywnymi i podpisami.

Plus

Oficjalny zestaw rozszerzeń

Wysokiej jakości szablony witryn, systemowe instrukcje AI i prywatna społeczność Discord. Jednorazowy zakup, dożywotnie aktualizacje.

  • 500+ szablonów stron
  • Instrukcje systemowe AI
  • Dożywotnie aktualizacje
  • Prywatna społeczność Discord