Directives

네이티브 CSS 가지치기

각 스타일시트의 네이티브 클래스 가지치기와 필요할 때 생성하는 키프레임을 제어합니다.

이 페이지의 내용

네이티브 CSS 가지치기는 사용하지 않는 클래스 선택자 분기를 제거하고 키프레임을 필요할 때 사용할 수 있게 합니다. 이는 유틸리티 클래스 생성과 별개인 스타일시트 정책입니다. 활성화 시점은 CSS 전달 최적화, 소스와 후보 필터는 스캔 지시문을 참고하세요.

클래스 목록을 제공해도 네이티브 CSS는 기본적으로 보존됩니다. 통합이나 스타일시트 API에 pruneNativeCSS: true를 설정해 프로젝트 소유 소스를 가지치기하세요. 패키지 CSS는 자신의 소스가 명시적으로 활성화하지 않으면 보존됩니다.

`@prune native`

@prune native;.used {  color: red;}.unused {  color: blue;}

이 지시문은 선언 파일만 가지치기에 참여시키며 가져온 스타일시트로 전파되지 않습니다. 통합이 프로젝트 전체 가지치기를 활성화해도 같은 파일의 @preserve native;가 우선합니다. 네이티브 출력 스위치 preserveNativeCSS: false는 별도이며 두 지시문과 관계없이 네이티브 출력을 억제합니다.

`@preserve native`

Master가 관리하는 스타일시트에 네이티브 CSS 가지치기로 제거하면 안 되는 네이티브 클래스 규칙이 있다면 @preserve native;를 사용하세요.

@import "@master/css";@preserve native;.injected-by-payment-widget {  color: blue;}

스타일시트는 여전히 Master CSS가 처리합니다. 스캔 소스에서 클래스를 사용하지 않아도 네이티브 클래스 규칙은 유지되며 일반 컴파일러 정규화는 적용됩니다. 이 정책은 사용하지 않는 관리 클래스를 생성 출력에 강제로 넣거나 원래 CSS 바이트를 그대로 보존한다는 뜻이 아닙니다.

가져오기 그래프

해석된 CSS 가져오기는 각 소스 경계를 유지하므로 파일 정책은 해당 파일에만 적용됩니다. 가져오는 파일이 의존 파일의 가지치기를 활성화할 수는 없습니다. pruneNativeCSS: true에서는 @preserve native;를 선언하지 않은 프로젝트 소유 의존성이 참여합니다. 패키지나 원격 스타일은 프로젝트가 가져온다고 프로젝트 소유가 되지 않습니다. 한정자 있는 가져오기는 media, supports, layer 래퍼를 유지합니다.

src/style.css

@prune native;@import "@master/css";@import "./cards.css";

src/cards.css

@prune native;.card {  border: 1px solid rgb(0 0 0 / 12%);}.unused-card {  color: red;}

스캔 소스에 card가 있으면 출력은 .card를 유지하고 .unused-card를 제거합니다. cards.css에 지시문이 없으면 둘 다 남습니다.

루트 범위

활성화는 각 소스 파일에 속하며 필터링은 이를 가져오는 루트의 사용 범위를 따릅니다. 따라서 활성화된 같은 공유 파일도 루트마다 다른 클래스를 유지할 수 있습니다. JavaScript나 프레임워크 라우트가 직접 가져오는 파일은 그 가져오기가 Master CSS 파이프라인에 들어갈 때만 자체 루트가 됩니다.

루트는 기본적으로 전역 스캐너 범위를 사용합니다. 루트 가져오기 그래프 어디의 @source, @source not, @safelist, @blocklist든 범위를 좁히거나 넓힐 수 있습니다. 가져온 파일의 지시문은 이를 가져오는 모든 루트에 병합되며 상대 패턴은 선언 파일을 기준으로 해석됩니다.

app/a/a.css

@prune native;@import "@master/css";@source "./page.html";@import "../shared.css";

app/shared.css

@prune native;@blocklist "debug-*";.shared-card {  border: 1px solid rgb(0 0 0 / 12%);}.only-used-in-b {  color: blue;}.debug-outline {  outline: 1px solid red;}

app/a/page.html이 shared-card만 사용하면 a.css 출력은 .shared-card를 유지하고 .only-used-in-b와 .debug-outline을 제거합니다. 다른 루트 b.css의 페이지가 only-used-in-b를 사용하면 같은 공유 파일에서 그 규칙을 유지합니다.

규칙 필터링

클래스 선택자 규칙은 분기 하나의 클래스 중 하나라도 사용하면 유지하며 사용하지 않는 분기는 선택자 목록에서 제거합니다. 검사는 DOM 관계가 아닌 클래스 이름을 기준으로 합니다. .card .title에서는 card나 title 하나만 찾아도 분기를 유지하므로 유지된 규칙이 어떤 요소에도 일치하지 않을 수 있습니다.

@prune native;body {  margin: 0;}.card,.unused:hover {  border: 1px solid rgb(0 0 0 / 12%);}@media (width >= 48rem) {  .card .title {    font-weight: 700;  }  .debug-card {    outline: 1px solid red;  }}

card와 title을 사용하면 출력은 body, .card, .card .title을 유지하고 .unused:hover와 .debug-card를 제거합니다. body, html, :root처럼 클래스 선택자가 없는 규칙은 항상 유지합니다. 가지치기로 빈 at-rule 블록은 제거합니다.

manifest 참조

유지된 네이티브 규칙이 var(--*)를 읽거나 manifest 애니메이션 이름을 지정하면 프로젝트 진입점 그래프의 해당 테마 변수와 키프레임을 유지합니다. 제거된 규칙은 아무 리소스도 유지하지 않습니다.

@prune native;@import "@master/css";@theme {  --color-primary: #175cff;}.notice {  color: var(--color-primary);}.unused-notice {  color: var(--color-primary);}

notice만 사용하면 .notice를 유지하므로 --color-primary가 출력되며 .unused-notice는 제거됩니다.

포함한 클래스

@safelist는 제한된 외부 소스에서 오는 네이티브 클래스를 사용한 것으로 표시하여 가지치기가 규칙을 유지하게 합니다. 스캔 소스에 작성한 앱 클래스를 대체하지는 않습니다.

@prune native;@safelist "dialog-open dialog-closing";.dialog-open {  overflow: hidden;}.dialog-closing {  pointer-events: none;}

네이티브 키프레임

네이티브 CSS에 키프레임을 선언하고 소유 파일에서 사용 기반 출력을 활성화합니다.

@prune native;@theme {  --animate-reveal: reveal .2s ease-out both;}@keyframes reveal {  from {    opacity: 0;  }  to {    opacity: 1;  }}@safelist keyframes "external-enter" "external-exit";@keyframes external-enter {  from {    opacity: 0;  }  to {    opacity: 1;  }}@keyframes external-exit {  from {    opacity: 1;  }  to {    opacity: 0;  }}

키프레임은 네이티브 클래스 규칙과 같은 파일 정책을 따릅니다. 기본적으로 네이티브 CSS이며 제자리에서 원문 그대로 출력에 남고 Master CSS는 다시 출력하지 않습니다. @prune native;는 파일의 키프레임을 토큰 같은 온디맨드 정의로 바꿉니다. 네이티브 출력에서 빠지고 이를 사용하는 출력이 생성 CSS와 함께 출력합니다. 두 지시문이 있으면 @preserve native;가 우선합니다. 정책은 선언 파일에만 적용되며 가져오기로 전파되지 않습니다. pruneNativeCSS 옵션은 프로젝트 소유 파일 범위를 유지합니다. 패키지 CSS는 명시적으로 가지치기에 참여하지 않으면 보존됩니다. preserveNativeCSS: false는 네이티브 전달을 억제하지만 온디맨드 정의는 사용 위치에 계속 출력됩니다.

키프레임 사용 루트

애니메이션 유틸리티, 네이티브 애니메이션 선언, 정적 애니메이션 토큰, 키프레임 세이프리스트는 일치하는 정의를 사용합니다. 분석은 단축 값, animation-name 목록, 중첩 변수, 대체 값, 범위가 있는 재정의, 전이적 토큰 의존성을 추적합니다. 사용한 정의는 프레임이 읽는 토큰도 사용합니다. 네이티브 정의는 스타일시트가 프레임을 전달하므로 해당 토큰만 제공합니다. 해석되지 않은 동적 이름은 보수적으로 컴파일 그래프의 모든 후보 정의를 사용하며 정보 진단을 생성합니다.

키프레임 조건과 제한

출력된 온디맨드 정의는 한정자 있는 가져오기의 레이어를 포함해 선언 위치의 조건과 레이어 규칙으로 감싸지며 생성 레이어 뒤에 옵니다. 같은 컨테이너의 정의는 래퍼 하나를 공유합니다. 같은 이름의 정의도 선언 순서대로 별도로 유지되며 브라우저가 우선할 정의를 결정합니다. 이름은 디코딩하고 대소문자를 구분합니다. 익명 레이어에는 다시 진입할 수 없으므로 그 안의 또는 그 안으로 가져온 온디맨드 키프레임은 컴파일 오류입니다. 레이어에 이름을 붙이거나 파일을 보존하세요. 프레임은 원래 스타일시트 밖에 출력되므로 내부 상대 url()도 컴파일 오류입니다. 절대 URL을 사용하거나 파일을 보존하세요. 정의 ID는 선언 파일에서 가장 가까운 명명된 package.json과 패키지 상대 경로에서 생성되므로 같은 프로젝트는 체크아웃이나 설치 디렉터리와 관계없이 같은 CSS를 출력합니다. 패키지 이름을 바꾸면 ID가 바뀌며 명명된 패키지 밖의 파일은 절대 경로를 대안으로 사용합니다.

키프레임 리소스 소유권

프레임은 네이티브 선언을 포함하며 프레임 내부 중첩 지시문과 @apply는 지원하지 않습니다. 사용하지 않는 유틸리티와 믹스인, 가지치기한 네이티브 규칙, 전달하지 않은 참조 스타일은 사용 루트를 만들지 않습니다. @reference는 보존 정책이나 세이프리스트를 가져오지 않고 정의를 필요할 때 사용할 수 있게 합니다. 상대 URL이 있는 네이티브 키프레임은 원래 스타일시트에 남습니다. 프로젝트나 기본 manifest의 네이티브 키프레임도 이를 전달하지 않는 스타일시트에서는 온디맨드입니다. emitted globals는 출력이 네이티브 또는 온디맨드로 전달하는 키프레임을 나열해 다른 출력의 중복을 막습니다. JavaScript로만 도입하는 애니메이션 이름은 @safelist keyframes "reveal";을 사용하세요.

런타임 키프레임 수명주기

런타임은 정의 ID와 이름을 별도로 추적하고 온디맨드 정의를 자신의 스타일시트에 삽입합니다. DOM 제거는 네이티브 사용, 정적 토큰, 세이프리스트 중 어느 것도 정의를 사용하지 않을 때만 이를 해제합니다. HMR은 정의와 emitted globals를 함께 교체하고 SSR 하이드레이션은 같은 ID와 리소스 순서를 사용합니다. 연결된 스타일시트는 동반 파일이나 표시 없이 일반 CSS로 유지됩니다.

Native keyframes

@keyframes fade-in { to { opacity: 1; } }

생성된 CSS

@keyframes fade-in {  to {    opacity: 1;  }}