Gå til indhold

Migrering til v7

Denne vejledning gennemgår de ændringer, du skal foretage, når du opgraderer fra Blockstudio 6 til 7.

ES-modulimporter

Blockstudio 7 introducerer det nye præfiks npm: til ES-modulimporter, så det følger Denos npm-specifier-konvention.

Før (v6):

JavaScript
import { h, render } from "blockstudio/preact@10.15.1";
import htm from "blockstudio/htm@3.1.1";
import confetti from "blockstudio/canvas-confetti@1.6.0";

Efter (v7):

JavaScript
import { h, render } from "npm:preact@10.15.1";
import htm from "npm:htm@3.1.1";
import confetti from "npm:canvas-confetti@1.6.0";

CSS-importer

Den samme ændring gælder for CSS-importer:

Før (v6):

JavaScript
import "blockstudio/swiper@11.0.0/swiper.min.css";

Efter (v7):

JavaScript
import "npm:swiper@11.0.0/swiper.min.css";

Bagudkompatibilitet

Præfikset blockstudio/ understøttes stadig af hensyn til bagudkompatibilitet. Din eksisterende kode vil fortsat fungere uden ændringer. Vi anbefaler dog, at du migrerer til præfikset npm: for at følge det bredere JavaScript-økosystem.

Præfikset npm: har flere fordele:

  • Tilpasning til økosystemet – Følger Denos etablerede konvention
  • Tydelighed – Gør det straks klart, at du importerer fra npm
  • Fremtidssikring – Præfikset blockstudio/ kan blive udfaset i en fremtidig hovedversion

Hooknavne

Blockstudio 7 standardiserer alle hooknavne i PHP, så de bruger snake_case i stedet for camelCase og følger konventionerne i WordPress-kernen.

Ændrede hooknavne

Gammelt navn (v6) Nyt navn (v7)
blockstudio/blocks/components/useblockprops/render blockstudio/blocks/components/use_block_props/render
blockstudio/blocks/components/innerblocks/render blockstudio/blocks/components/inner_blocks/render
blockstudio/blocks/components/innerblocks/frontend/wrap blockstudio/blocks/components/inner_blocks/frontend/wrap
blockstudio/blocks/components/richtext/render blockstudio/blocks/components/rich_text/render
blockstudio/assets/process/scss/importPaths blockstudio/assets/process/scss/import_paths
blockstudio/settings/assets/process/scssFiles blockstudio/settings/assets/process/scss_files
blockstudio/settings/editor/formatOnSave blockstudio/settings/editor/format_on_save
blockstudio/settings/blockEditor/disableLoading blockstudio/settings/block_editor/disable_loading
blockstudio/settings/blockEditor/cssClasses blockstudio/settings/block_editor/css_classes
blockstudio/settings/blockEditor/cssVariables blockstudio/settings/block_editor/css_variables
blockstudio/settings/ai/enableContextGeneration blockstudio/settings/ai/enable_context_generation

Bagudkompatibilitet

De gamle camelCase-hooknavne understøttes stadig af hensyn til bagudkompatibilitet. Din eksisterende kode vil fortsat fungere uden ændringer. Vi anbefaler dog, at du migrerer til de nye snake_case-navne for at sikre ensartethed.

Eksempel på migrering:

PHP
// Before (v6)
add_filter('blockstudio/settings/blockEditor/cssClasses', function() {
    return ['my-stylesheet'];
});

// After (v7)
add_filter('blockstudio/settings/block_editor/css_classes', function() {
    return ['my-stylesheet'];
});

Kanoniske bloktags

Blockstudio 7.6 bevarer projektpræfikser og præcise aliaser som udvidelsespunkter ved kørsel, men bruger <bs:namespace-slug> som den kanoniske stavemåde i eksempler, katalogoutput, render-deklarationer og diagnostik. Kanoniske tags indeholder det reelt registrerede bloknavn og afhænger ikke af et værtsspecifikt filter.

For et projekt med brand => ["theme-components"] og ui => ["bsui"]:

HTML
<!-- Legacy project shorthand -->
<brand-card>
  <ui-input />
</brand-card>

<!-- Canonical output -->
<bs:theme-components-card>
  <bs:bsui-input />
</bs:theme-components-card>

En selvstændig migreringskommando gennemgår et eksisterende projekt og omskriver forkortelser til den kanoniske stavemåde. Den viser først en rapport, stopper ved uafklarede tilfælde og ændrer kun tagnavne. Se Migrering af bloktags for kommandoen, dens input og dens sikkerhedsadfærd.

Navngivning af aktivfiler

Blockstudio 7 introducerer punktumsnotation til filendelser for aktiver og erstatter den tidligere bindestregsnotation som anbefalet konvention.

Ændrede filnavne

Gammelt navn (v6) Nyt navn (v7)
*-inline.(s)css *.inline.(s)css
*-inline.js *.inline.js
*-editor.(s)css *.editor.(s)css
*-editor.js *.editor.js
*-scoped.(s)css *.scoped.(s)css
*-view.js *.view.js

Bagudkompatibilitet

Den gamle bindestregsnotation understøttes stadig af hensyn til bagudkompatibilitet. Dine eksisterende filer vil fortsat fungere uden omdøbning. Vi anbefaler dog, at du bruger punktumsnotation til nye blokke.

Eksempel på migrering:

Kode
my-block/
├── block.json
├── index.php
├── style.css
├── style-inline.css   →  style.inline.css
├── style-scoped.css   →  style.scoped.css
├── style-editor.css   →  style.editor.css
├── script.js
├── script-inline.js   →  script.inline.js
├── script-editor.js   →  script.editor.js
└── script-view.js     →  script.view.js

Feltafbryder

Egenskaben switch har nu standardværdien false i stedet for true. I v6 havde hvert felt en usynlig kontakt i venstre side, som var slået til som standard. I v7 er kontakten valgfri og vises som et synligt øjeikon i feltets etiket.

Hvad er ændret

  • Standardværdien er nu false: Felter har ikke længere en kontakt, medmindre du udtrykkeligt angiver "switch": true
  • Synligt øjeikon: I stedet for et skjult klikområde i venstre side vises en knap med et øjeikon i etiketområdet
  • Deaktiveret overlejring: Når et felt er deaktiveret, vises en sløret overlejring med teksten "Dette felt er deaktiveret" i stedet for blot at mindske opaciteten

Migrering

Hvis du var afhængig af standardadfærden for kontakter i v6, skal du aktivere den udtrykkeligt:

JSON
{
  "id": "title",
  "type": "text",
  "label": "Title",
  "switch": true
}

Hvis du tidligere satte "switch": false for at deaktivere kontakten, kan du fjerne den, da false nu er standard.

Tailwind CSS

Blockstudio 7 erstatter fuldstændigt tilgangen med v6 Tailwind. I v6 blev Tailwind CSS kompileret på klientsiden via CDN i editoren og gemt på disken, når indlægget blev gemt. I v7 kompileres Tailwind CSS på serversiden ved hver frontendforespørgsel via TailwindPHP med automatisk filbaseret cachelagring.

Se dokumentationen til Tailwind CSS for alle detaljer om det nye system.

Altid aktiv kompilering på serversiden

Når tailwind.enabled er true, kompileres hver frontendforespørgsel på serversiden. Kompileringsforløbet:

  1. WordPress gengiver hele sidens HTML i en outputbuffer
  2. CSS-klassekandidater udtrækkes fra HTML (hurtigt regulært udtryk, ingen kompilering)
  3. Kandidater sorteres og hashes med CSS-konfigurationen for at oprette en cache-nøgle
  4. Ved cachetræf: Den cachelagrede CSS-fil læses og indsættes
  5. Ved cachemiss: TailwindPHP kompilerer CSS, skriver det til Blockstudios delte runtime-cache under området tailwind og indsætter det

Den kompilerede CSS indsættes som et inline-<style id="blockstudio-tailwind">-tag før </head>. Det omfatter Tailwinds preflight og alle matchede hjælpeklasser.

Scriptet CDN forbliver aktivt i editoren kun til liveforhåndsvisning. Det leveres aldrig på frontend.

Ændret config-format

Egenskaben config er ændret fra et JSON-objekt (Tailwind v3) til en CSS-streng (syntaks med Tailwind v4 CSS først).

Før (v6):

JSON
{
  "tailwind": {
    "config": {
      "theme": {
        "extend": {
          "colors": {
            "primary": "pink"
          }
        }
      }
    }
  }
}

Efter (v7):

JSON
{
  "tailwind": {
    "config": "@theme { --color-primary: pink; }"
  }
}

Indstillingen customClasses fjernet

Indstillingen customClasses array er fjernet. Med Tailwind v4’s CSS-først-tilgang defineres brugerdefinerede utility-klasser direkte i strengen config ved hjælp af @layer utilities.

Før (v6):

JSON
{
  "tailwind": {
    "customClasses": [
      { "className": "btn", "value": "px-4 py-2 rounded-lg font-medium" },
      { "className": "card", "value": "bg-white rounded-xl shadow-lg p-6" }
    ]
  }
}

Efter (v7):

JSON
{
  "tailwind": {
    "config": "@layer utilities { .btn { @apply px-4 py-2 rounded-lg font-medium; } .card { @apply bg-white rounded-xl shadow-lg p-6; } }"
  }
}

Eller via filteret til konfigurationer med flere linjer:

PHP
add_filter('blockstudio/settings/tailwind/config', function () {
    return <<<CSS
@layer utilities {
    .btn { @apply px-4 py-2 rounded-lg font-medium; }
    .card { @apply bg-white rounded-xl shadow-lg p-6; }
}
CSS;
});

Filteret blockstudio/settings/tailwind/custom_classes er også fjernet. Brug filteret blockstudio/tailwind/css i stedet for at tilføje brugerdefinerede regler for CSS.

Endepunktet REST fjernet

Endepunktet POST /blockstudio/v1/editor/tailwind/save er fjernet. Kompileret CSS gemmes ikke længere fra editoren. Hvis du havde brugerdefineret kode, der kaldte dette endepunkt, kan den fjernes uden videre.

Cachelagring

Blockstudio bruger en cachelagringsstrategi baseret på kandidater. I stedet for at hashe hele sidens HTML (hvilket ville ugyldiggøre cachen ved hver forespørgsel på grund af noncer og tidsstempler) hashes kun CSS-klassekandidaterne. Det betyder:

  • To sider med de samme CSS-klasser deler den samme cachelagrede fil
  • Dynamisk indhold (noncer, adminbjælker, tidsstempler) ugyldiggør ikke cachen
  • Cachen ugyldiggøres kun, når sættet af CSS-klasser eller konfigurationen ændres

Cachefiler bruger den konfigurerede runtime-rod for Blockstudio under sites/{network-blog}/{runtime-identity}/tailwind/. Kald Blockstudio\Runtime_Cache::purge('tailwind') for at gennemtvinge genkompilering.

Filterændringer

Gammelt navn (v6) Nyt navn (v7)
blockstudio/tailwind/on_demand/css blockstudio/tailwind/css
blockstudio/tailwind/assets/dir Fjernet
blockstudio/settings/tailwind/custom_classes Fjernet

Fjernede filer og indlæsninger

I v6 blev Tailwind CSS indlæst som eksterne typografiark (blockstudio-tailwind, blockstudio-tailwind-preflight). I v7 indsættes alt CSS inline via en outputbuffer. Der er ingen linktags eller indlæste typografiark for Tailwind på frontend.

Blokbibliotek

Det indbyggede bibliotek “Blockstudio Elements” er fjernet. Indstillingen library i blockstudio.json og filteret blockstudio/settings/library har ikke længere nogen effekt.

Hvis du brugte biblioteksblokkene (Gallery, Slider, Image Comparison, Code, Icon), skal du kopiere blokmapperne fra mappen includes/library/blockstudio-element/ i din v6-installation til dit temas blockstudio-mappe og opdatere deres block.json-filer med de nye navne og kategorier.