Deprecacja bloków Gutenberg: Aktualizuj bez niszczenia treści

Podsumowanie

Aktualizacja bloku Gutenberg często psuje istniejące wpisy korzystające ze starej wersji. Ten artykuł pokazuje, jak użyć właściwości deprecated w block.json, aby zachować wsteczną kompatybilność. Poznasz dokładne kroki, aby przechwycić obecny znacznik bloku, zdefiniować jedną lub więcej przestarzałych wersji i poprawnie odwzorować atrybuty. Omówimy zarówno bloki statyczne, jak i dynamiczne, z praktycznymi przykładami. Artykuł kwestionuje również założenie, że deprecacja jest zawsze najlepszym podejściem, omawiając, kiedy czyste przerwanie może być lepsze. Na koniec będziesz w stanie aktualizować swoje bloki bez obaw, nie psując treści użytkowników.

Scenariusz zmiany przełamującej

Sześć miesięcy temu uruchomiłeś niestandardowy blok opinii. Wyświetla on prosty <div> z cytatem i nazwiskiem autora. Teraz twój klient chce nowego projektu: autor powinien pojawiać się nad cytatem, z inną klasą CSS. Aktualizujesz funkcję save bloku oraz render_callback. Testujesz na nowym wpisie — wygląda świetnie. Potem przechodzisz do starego wpisu korzystającego z tego bloku. Katastrofa: tekst cytatu zniknął, autor jest w złym miejscu, a stylizacja jest nieprawidłowa. Właśnie zepsułeś każdą stronę, która używa tego bloku.

Czym jest deprecacja bloków?

Deprecacja bloków to wbudowany mechanizm Gutenberga do obsługi zmian wersji. Definiując tablicę deprecated w block.json, mówisz edytorowi: "Jeśli napotkasz blok pasujący do jednej z tych starszych wersji, przekształć go na bieżącą wersję." Każdy wpis deprecated określa poprzednie attributes, supports oraz funkcję save (lub render_callback). Gdy edytor ładuje stary blok, iteruje przez tablicę deprecated w kolejności i stosuje pierwsze pasujące przekształcenie.

Ta funkcja jest często niedoceniana, ponieważ programiści zakładają, że nigdy nie będą musieli zmieniać znaczników bloku. Jednak w rzeczywistych projektach wymagania ewoluują. Jeśli pominiesz deprecację, zmuszasz użytkowników do usuwania i ponownego wstawiania bloków (słabe doświadczenie) lub utrzymujesz dwie oddzielne wersje bloku (bałagan). Oficjalny podręcznik dewelopera WordPressa omawia to w Podręczniku edytora bloków, ale brakuje praktycznych przewodników.

Krok 1: Przechwyć bieżący stan

Przed wprowadzeniem jakichkolwiek zmian, zapisz dokładne wyjście save (lub render_callback dla bloków dynamicznych) oraz attributes, których obecnie używa twój blok. Potraktuj to jako zrobienie migawki. Dla bloków statycznych zapisz JSX zwracany przez funkcję save. Dla bloków dynamicznych zapisz znacznik PHP generowany przez render_callback.

Utwórz nowy plik w swojej wtyczce o nazwie deprecated.js (lub podobnej) i przechowuj tam starą funkcję save. Alternatywnie, trzymaj przestarzałe wersje bezpośrednio w głównym pliku JavaScript bloku. Kluczowe jest zachowanie tego kodu dokładnie tak, jak wyglądał przy pierwszym wdrożeniu bloku.

Krok 2: Zdefiniuj swoje przestarzałe wersje

W swoim block.json dodaj tablicę deprecated. Każdy wpis to obiekt, który może zawierać:

• attributes (obiekt): Poprzednie definicje atrybutów.
• supports (obiekt): Wszelkie poprzednie ustawienia wsparcia, które się zmieniły.
• save (funkcja lub string): Poprzednia funkcja save. Dla bloków tylko JavaScript zaimportujesz starą funkcję. Dla bloków dynamicznych renderowanych przez PHP możesz użyć migrate i render_callback.
• migrate (funkcja): Funkcja mapująca stare atrybuty na nowe (opcjonalnie).

Przykład:

"deprecated": [
  {
    "attributes": {
      "quote": { "type": "string", "source": "html", "selector": ".quote" },
      "author": { "type": "string", "source": "html", "selector": ".author" }
    },
    "supports": {},
    "save": "() => <div className="testimonial-legacy"><p className="quote">{attributes.quote}</p><p className="author">{attributes.author}</p></div>"
  }
]

Uwaga: Funkcja save w block.json jest zwykle definiowana w JavaScript. Jeśli używasz zewnętrznego skryptu, musisz go zakolejkować i odwołać się do nazwy funkcji. Alternatywnie, możesz umieścić funkcję jako string (choć nie jest to zalecane dla złożonych bloków).

Krok 3: Odwzoruj atrybuty

Często zmieniasz nie tylko znaczniki, ale także nazwy atrybutów lub źródła. Na przykład możesz przejść od przechowywania autora jako zwykłego stringa do pola tekstu sformatowanego. W takich przypadkach użyj właściwości migrate, aby przekształcić stare atrybuty na nowe.

migrate: (attributes) => {
  return {
    quote: attributes.quote,
    author: { content: attributes.author, level: 2 }
  };
}

Jeśli nie podasz funkcji migrate, edytor po prostu przekaże stare atrybuty bezpośrednio do nowego bloku. Może to spowodować błędy, jeśli nazwy atrybutów się zmieniły.

Krok 4: Testuj z rzeczywistą treścią

Po zdefiniowaniu przestarzałej wersji dokładnie przetestuj. Utwórz nowy wpis, wstaw stary blok (możesz symulować, wklejając zserializowany kod bloku z istniejącego wpisu) i sprawdź, czy konwertuje się do nowej wersji bez błędów walidacji. Przetestuj również edycję i zapisanie przekonwertowanego bloku. Powtórz dla wielu przestarzałych wersji, jeśli je masz.

Dla bloków dynamicznych, proces jest podobny, ale z pewnym haczykiem: funkcja save dla bloku dynamicznego zwykle zwraca null (blok renderuje się przez PHP). W przestarzałym wpisie możesz ustawić save na poprzedni statyczny znacznik, który był używany przed przejściem na dynamiczne renderowanie, lub użyć render_callback w PHP, który obsługuje zarówno stare, jak i nowe struktury atrybutów. To bardziej złożone, ale wykonalne.

Zastrzeżenia i kompromisy

Deprecacja jest potężna, ale ma wady. Każda przestarzała wersja dodaje kod do twojej wtyczki. Z czasem możesz skończyć z łańcuchem pięciu lub sześciu starszych wersji, które są rzadko używane, ale muszą być utrzymywane. Zespół podstawowy WordPressa zaleca trzymanie co najmniej dwóch wersji wstecz, ale poza tym możesz rozważyć czyste przerwanie, jeśli liczba dotkniętych wpisów jest mała.

Innym niuansem: kolejność wpisów deprecated ma znaczenie. Edytor iteruje przez tablicę od indeksu 0 w górę i używa pierwszego dopasowania. Jeśli dwie przestarzałe wersje są podobne, może zostać zastosowana niewłaściwa. Zawsze umieszczaj najnowszą przestarzałą wersję jako pierwszą (tę, która bezpośrednio poprzedza bieżącą wersję).

Wreszcie, deprecacja nie obsługuje treści edytowanej przy użyciu ogólnoserwisowych zmian stylów (np. przez theme.json). Jeśli wygląd twojego bloku opierał się na globalnych stylach, które od tego czasu się zmieniły, deprecacja tego nie dostosuje. Możesz potrzebować dodać skrypt migracyjny uruchamiany przy zapisie lub przez hak aktualizacji wtyczki.

Kiedy deprecacja nie jest odpowiedzią

Większość poradników przedstawia deprecację jako obowiązkową. W rzeczywistości istnieją sytuacje, w których czyste przerwanie jest lepsze. Jeśli twój blok jest nowy i używany tylko w kilku wpisach, ręczna aktualizacja tych kilku instancji może być szybsza niż pisanie i testowanie kodu deprecacji. Podobnie, jeśli model danych bloku jest zasadniczo inny (np. scalasz dwa bloki w jeden), deprecacja może nie być wystarczająco elastyczna. W takim przypadku napisz jednorazowy skrypt migracyjny uruchamiany przy aktualizacji wtyczki, który przekształca stare bloki na nowy format.

Inny kontrowersyjny punkt: deprecacja nie powinna być używana jako substytut dobrego projektu. Jeśli przewidujesz częste zmiany, zaprojektuj blok z myślą o wersjonowaniu od początku — np. przechowując atrybut version i używając warunkowego renderowania. To podejście, omówione w Poza podstawowymi blokami, jest lżejsze niż deprecacja, ale wymaga przewidywania.

Podsumowanie

Deprecacja bloków to niezbędne narzędzie dla każdego poważnego programisty Gutenberga. Pozwala ewoluować bloki bez psucia treści użytkowników. Kluczowe kroki to: przechwyć bieżący stan, zdefiniuj przestarzałą wersję w block.json, odwzoruj atrybuty, jeśli to konieczne, i testuj z rzeczywistą treścią. Pamiętaj jednak, że deprecacja wiąże się z kosztami utrzymania. Czasami czyste przerwanie lub wersjonowany projekt bloku są bardziej pragmatyczne. Używaj deprecacji strategicznie, a nie automatycznie, a twoje bloki pozostaną solidne przez wiele aktualizacji.

Aby uzyskać szerszą perspektywę na budowanie łatwych w utrzymaniu wtyczek, zobacz Budowanie solidnych wtyczek WordPress. A jeśli jesteś nowy w tworzeniu bloków, Poza podstawowymi blokami pomoże Ci zacząć.