CSS 함수 및 믹스인 모듈

1. 소개

이 섹션은 규범적이지 않습니다.

참고: 현재 이 명세에서는 CSS 값 수준에서 동작하는 사용자 정의 함수만 정의합니다. 추후 스타일 규칙 수준에서 동작하는 "믹스인"도 정의될 예정입니다.

사용자 정의 속성은 저자가 한 곳에서 유용하고 때로는 복잡한 값을 정의하고 스타일시트 전반에 재사용할 수 있는 강력한 기능을 제공합니다. 이러한 값은 문서 전체 또는 미디어 쿼리나 기타 조건에 따라 달라질 수 있어 매우 유연하고 반응성이 높습니다.

하지만 그 값은 정의 시점에 고정되며, 이전 정의를 완전히 덮어쓰기 전에는 변경할 수 없습니다: --shadow: 2px 2px var(--shadow-color) 선언은 해당 요소에서 선언된 --shadow-color 값을 사용하고, 이후 자손 요소에서 --shadow-color를 변경해도 그 요소의 --shadow 값에는 영향을 주지 않습니다; --shadow가 정의된 위치의 그림자 색상을 계속 사용합니다. 이는 이처럼 복합 변수(composite variable)를 많이 사용하는 저자들에게 흔히 혼란을 야기합니다.

사용자 정의 함수는 사용자 정의 속성과 동일한 강력함을 제공하지만, 매개변수화가 가능합니다: 사용자 정의 속성 정의와 같은 유연성과 조건부 기능을 가지면서도, 다른 사용자 정의 속성(또는 명시적으로 인자)에서 사용 시점에 값을 가져옵니다. 예를 들어, --shadow 사용자 정의 속성 대신, --shadow() 사용자 정의 함수를 다음과 같이 정의할 수 있습니다:

@function --shadow(--shadow-color <color> : inherit) {
  /* --shadow-color 인자가 전달되지 않거나,
     <color>로 정상적으로 파싱되지 않으면,
     대신 해당 요소의 --shadow-color *속성*을 사용 */

  /* var(--shadow-color)는 --shadow-color 파라미터를 참조하며,
     사용자 정의 속성을 참조하는 것이 아니지만,
     여전히 보통처럼 폴백 값을 사용할 수 있음 */
  result: 2px 2px var(--shadow-color, black);
}

.foo {
  --shadow-color: blue;
  box-shadow: --shadow(); /* 파란 그림자 생성 */
  /* 또는 */
  box-shadow: --shadow(blue);
}

2. 사용자 정의 함수 정의

사용자 정의 함수는 고급 사용자 정의 속성으로 볼 수 있습니다. 단일 고정 값으로 대체되는 대신, 함수 파라미터 및 호출 시점의 사용자 정의 속성 값을 기반으로 대체 값을 계산합니다. 사용자 정의 속성의 var() 문법 대신, 사용자 정의 함수는 <dashed-function> 문법으로 호출되며, 추가 값을 인자로 전달할 수 있습니다.

@function --negative(--value) {
  result: calc(-1 * var(--value));
}

html {
  --gap: 1em;
  padding: --negative(var(--gap));
  /* 또는 값을 직접 전달할 수도 있음: */
  padding: --negative(1em);
}

<dashed-function>은 임의 치환 함수이며, var()와 유사합니다. 속성 값에 존재하면 파싱 시점에는 유효하다고 간주되며, 임의 치환이 발생한 후 계산값(computed-value) 시점에 평가 및 파싱됩니다.

2.1. @function 규칙

@function 규칙은 사용자 정의 함수를 정의하며, 이름, 파라미터 목록, 함수 본문, 그리고 선택적으로 반환 타입(문법 정의로 기술됨)을 포함합니다.

각 함수 파라미터는 이름(<custom-property-name>), 선택적으로 파라미터 타입(문법 정의로 기술됨), 그리고 선택적으로 기본값으로 구성됩니다.

<@function> = @function <function-token> <function-parameter>#? )
  [ returns <css-type> ]?
{
  <declaration-rule-list>
}

<function-parameter> = <custom-property-name> <css-type>? [ : <declaration-value> ]?
<css-type> = <syntax-component> | <type()>
<type()> = type( <syntax> )

2.1.1. 함수 서두

<function-token> 생성식은 <dashed-ident>처럼 반드시 두 개의 하이픈(U+002D HYPHEN-MINUS)으로 시작해야 하며, 그렇지 않으면 정의가 무효입니다.

생성된 사용자 정의 함수의 이름은 <function-token>의 이름으로, 선택적 함수 파라미터는 <function-parameter> 값으로 (기본값: 빈 집합), 선택적 반환 타입은 returns 키워드 뒤의 <css-type>으로 (기본값: type(*)) 지정됩니다.

@function --foo(--a <length>) { /* ... */ }
@function --foo(--a <color>) { /* ... */ }
@function --foo(--a <length>+) { /* ... */ }

@function --foo(--a type(<number> | <percentage>)) { /* ... */ }

@function 규칙의 이름은 트리 범위 이름입니다. 동일한 이름의 @function이 둘 이상 존재할 경우, 더 강한 계단식 레이어의 규칙이 우선하며, 같은 레이어 내에서는 나중에 정의된 규칙이 우선합니다.

함수 파라미터에 동일한 <custom-property-name>이 두 번 이상 포함되면, 해당 @function 규칙은 무효입니다.

2.1.2. 함수 본문

@function 규칙의 본문은 조건부 그룹 규칙(예: @media)을 허용합니다. 또한 다음 기술자를 허용합니다:

• result 기술자: 함수 평가의 결과를 결정합니다. result 기술자가 없으면 함수는 유효하지만 항상 보장된-무효 값을 반환합니다.

• 사용자 정의 속성: 지역 변수를 제공합니다.

알 수 없는 기술자는 무효로 간주되어 무시되지만, @function 규칙 자체는 무효가 아닙니다.

2.2. result 기술자

result 기술자는 함수를 평가할 때 사용자 정의 함수가 반환하는 결과를 정의합니다. var() 함수를 사용해 함수 파라미터, 지역 변수, 그리고 <dashed-function>을 통해 다른 사용자 정의 함수도 참조할 수 있습니다.

result 기술자 자체는 타입이 없지만, 해결된 값은 치환 시 <dashed-function>의 타입 검사를 받습니다.

2.3. 인자 및 지역 변수

이 섹션은 비규범적입니다.

사용자 정의 함수의 함수 본문 내에서 var() 함수는 지역 변수(함수 본문에 정의된 사용자 정의 속성), 함수 인자(함수에 전달된 값 또는 기본값), 그리고 호출 위치(요소 또는 다른 사용자 정의 함수)에 정의된 사용자 정의 속성에 접근할 수 있습니다.

이 목록에서, 앞에 있는 것이 같은 이름일 경우 "이깁니다" — 만약 지역 변수 --foo가 있으면 var(--foo)는 그 지역 변수로 치환되고, 인자나 외부에서 정의된 사용자 속성으로 치환되지 않습니다. 다른 값들도 접근은 가능합니다: --foo 지역 변수를 initial로 설정하면 그 인자 값으로, inherit로 설정하면 호출 위치의 --foo 사용자 속성 값으로 처리됩니다.

@function --outer(--outer-arg) {
  --outer-local: 2;
  result: --inner();
}
@function --inner() returns <number> {
  result: calc(var(--outer-arg) + var(--outer-local));
}
div {
  z-index: --outer(1); /* 3 */
}

@function --double-z() returns <number> {
  result: calc(var(--z) * 2);
}
div {
  --z: 3;
  z-index: --double-z(); /* 6 */
}

@function --add-a-b-c(--b, --c) {
  --c: 300;
  result: calc(var(--a) + var(--b) + var(--c));
  /* 호출 위치의 --a 사용자 정의 속성,
     함수 인자의 --b,
     그리고 지역 변수의 --c를 사용 */
}
div {
  --a: 1;
  --b: 2;
  --c: 3;
  z-index: --add-a-b-c(20, 30); /* 321 */
}

3. 사용자 정의 함수 사용

사용자 정의 속성의 값이 var()로 다른 속성 값에 치환될 수 있는 것처럼, 사용자 정의 함수의 평가 결과도 <dashed-function>으로 속성 값에 치환할 수 있습니다.

<dashed-function>은 함수 이름이 두 개의 하이픈(U+002D HYPHEN-MINUS)으로 시작하는 함수형 표기입니다. 그 인자 문법은 다음과 같습니다:

<dashed-function> = --*( <declaration-value>#? )

<dashed-function>은 var()가 허용되는 위치에서만 사용할 수 있습니다.

속성에 하나 이상의 <dashed-function>이 포함되어 있으면, 해당 속성의 전체 문법은 파싱 시점에 항상 유효하다고 간주됩니다. 계산값(computed-value) 시점에 모든 <dashed-function>은 치환되어야 하고, 그 후 속성의 문법과 검증됩니다.

참고: 사용자 정의 함수의 본문 내에서 var() 함수는, <dashed-function>이 사용된 요소에서와는 다르게 해석될 수 있습니다. § 3.1 사용자 정의 함수 평가 참고.

<dashed-function>은 어떤 컨텍스트에서 평가됩니다: 요소의 속성 값에서 (또는 @keyframes 등 결국 요소의 속성처럼 처리되는 기술자에서), 혹은 다른 사용자 정의 함수의 함수 본문에서 "가상의" 요소에 대해 기술자에서. 어느 경우든, 이것은 호출 컨텍스트를 제공하며, 여기에는 <dashed-function>이 포함된 속성/기술자 이름과, 그 속성/기술자가 적용되는 요소(또는 "가상의" 요소)가 포함됩니다.

호출 컨텍스트가 <dashed-function> 평가에 의해 중첩될 때, 호출 컨텍스트의 루트 요소는 호출 컨텍스트 스택의 최상위 실제 요소입니다.

@function --max-plus-x(--list, --x) {
  result: calc(max(var(--list)) + var(--x));
}
div {
  width: --max-plus-x({ 1px, 7px, 2px }, 3px); /* 10px */
}

@function --foo(--x) {
  result: --foo(10);
}

@function --bar() {
  --x: --bar();
  result: 1;
}

@function --baz(--x) {
  @media (unknown-feature) {
    result: --baz(42);
  }
  result: 1;
}

@function --baz(--x) {
  --y: 10px;
  result: calc(var(--x) + var(--y));
}

div {
  --x: --baz(1px);
  --y: --baz(2px);
  width: var(--x);  /* 11px */
  height: var(--y); /* 12px */
}

3.1. 사용자 정의 함수 평가

사용자 정의 함수는 본질적으로 함수 본문을 스타일 규칙처럼 가상의 요소에 적용한다고 가정하고, 일반적인 스타일 해석을 수행한 뒤, 그 가상의 요소의 result 기술자 값을 반환함으로써 평가됩니다. 가상의 요소는 호출 컨텍스트의 자식처럼 모든 사용자 정의 속성 값을 "상속"하고, 함수 인자가 동일 이름의 "상속된" 사용자 속성 값을 덮어씁니다.

4. 커스텀 함수의 실행 모델

CSS의 다른 부분과 마찬가지로, 커스텀 함수도 선언적 모델을 따릅니다.

지역 변수 기술자와 result 기술자는 어떤 순서로든 나타날 수 있으며, 여러 번 작성해도 됩니다. 이런 경우, 나중에 등장한 선언이 더 앞선 선언을 덮어씁니다.

@function --mypi() {
  result: 3;
  result: 3.14;
}

@function --circle-area(--r) {
  result: calc(pi * var(--r2));
  --r2: var(--r) * var(--r);
}

4.1. 조건부 규칙

조건부 그룹 규칙이 @function 안에 나타나면 중첩 그룹 규칙이 되고, 추가적으로 @function 내에서 허용된 기술자만 중첩 그룹 규칙 내에 쓸 수 있습니다.

조건부 그룹 규칙은 @function 내에서 일반 규칙대로 처리되며, 조건이 true일 때 규칙 내용이 해당 위치에 있는 것처럼 동작하고, 그렇지 않으면 아무것도 없는 것처럼 동작합니다.

@function --suitable-font-size() {
  result: 16px;
  @media (width > 1000px) {
    result: 20px;
  }
}

@function --suitable-font-size() {
  @media (width > 1000px) {
    result: 20px;
  }
  result: 16px;
}

@function --suitable-font-size() {
  --size: 16px;
  @media (width > 1000px) {
    --size: 20px;
  }
  result: var(--size);
}

5. CSSOM

5.1. CSSFunctionRule 인터페이스

CSSFunctionRule 인터페이스는 @function 규칙을 나타냅니다.

[Exposed=Window]
interface CSSFunctionRule : CSSGroupingRule {
  readonly attribute CSSOMString name;
  sequence<FunctionParameter> getParameters();
  readonly attribute CSSOMString returnType;
};

name, 타입 CSSOMString, 읽기 전용

커스텀 함수의 이름입니다.

returnType, 타입 CSSOMString, 읽기 전용

커스텀 함수의 문법 문자열로 표현된 반환 타입입니다. 커스텀 함수에 반환 타입이 없는 경우, "type(*)"을 반환합니다.

dictionary FunctionParameter {
  required CSSOMString name;
  required CSSOMString type;
  CSSOMString? defaultValue;
};

name

함수 인자의 이름입니다.

type

함수 인자의 타입으로, 문법 문자열로 표현되며, 인자에 타입이 없으면 "type(*)"입니다.

defaultValue

함수 인자의 기본값, 인자에 기본값이 없으면 `null`입니다.

@function 규칙 내에 선언을 직접 명시할 수 있지만, CSSOM에서는 그렇게 표현되지 않습니다. 대신 연속된 선언 구간이 CSSFunctionDeclarations 규칙으로 래핑된 것처럼 나타납니다.

참고: 이는 @function 규칙의 맨 앞 선언(즉, 다른 중첩 규칙 뒤에 오지 않은 선언)에도 적용됩니다.

@function --bar() {
  --x: 42;
  result: var(--y);
  @media (width > 1000px) {
    /* ... */
  }
  --y: var(--x);
}

@function --bar() {
  /* CSSFunctionDeclarations { */
    --x: 42;
    result: var(--y);
  /* } */
  @media (width > 1000px) {
    /* ... */
  }
  /* CSSFunctionDeclarations { */
    --y: var(--x);
  /* } */
}

5.2. CSSFunctionDeclarations 인터페이스

CSSFunctionDeclarations 인터페이스는 선언이 @function 규칙 내에서 연속적으로 나타나는 부분을 나타냅니다.

[Exposed=Window]
interface CSSFunctionDescriptors : CSSStyleDeclaration {
  attribute [LegacyNullToEmptyString] CSSOMString result;
};

[Exposed=Window]
interface CSSFunctionDeclarations : CSSRule {
  [SameObject, PutForwards=cssText] readonly attribute CSSFunctionDescriptors style;
};

CSSFunctionDeclarations 규칙은 CSSNestedDeclarations와 같이, 직렬화될 때 선언 블록이 선언 블록이 직접 직렬화된 것처럼 나타납니다.

6. 프라이버시 고려사항

이 명세서에서 정의된 구조체들은 모두 CSS 내부에서만 정의되고 사용되며, 새로운 정보를 노출하지 않습니다.

7. 보안 고려사항

이 명세서에는 아직 제기된 이슈가 없습니다.