Отхвърляне на Gutenberg блок: Актуализирайте, без да нарушавате съдържанието

Резюме

Актуализирането на Gutenberg блок често нарушава съществуващи публикации, които използват старата версия. Тази статия ви показва как да използвате свойството deprecated в block.json, за да поддържате обратна съвместимост. Ще научите точните стъпки за улавяне на текущата маркировка на блока, дефиниране на една или повече отхвърлени версии и правилно картографиране на атрибути. Ще покрием както статични, така и динамични блокове с практически примери. Статията също така поставя под съмнение предположението, че отхвърлянето винаги е най-добрият подход, като обсъжда кога чистото прекъсване може да е по-добре. Накрая ще можете да актуализирате блоковете си уверено, без да нарушавате съдържанието на потребителите.

Сценарият с промяна, която нарушава

Преди шест месеца пуснахте персонализиран testimonial блок. Той извежда прост <div> с цитат и име на автор. Сега клиентът ви иска нов дизайн: авторът да се появи над цитата, с различен CSS клас. Актуализирате функцията save и render_callback на блока. Тествате на нова публикация – изглежда страхотно. След това отивате на стара публикация, която използва блока. Катастрофа: текстът на цитата липсва, авторът е на грешното място, а стиловете са объркани. Току-що сте нарушили всяка страница, която използва този блок.

Това е класическият проблем с „нарушаваща промяна“ в разработката на Gutenberg блокове. Блоковете са по същество структури от данни, комбинирани с маркировка. Когато промените маркировката, редакторът не може автоматично да картографира старото съдържание към новата структура. Резултатът е или грешка при валидиране (блокът става невалиден), или – още по-лошо – тиха корупция, при която блокът се визуализира неправилно.

Какво е отхвърляне на блок?

Отхвърлянето на блок е вградената в Gutenberg механизъм за обработка на промени на версията. Като дефинирате масив deprecated в block.json на вашия блок, казвате на редактора: „Ако срещнете блок, който съответства на някоя от тези по-стари версии, трансформирайте го в текущата версия.“ Всеки запис за отхвърляне указва предишните attributes, supports и save функция (или render_callback). Когато редакторът зареди стар блок, той преминава през масива на отхвърлените версии в ред и прилага първото съвпадащо преобразуване.

Тази функция често се използва малко, защото разработчиците предполагат, че никога няма да се наложи да променят маркировката на блок. Но в реални проекти изискванията се променят. Ако пропуснете отхвърлянето, или принуждавате потребителите да изтрият и вмъкнат отново блокове (лошо изживяване), или поддържате две отделни версии на блока (объркано). Официалният наръчник за разработчици на WordPress покрива това в Наръчник за блоковия редактор, но липсват практически примери.

Стъпка 1: Уловете текущото състояние

Преди да направите каквито и да било промени, запишете точния резултат от save (или render_callback за динамични блокове) и attributes, които блокът ви в момента използва. Мислете за това като за моментна снимка. За статични блокове запазете JSX, върнат от функцията save. За динамични блокове запазете PHP маркировката, генерирана от render_callback.

Създайте нов файл във вашия плъгин, наречен deprecated.js (или подобен), и съхранете старата функция save там. Алтернативно, запазете отхвърлените версии директно в основния JavaScript файл на блока. Ключовото е да запазите този код точно както е бил, когато блокът е бил първоначално разгърнат.

Стъпка 2: Дефинирайте отхвърлените версии

В block.json добавете масив deprecated. Всеки запис е обект, който може да включва:

• attributes (обект): Предишните дефиниции на атрибути.
• supports (обект): Всички предишни настройки за поддръжка, които са се променили.
• save (функция или низ): Предишната функция save. За блокове само с JavaScript ще импортирате старата функция. За динамични блокове, визуализирани чрез PHP, можете да използвате migrate и render_callback.
• migrate (функция): Функция, която картографира стари атрибути към нови (по избор).

Пример:

"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>"
  }
]

Забележка: Функцията save в block.json обикновено се дефинира в JavaScript. Ако използвате външен скрипт, ще трябва да го поставите в опашката и да посочите името на функцията. Алтернативно, можете да вградите функцията като низ (въпреки че това не се препоръчва за сложни блокове).

Стъпка 3: Картографиране на атрибути

Често променяте не само маркировката, но и имената или източниците на атрибути. Например може да преминете от съхраняване на автора като обикновен низ към поле за богат текст. В такива случаи използвайте свойството migrate, за да трансформирате старите атрибути в нови.

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

Ако не предоставите функция migrate, редакторът просто ще предаде старите атрибути директно на новия блок. Това може да доведе до грешки, ако имената на атрибутите са се променили.

Стъпка 4: Тествайте с реално съдържание

След като дефинирате отхвърлената версия, тествайте задълбочено. Създайте нова публикация, вмъкнете стария блок (можете да симулирате, като поставите сериализирания код на блок от съществуваща публикация) и проверете дали той се преобразува в новата версия без грешки при валидиране. Също така тествайте редактиране и запазване на преобразувания блок. Повторете за множество отхвърлени версии, ако имате такива.

За динамични блокове процесът е подобен, но с обрат: функцията save за динамичен блок обикновено връща null (блокът се визуализира чрез PHP). В записа за отхвърляне можете или да зададете save на предишната статична маркировка, която е била използвана преди да превключите към динамично визуализиране, или да използвате render_callback в PHP, който обработва както стари, така и нови структури от атрибути. Това е по-сложно, но възможно.

Предупреждения и компромиси

Отхвърлянето е мощно, но има недостатъци. Всяка отхвърлена версия добавя код към вашия плъгин. С течение на времето може да се окажете с верига от пет или шест наследени версии, които рядко се използват, но трябва да се поддържат. Екипът на WordPress core препоръчва да пазите поне две версии назад, но след това можете да помислите за чисто прекъсване, ако броят на засегнатите публикации е малък.

Друг нюанс: редът на отхвърлените записи има значение. Редакторът обхожда масива от индекс 0 нагоре и използва първото съвпадение. Ако две отхвърлени версии са подобни, може да се приложи грешната. Винаги поставяйте най-новата отхвърлена версия първа (тази, която непосредствено предхожда текущата версия).

Накрая, отхвърлянето не обработва съдържание, което е редактирано с помощта на промяна в стиловете на целия сайт (напр. чрез theme.json). Ако външният вид на вашия блок разчиташе на глобални стилове, които са се променили, отхвърлянето няма да се адаптира към това. Може да се наложи да добавите миграционен скрипт, който да се изпълнява при запазване или чрез кука за актуализация на плъгин.

Когато отхвърлянето не е отговорът

Повечето уроци представят отхвърлянето като задължително. В действителност има ситуации, в които чистото прекъсване е по-добре. Ако блокът ви е нов и се използва само в няколко публикации, ръчното актуализиране на тези няколко случая може да е по-бързо от писането и тестването на код за отхвърляне. По същия начин, ако основният модел на данни на блока е коренно различен (например сливате два блока в един), отхвърлянето може да не е достатъчно гъвкаво. В този случай напишете еднократен миграционен скрипт, който се изпълнява при актуализация на плъгина, преобразувайки старите блокове в новия формат.

Друг контрапункт: отхвърлянето не трябва да се използва като заместител на добрия дизайн. Ако очаквате чести промени, проектирайте блока си с мисъл за версиониране от самото начало – например чрез съхраняване на атрибут version и използване на условно визуализиране. Този подход, обсъден в Отвъд основните блокове, е по-лек от отхвърлянето, но изисква предвидливост.

Заключение

Отхвърлянето на блокове е основен инструмент за всеки сериозен разработчик на Gutenberg. То ви позволява да развивате блоковете си, без да нарушавате съдържанието на потребителите. Ключовите стъпки са: уловете текущото състояние, дефинирайте отхвърлената версия в block.json, картографирайте атрибути ако е необходимо, и тествайте с реално съдържание. Но не забравяйте, че отхвърлянето идва с разходи за поддръжка. Понякога чистото прекъсване или проектиране на блок с версии е по-прагматично. Използвайте отхвърлянето стратегически, а не автоматично, и вашите блокове ще останат стабилни през много актуализации.

За по-широка перспектива за изграждане на поддържаеми плъгини, вижте Изграждане на стабилни WordPress плъгини. И ако сте нов в разработката на блокове, Отвъд основните блокове ще ви помогне да започнете.