웹 구성 요소 API 사용 중단

웹 구성 요소 API를 더 이상 사용하지 않는 것은 패키지의 다음 주요 릴리스에서 기능이 제거될 것임을 사용자에게 알리는 좋은 방법입니다. 구성요소 API를 문서화하기 위해 사용자 정의 요소 매니페스트를 사용하는 경우 이는 보기보다 까다로울 수 있습니다. 웹 구성 요소에는 일반적으로 프레임워크 구성 요소보다 더 많은 공개 API가 있습니다.

• CSS 변수
• CSS 부분
• 슬롯
• 이벤트
• 방법
• 속성
• 속성.

이 기사에서는 API 지원 중단을 문서화하고 주요 변경 사항을 도입하지 않고 대체 기능을 추가하는 방법을 설명합니다.

선적 서류 비치

지원 중단 과정에서 가장 까다로운 부분 중 하나는 문서입니다. 속성, 메소드 및 구성 요소의 경우 구성 요소 클래스의 JSDoc 주석에 @deprecated 태그를 추가하는 것만큼 간단할 수 있습니다.

/**
  * @deprecated This component is going away. Use ... instead.
  */
class MyElement extends HTMLElement {
  /** @deprecated This property is being removed. Use ... instead. */
  myProp;

  /** @deprecated This method is going away. Use ... instead. */
  myMethod() {
  }
}

CSS 변수, CSS 부분, 슬롯, 이벤트 및 속성은 일반적으로 클래스의 JSDoc에 문서화되어 있습니다.

다음은 맞춤 요소 JSDoc에 문서화할 수 있는 내용의 예입니다.

/**
 * @attr {boolean} disabled - disables the element
 * @attribute {string} foo - description for foo
 *
 * @csspart bar - Styles the bar element in the shadow DOM
 *
 * @slot - This is a default/unnamed slot
 * @slot container - You can put some elements here
 *
 * @cssprop --text-color - Controls the color of foo
 * @cssproperty [--background-color=red] - Controls the background color of bar
 *
 * @prop {boolean} prop1 - some description
 * @property {number} prop2 - some description
 *
 * @fires custom-event - some description for custom-event
 * @fires {MyType} typed-event - some description for typed-event
 * @event {MyType} typed-custom-event - some description for typed-custom-event
 *
 * @summary This is MyElement
 *
 * @tag my-element
 * @tagname my-element
 */
class MyElement extends HTMLElement {}

문제

문제는 JSDoc 태그를 두 배로 늘리고 @deprecated 태그를 사용하여 이러한 항목이 더 이상 사용되지 않음을 나타낼 수 없다는 것입니다. 그렇지 않으면 전체 클래스가 더 이상 사용되지 않는 것으로 해석됩니다.

/**
 * @cssprop --text-color - @deprecated I dub thee "deprecated" ❌
 */
class MyElement extends HTMLElement {}

해결책

이 문제를 해결하기 위해 JSDoc의 항목에 태그를 지정하여 해당 항목이 맞춤 요소 매니페스트에서 적절하게 업데이트되도록 하는 도구(custom-elements-manifest-deprecator)를 만들었습니다.

이 도구를 사용하면 대체 태그를 사용하여 더 이상 사용되지 않는 API를 식별할 수 있습니다. 기본적으로 괄호로 묶인 @deprecated 태그를 식별자로 사용하지만(오늘 사용할 태그) 원하는 대로 사용자 정의할 수 있습니다.

/**
 * @cssprop --text-color - (@deprecated) I dub thee "deprecated" ?
 */
class MyElement extends HTMLElement {}

API 업데이트

우리 팀에게 중요한 점은 API를 제거하거나 변경할 때 팀이 조기에 해당 기능으로 마이그레이션할 수 있도록 다음 주요 릴리스 전에 새로운 기능을 도입하려고 노력한다는 것입니다. 이렇게 하면 최신 상태를 유지하면 새 버전으로 업그레이드하는 데 따른 영향을 최소화할 수 있습니다.

다음 섹션에서는 기존 API를 손상시키지 않고 새로운 기능을 도입하는 방법과 서로 경쟁하지 않고 공존할 수 있는 방법을 살펴보겠습니다. 간단한 버튼 구성요소에 대한 일부 API를 업데이트할 예정입니다.

이 예에서는 Lit를 사용하지만 이러한 기능과 원리는 모든 환경에 적용될 수 있습니다.

CSS 변수

VS Code 및 JetBrains와 같은 편집기에서 더 나은 자동 완성 및 설명을 제공하려면 구성 요소별 CSS 변수 이름을 제공해야 합니다.

/**
  * @deprecated This component is going away. Use ... instead.
  */
class MyElement extends HTMLElement {
  /** @deprecated This property is being removed. Use ... instead. */
  myProp;

  /** @deprecated This method is going away. Use ... instead. */
  myMethod() {
  }
}

까다로운 부분은 팀이 이미 이전 변수를 사용하고 있으므로 작동하려면 둘 다 필요하다는 것입니다. 더 이상 사용되지 않는 변수를 새 변수에 매핑하고 해당 변수만 사용하도록 버튼 코드를 업데이트하면 됩니다. 이렇게 하면 사용자가 더 이상 사용되지 않는 변수로 스타일을 지정하는 경우 해당 변수가 새 변수에 적용되거나 사용자가 새 변수에 직접 값을 적용할 수 있습니다.

/**
 * @attr {boolean} disabled - disables the element
 * @attribute {string} foo - description for foo
 *
 * @csspart bar - Styles the bar element in the shadow DOM
 *
 * @slot - This is a default/unnamed slot
 * @slot container - You can put some elements here
 *
 * @cssprop --text-color - Controls the color of foo
 * @cssproperty [--background-color=red] - Controls the background color of bar
 *
 * @prop {boolean} prop1 - some description
 * @property {number} prop2 - some description
 *
 * @fires custom-event - some description for custom-event
 * @fires {MyType} typed-event - some description for typed-event
 * @event {MyType} typed-custom-event - some description for typed-custom-event
 *
 * @summary This is MyElement
 *
 * @tag my-element
 * @tagname my-element
 */
class MyElement extends HTMLElement {}

이제 새로운 CSS 변수로 JSDoc 정보를 업데이트하고 업데이트된 설명과 함께 이전 변수에 (@deprecated)를 추가할 수 있습니다.

/**
 * @cssprop --text-color - @deprecated I dub thee "deprecated" ❌
 */
class MyElement extends HTMLElement {}

CSS 부분

CSS 변수와 마찬가지로 더 나은 도구 지원을 위해 부품에 네임스페이스 이름을 제공하려고 하므로 컨트롤을 버튼 컨트롤로 대체할 예정입니다. CSS 클래스처럼 요소에 여러 부분을 적용할 수 있으므로 CSS 부분은 매우 쉽습니다. 따라서 새 부분 이름을 다른 요소와 함께 요소에 적용해 보겠습니다.

/**
 * @cssprop --text-color - (@deprecated) I dub thee "deprecated" ?
 */
class MyElement extends HTMLElement {}

이제 JSDoc을 새 부분으로 업데이트하고 (@deprecated)를 사용하여 이전 부분을 지원 중단하고 설명을 업데이트할 수 있습니다.

/* old variables */
--bg-color: #ccc;
--fg-color: black;

/* new variables */
--button-bg-color: #ccc;
--button-fg-color: black;

슬롯

국제화(i18n)를 지원하기 위한 구성 요소에 대한 새로운 계획을 통해 우리는 일부 API를 RTL(오른쪽에서 왼쪽으로) 언어에서 더욱 의미 있게 업데이트하고 있습니다. 우리가 하고 싶은 한 가지는 이미 왼쪽 슬롯을 사용하고 있는 프로젝트의 경험을 방해하지 않고 왼쪽부터 버튼 텍스트 앞에 아이콘을 표시하도록 슬롯을 업데이트하는 것입니다.

이를 수행하려면 더 이상 사용되지 않는 슬롯을 새 슬롯 내에 중첩하면 됩니다. 새 슬롯을 사용하지 않는 경우 기존 슬롯으로 "대체"됩니다.

--bg-color: #ccc;
--fg-color: black;
--button-bg-color: var(--bg-color);
--button-fg-color: var(--fg-color);

button {
  background-color: var(--button-bg-color);
  border: solid 1px var(--button-fg-color);
  color: var(--button-fg-color);
}

이제 JSDoc을 새 슬롯으로 업데이트하고 (@deprecated)를 사용하여 이전 슬롯을 지원 중단하고 설명을 업데이트할 수 있습니다.

/**
 * An example button element.
 *
 * @tag my-button
 * 
 * @cssprop [--bg-color=#ccc] - (@deprecated) (use `--button-bg-color` instead) controls the background color of the button
 * @cssprop [--fg-color=black] - (@deprecated) (use `--button-fg-color` instead) controls the foreground/text color of the button
 * @cssprop [--button-bg-color=#ccc] - controls the background color of the button
 * @cssprop [--button-fg-color=black] - controls the foreground/text color of the button
 *
 */

이벤트

예를 들어 사용자 정의 포커스 이벤트를 내보내고 있지만 팀에 혼란을 주고 있으므로 네임스페이스 이벤트(my-focus)를 추가하려고 합니다. 이벤트는 두 이벤트를 모두 내보낼 수 있고 개발자가 기회가 있을 때 새 이벤트로 이동할 수 있으므로 매우 간단합니다.

<button part="control button-control">
  <slot></slot>
</button>

이제 JSDoc을 새 이벤트로 업데이트하고 (@deprecated)를 사용하여 이전 이벤트를 지원 중단하고 설명을 업데이트할 수 있습니다.

/**
 * An example button element.
 *
 * @tag my-button
 *
 * @csspart control - (@deprecated) (use `button-control` instead) provides a hook to style internal button element
 * @csspart button-control - provides a hook to style internal button element
 */

참고: 대부분의 도구는 이벤트 문서화를 위해 @event 및 @fires를 허용합니다. 실제로는 별 차이가 없습니다.

행동 양식

메서드는 서로 병렬로 추가하기가 매우 쉽고 메소드 설명에 표준 @deprecated 태그를 사용하여 더 이상 사용되지 않음을 전달할 수 있습니다.

/**
  * @deprecated This component is going away. Use ... instead.
  */
class MyElement extends HTMLElement {
  /** @deprecated This property is being removed. Use ... instead. */
  myProp;

  /** @deprecated This method is going away. Use ... instead. */
  myMethod() {
  }
}

속성 및 속성

속성과 속성은 @attr/@attribute 및 @prop/@property 태그를 사용하여 클래스의 JSDoc에 문서화될 수 있습니다. 이를 사용하는 경우 (@deprecated) 태그를 사용하여 사용자 정의 요소 매니페스트에서 해당 속성을 더 이상 사용하지 않을 수 있지만 일반적으로 자체 JSDoc 주석을 사용하여 속성을 직접 문서화하는 것이 더 좋습니다. 이를 통해 유형 및 기타 도구를 사용하여 더 이상 사용되지 않는 API를 올바르게 식별할 수 있습니다.

좋은 점은 대부분의 분석기가 데코레이터 또는 기타 구성을 사용하여 구성 요소 클래스에 정의된 속성과 속성을 연결하는 데 매우 능숙하다는 것입니다. 따라서 해당 속성을 더 이상 사용하지 않으면 연관된 속성도 더 이상 사용되지 않습니다.

데모 구성 요소에는 기본 HTML 요소와 더 일치하도록 비활성화로 업데이트하려는 비활성화 속성이 있습니다.

가장 먼저 할 일은 이전 속성을 지원 중단하고 새 속성을 추가하는 것입니다.

/**
 * @attr {boolean} disabled - disables the element
 * @attribute {string} foo - description for foo
 *
 * @csspart bar - Styles the bar element in the shadow DOM
 *
 * @slot - This is a default/unnamed slot
 * @slot container - You can put some elements here
 *
 * @cssprop --text-color - Controls the color of foo
 * @cssproperty [--background-color=red] - Controls the background color of bar
 *
 * @prop {boolean} prop1 - some description
 * @property {number} prop2 - some description
 *
 * @fires custom-event - some description for custom-event
 * @fires {MyType} typed-event - some description for typed-event
 * @event {MyType} typed-custom-event - some description for typed-custom-event
 *
 * @summary This is MyElement
 *
 * @tag my-element
 * @tagname my-element
 */
class MyElement extends HTMLElement {}

이제 구성요소가 비활성화되었는지 확인해야 할 때마다 두 속성을 모두 확인하지 않아도 됩니다. 이를 단순화하기 위해 더 이상 사용되지 않는 속성을 getter/setter로 변환하고 새 속성을 정보 소스로 사용할 수 있습니다.

/**
 * @cssprop --text-color - @deprecated I dub thee "deprecated" ❌
 */
class MyElement extends HTMLElement {}

이제 이전 값이 업데이트될 때마다 새 값이 자동으로 업데이트되므로 새 속성만 확인하여 구성요소가 비활성화되었는지 확인하면 됩니다.

/**
 * @cssprop --text-color - (@deprecated) I dub thee "deprecated" ?
 */
class MyElement extends HTMLElement {}

완성된 예시를 확인해보세요!

결론

API를 변경하면 복잡해질 수 있지만, 획기적인 변경이 포함될 수 있으므로 새로운 기능 생성을 중단해야 한다는 의미는 아닙니다. 새로운 기능을 조기에 도입하고 기존 기능을 더 이상 사용하지 않는 것은 좋은 개발자 경험(DX)을 제공하는 방법이 될 수 있습니다. 이는 팀이 새로운 기능을 활용하기 위해 한꺼번에 대규모 변경을 기다리도록 강요하는 대신 점진적인 개선의 길을 제공합니다.

위 내용은 웹 구성 요소 API 사용 중단의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!