Gutenberg 블록 폐기: 콘텐츠를 손상시키지 않고 업데이트하기

요약

Gutenberg 블록을 업데이트하면 기존 게시물이 깨지는 경우가 많습니다. 이 글에서는 block.json의 deprecated 속성을 사용하여 이전 버전과의 호환성을 유지하는 방법을 알려드립니다. 현재 블록 마크업을 캡처하고, 하나 이상의 폐기 버전을 정의하며, 속성을 올바르게 매핑하는 정확한 단계를 배우게 됩니다. 정적 블록과 동적 블록을 모두 다루며 실용적인 예제를 제공합니다. 또한 폐기가 항상 최선의 접근 방식이라는 가정에 반박하며, 깔끔한 분리가 더 나은 경우를 논의합니다. 마지막으로, 사용자의 콘텐츠를 깨뜨리지 않고 자신 있게 블록을 업데이트할 수 있게 될 것입니다.

변경 사항 시나리오

6개월 전에 맞춤형 사용후기 블록을 출시했습니다. 이 블록은 인용문과 작성자 이름이 포함된 간단한 <div>를 출력합니다. 이제 고객이 새로운 디자인을 원합니다. 작성자가 인용문 위에 나타나고 다른 CSS 클래스를 사용해야 합니다. 블록의 save 함수와 render_callback을 업데이트합니다. 새 게시물에서 테스트해보니 잘 작동합니다. 그런 다음 블록을 사용하는 오래된 게시물로 이동합니다. 재앙이 일어납니다: 인용문 텍스트는 사라지고, 작성자는 잘못된 위치에 있으며, 스타일이 깨져 있습니다. 블록을 사용하는 모든 페이지가 손상되었습니다.

이것이 Gutenberg 블록 개발에서 고전적인 "변경 사항" 문제입니다. 블록은 기본적으로 데이터 구조와 마크업의 조합입니다. 마크업을 변경하면 편집기가 이전 콘텐츠를 새 구조에 자동으로 매핑할 수 없습니다. 결과는 유효성 검사 오류(블록이 유효하지 않게 됨) 또는 더 나쁜 경우 블록이 잘못 렌더링되는 조용한 손상입니다.

블록 폐기란 무엇인가?

블록 폐기는 Gutenberg가 버전 변경을 처리하기 위한 내장 메커니즘입니다. 블록의 block.json에 deprecated 배열을 정의하면 편집기에게 "이전 버전 중 하나와 일치하는 블록을 발견하면 현재 버전으로 변환하십시오"라고 지시합니다. 각 폐기 항목은 이전 attributes, supports, save 함수(또는 render_callback)를 지정합니다. 편집기가 이전 블록을 로드하면 폐기 배열을 순서대로 반복하며 첫 번째 일치하는 변환을 적용합니다.

이 기능은 개발자가 블록의 마크업을 변경할 필요가 없다고 가정하기 때문에 자주 사용되지 않습니다. 그러나 실제 프로젝트에서는 요구 사항이 진화합니다. 폐기를 건너뛰면 사용자가 블록을 삭제하고 다시 삽입해야 하거나(나쁜 경험) 두 가지 별도 버전의 블록을 유지 관리해야 합니다(지저분함). 공식 WordPress 개발자 핸드북은 Block Editor Handbook에서 이 내용을 다루지만 실용적인 안내는 부족합니다.

1단계: 현재 상태 캡처

변경하기 전에 현재 블록이 사용하는 정확한 save 출력(또는 동적 블록의 경우 render_callback)과 attributes를 기록하십시오. 스냅샷을 찍는다고 생각하십시오. 정적 블록의 경우 save 함수가 반환하는 JSX를 저장하십시오. 동적 블록의 경우 render_callback이 생성하는 PHP 마크업을 저장하십시오.

플러그인에 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>"
  }
]

참고: block.json의 save 함수는 일반적으로 JavaScript로 정의됩니다. 외부 스크립트를 사용하는 경우 이를 추가하고 함수 이름을 참조해야 합니다. 또는 함수를 문자열로 인라인할 수도 있습니다(복잡한 블록에는 권장되지 않음).

3단계: 속성 매핑

종종 마크업뿐만 아니라 속성 이름이나 소스도 변경합니다. 예를 들어 작성자를 일반 문자열로 저장하는 대신 리치 텍스트 필드로 전환할 수 있습니다. 이러한 경우 migrate 속성을 사용하여 이전 속성을 새 속성으로 변환하십시오.

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

migrate 함수를 제공하지 않으면 편집기는 단순히 이전 속성을 새 블록에 직접 전달합니다. 속성 이름이 변경된 경우 오류가 발생할 수 있습니다.

4단계: 실제 콘텐츠로 테스트

폐기 버전을 정의한 후 철저히 테스트하십시오. 새 게시물을 만들고 이전 블록을 삽입한 후(기존 게시물의 직렬화된 블록 코드를 붙여넣어 시뮬레이션) 유효성 검사 오류 없이 새 버전으로 변환되는지 확인하십시오. 또한 변환된 블록을 편집하고 저장하는 것도 테스트하십시오. 여러 폐기 버전이 있는 경우 각각에 대해 반복하십시오.

동적 블록의 경우 프로세스는 비슷하지만 차이점이 있습니다: 동적 블록의 save 함수는 일반적으로 null을 반환합니다(블록은 PHP를 통해 렌더링됨). 폐기 항목에서 save를 동적 렌더링으로 전환하기 전에 사용된 이전 정적 마크업으로 설정하거나, PHP에서 이전 및 새 속성 구조를 모두 처리하는 render_callback을 사용할 수 있습니다. 이것은 더 복잡하지만 가능합니다.

주의 사항 및 장단점

폐기는 강력하지만 단점이 있습니다. 각 폐기 버전은 플러그인에 코드를 추가합니다. 시간이 지나면 거의 사용되지 않지만 유지 관리해야 하는 5~6개의 레거시 버전 체인이 생길 수 있습니다. WordPress 핵심 팀은 적어도 두 버전 이전을 유지할 것을 권장하지만, 그 이상은 영향을 받는 게시물 수가 적다면 깔끔한 분리를 고려할 수 있습니다.

또 다른 미묘한 점: 폐기 항목의 순서가 중요합니다. 편집기는 인덱스 0부터 배열을 반복하며 첫 번째 일치 항목을 사용합니다. 두 폐기 버전이 유사하면 잘못된 항목이 적용될 수 있습니다. 항상 가장 최근 폐기 버전(현재 버전 바로 이전)을 먼저 나열하십시오.

마지막으로, 폐기는 사이트 전체 스타일 변경(예: theme.json을 통해)으로 편집된 콘텐츠를 처리하지 않습니다. 블록의 모양이 변경된 글로벌 스타일에 의존했다면 폐기는 이를 조정하지 않습니다. 저장 시 또는 플러그인 업데이트 훅을 통해 실행되는 마이그레이션 스크립트를 추가해야 할 수 있습니다.

폐기가 정답이 아닌 경우

대부분의 튜토리얼은 폐기가 필수라고 주장합니다. 실제로는 깔끔한 분리가 더 나은 상황이 있습니다. 블록이 새롭고 소수의 게시물에서만 사용된다면 해당 몇 가지 인스턴스를 수동으로 업데이트하는 것이 폐기 코드를 작성하고 테스트하는 것보다 빠를 수 있습니다. 마찬가지로 블록의 기본 데이터 모델이 근본적으로 다른 경우(예: 두 블록을 하나로 병합) 폐기가 충분히 유연하지 않을 수 있습니다. 그런 경우 플러그인이 업데이트될 때 실행되는 일회성 마이그레이션 스크립트를 작성하여 이전 블록을 새 형식으로 변환하십시오.

또 다른 반대 의견: 폐기는 좋은 디자인의 대체재로 사용되어서는 안 됩니다. 빈번한 변경이 예상된다면 처음부터 버전 관리를 염두에 두고 블록을 설계하십시오. 예를 들어 version 속성을 저장하고 조건부 렌더링을 사용하는 것입니다. Beyond Basic Blocks에서 논의된 이 접근 방식은 폐기보다 가볍지만 선견지명이 필요합니다.

결론

블록 폐기는 진지한 Gutenberg 개발자에게 필수적인 도구입니다. 사용자의 콘텐츠를 깨뜨리지 않고 블록을 발전시킬 수 있습니다. 주요 단계는 현재 상태 캡처, block.json에 폐기 버전 정의, 필요한 경우 속성 매핑, 실제 콘텐츠로 테스트입니다. 그러나 폐기에는 유지 관리 비용이 따릅니다. 때로는 깔끔한 분리 또는 버전 관리된 블록 디자인이 더 실용적입니다. 폐기를 자동으로 적용하지 말고 전략적으로 사용하면 블록이 많은 업데이트를 견뎌낼 수 있습니다.

유지 관리 가능한 플러그인 구축에 대한 더 넓은 관점은 Building Robust WordPress Plugins를 참조하십시오. 블록 개발이 처음이라면 Beyond Basic Blocks가 시작하는 데 도움이 될 것입니다.