掌握 CSS：使用 @property 注册自定义属性

自定义属性（也称为 CSS 变量）彻底改变了我们编写和维护 CSS 的方式。它们允许我们定义可重用的值，使我们的样式表更具灵活性和可维护性。但是，如果您可以超越简单地定义值呢？如果您可以定义自定义属性所持有的值的类型，以及它的初始值和继承行为呢？这就是 @property 的用武之地。

什么是 @property？

@property 是一个 CSS at-rule，它允许您显式地向浏览器注册一个自定义属性。此注册过程为浏览器提供了有关属性的预期类型、其初始值以及是否应从其父元素继承的信息。这解锁了几个高级功能，包括：

• 类型检查：确保为自定义属性分配正确类型的值。
• 动画：为特定类型的自定义属性（如数字或颜色）启用平滑的过渡和动画。
• 默认值：如果未在元素上显式定义自定义属性，则提供一个备用值。
• 继承控制：确定自定义属性是否从其父元素继承其值。

将其视为在 CSS 变量中添加类型安全性。它允许您创建更健壮、更可预测的样式表。

@property 的语法

@property 规则遵循以下基本语法：

@property --property-name {
  syntax: '';
  inherits: true | false;
  initial-value: ;
}

让我们分解一下每个部分：

• --property-name：您要注册的自定义属性的名称。它必须以两个连字符（--）开头。
• syntax：定义属性的预期值类型。这对于类型检查和动画至关重要。我们将在下面详细探讨可用的语法值。
• inherits：一个布尔值，指示属性是否应从其父元素继承。如果未指定，则默认为 false。
• initial-value：如果未在元素上显式设置，则该属性的默认值。这可确保始终提供备用值。

理解 syntax 描述符

syntax 描述符是 @property 规则中最重要的部分。它告诉浏览器该自定义属性预期什么类型的值。以下是一些常见的语法值：

• *：允许任何值。这是最宽松的语法，基本上复制了标准 CSS 变量在没有注册时的行为。请谨慎使用此选项。
• <length>：期望一个长度值（例如，10px、2em、50%）。这使得在不同长度值之间进行平滑动画成为可能。
• <number>：期望一个数值（例如，1、3.14、-5）。对于动画不透明度或缩放等数值属性很有用。
• <percentage>：期望一个百分比值（例如，25%、100%）。
• <color>：期望一个颜色值（例如，#f00、rgb(255, 0, 0)、hsl(0, 100%, 50%)）。可以实现平滑的颜色过渡和动画。
• <image>：期望一个图像值（例如，url(image.jpg)、linear-gradient(...)）。
• <integer>：期望一个整数值（例如，1、-10、0）。
• <angle>：期望一个角度值（例如，45deg、0.5rad、200grad）。对于动画旋转很有用。
• <time>：期望一个时间值（例如，1s、500ms）。通过自定义属性控制动画持续时间或延迟很有用。
• <resolution>：期望一个分辨率值（例如，300dpi、96dpi）。
• <transform-list>：期望一个变换函数列表（例如，translateX(10px) rotate(45deg)）。允许动画复杂的变换。
• <custom-ident>：期望一个自定义标识符（一个字符串）。类似于 enum。
• <string>：期望一个字符串值（例如，"Hello World"）。要小心使用此选项，因为通常不支持字符串动画。
• 自定义语法：您可以使用上述值的组合以及 |（或）、[]（分组）、+（一个或多个）、*（零个或多个）和 ?（零个或一个）运算符来创建更复杂的语法。例如：<length> | <percentage> 允许长度或百分比值。

选择正确的 syntax 对于利用 @property 的全部功能至关重要。

@property 的实际示例

让我们看一些在 CSS 中使用 @property 的实际示例。

示例 1：动画背景颜色

假设您想为按钮的背景颜色设置动画。您可以使用 @property 为背景颜色注册一个自定义属性，然后使用 CSS 过渡对其进行动画处理。

@property --bg-color {
  syntax: '<color>';
  inherits: false;
  initial-value: #fff;
}

.button {
  background-color: var(--bg-color);
  transition: --bg-color 0.3s ease;
}

.button:hover {
  --bg-color: #f00; /* Red */
}

在此示例中，我们使用 <color> 语法注册了 --bg-color 自定义属性，这意味着它期望一个颜色值。initial-value 设置为白色（#fff）。当鼠标悬停在按钮上时，--bg-color 会更改为红色（#f00），并且过渡会平滑地动画背景颜色变化。

示例 2：使用数字控制边框半径

您可以使用 @property 来控制元素的边框半径并对其进行动画处理。

@property --border-radius {
  syntax: '<length>';
  inherits: false;
  initial-value: 0px;
}

.rounded-box {
  border-radius: var(--border-radius);
  transition: --border-radius 0.5s ease;
}

.rounded-box:hover {
  --border-radius: 20px;
}

在这里，我们将 --border-radius 注册为 <length>，确保它接受 px、em 或 % 等长度值。初始值为 0px。当鼠标悬停在 .rounded-box 上时，边框半径会动画到 20px。

示例 3：动画阴影偏移

假设您想为盒阴影的水平偏移设置动画。

@property --shadow-offset-x {
  syntax: '<length>';
  inherits: false;
  initial-value: 0px;
}

.shadowed-box {
  box-shadow: var(--shadow-offset-x) 5px 10px rgba(0, 0, 0, 0.5);
  transition: --shadow-offset-x 0.3s ease;
}

.shadowed-box:hover {
  --shadow-offset-x: 10px;
}

在此示例中，--shadow-offset-x 以 <length> 形式注册，其初始值为 0px。box-shadow 属性在其水平偏移中使用此自定义属性。鼠标悬停时，偏移量会动画到 10px。

示例 4：使用 <custom-ident> 进行主题化

<custom-ident> 语法允许您定义一组预定义的字符串值，从而有效地为 CSS 变量创建枚举。这对于主题化或控制不同的状态非常有用。

@property --theme {
  syntax: '<custom-ident>';
  inherits: true;
  initial-value: light;
}

:root {
  --theme: light; /* Default Theme */
}

body {
  background-color: var(--theme) == light ? #fff : #333;
  color: var(--theme) == light ? #000 : #fff;
}

.dark-theme {
  --theme: dark;
}

在此，--theme 使用 <custom-ident> 语法进行注册。虽然我们没有在 @property 规则本身中显式列出允许的标识符，但代码暗示它们是 `light` 和 `dark`。然后，CSS 使用条件逻辑（var(--theme) == light ? ... : ...）来根据当前主题应用不同的样式。将 dark-theme 类添加到元素将把主题切换为 dark。请注意，使用 var() 的条件逻辑不是标准的 CSS，通常需要预处理器或 JavaScript。更标准的方法将使用 CSS 类和级联：

@property --theme {
  syntax: '<custom-ident>';
  inherits: true;
  initial-value: light;
}

:root {
  --theme: light;
}

body {
  background-color: #fff;
  color: #000;
}

body[data-theme="dark"] {
  background-color: #333;
  color: #fff;
}

/* JavaScript to toggle the theme */
/* document.body.setAttribute('data-theme', 'dark'); */

在此修订示例中，我们使用 body 元素上的 data-theme 属性来控制主题。JavaScript（已注释掉）将用于在 `light` 和 `dark` 之间切换属性。这是使用 CSS 变量进行主题化的更健壮、更标准的方法。

使用 @property 的好处

使用 @property 可带来多项优势：

• 提高代码可读性和可维护性：通过显式定义自定义属性值的预期类型，您可以使代码更易于理解，并且不易出错。
• 增强的动画功能：@property 支持自定义属性的平滑过渡和动画，为创建动态且引人入胜的用户界面开辟了新的可能性。
• 更好的性能：浏览器可以优化使用已注册自定义属性的元素的渲染，从而提高性能。
• 类型安全：浏览器会验证分配的值是否与声明的语法匹配，从而防止意外行为并使调试更容易。这在大项目或多开发人员协作的项目中尤其有用。
• 默认值：确保自定义属性始终具有有效值，即使它未被显式设置，也可以防止错误并提高 CSS 的健壮性。

浏览器兼容性

截至 2023 年末，@property 具有良好但并非普遍的浏览器支持。它在大多数现代浏览器中得到支持，包括 Chrome、Firefox、Safari 和 Edge。但是，旧版浏览器可能不支持它。在使用 @property 生产环境之前，请务必在 Can I use... 等网站上查看最新的浏览器兼容性信息。

为了处理旧版浏览器，您可以使用功能查询（@supports）来提供回退样式：

@supports (--property: value) {
  /* 使用 @property 的样式 */
}

@supports not (--property: value) {
  /* 不支持 @property 的浏览器的回退样式 */
}

将 --property 和 value 替换为实际的自定义属性及其值。

何时使用 @property

在以下情况下，请考虑使用 @property：

• 当您需要为自定义属性设置动画时：这是 @property 的主要用例。使用正确的语法注册属性可以实现平滑的动画。
• 当您想强制自定义属性的类型安全时：如果您想确保自定义属性始终保持特定类型的值，请使用 @property 进行注册。
• 当您想为自定义属性提供默认值时：initial-value 描述符允许您指定一个备用值。
• 在大型项目中：@property 增强了代码的可维护性并防止了错误，这对于多开发人员参与的大型项目尤其有利。
• 在创建可重用组件或设计系统时：@property 有助于确保组件之间的一致性和可预测性。

要避免的常见错误

• 忘记 syntax 描述符：没有 syntax 描述符，浏览器将不知道预期的值类型，并且动画将无法正常工作。
• 使用错误的 syntax 值：选择错误的语法可能导致意外行为。请确保选择准确反映预期值类型的语法。
• 未提供 initial-value：如果没有初始值，自定义属性可能未定义，从而导致错误。请始终提供合理的默认值。
• 过度使用 * 作为语法：虽然方便，但使用 * 会削弱类型检查和动画的好处。仅在您确实需要允许任何类型的值时使用它。
• 忽略浏览器兼容性：始终检查浏览器兼容性，并为旧版浏览器提供回退样式。

@property 与 CSS Houdini

@property 是称为 CSS Houdini 的 API 集合的一部分。Houdini 允许开发人员访问浏览器的渲染引擎，从而使他们能够前所未有地控制样式和布局过程。其他 Houdini API 包括：

• Paint API：允许您定义自定义背景图像和边框。
• Animation Worklet API：提供了一种创建在浏览器合成器线程中直接运行的高性能动画的方法。
• Layout API：允许您定义自定义布局算法。
• Parser API：提供对浏览器 CSS 解析器的访问。

@property 是一个相对容易学习的 Houdini API，但它为您探索更高级的 Houdini 功能打开了大门。

结论

@property 是一个强大的 CSS at-rule，它为自定义属性解锁了高级功能。通过向浏览器注册自定义属性，您可以强制执行类型安全，实现平滑的动画，并提高 CSS 代码的整体健壮性。虽然浏览器支持并非普遍存在，但使用 @property 的好处，尤其是在大型项目和设计系统中，使其成为现代 Web 开发的宝贵工具。拥抱 @property，将您的 CSS 技能提升到一个新的水平！