Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / CSS

@property — registo tipado de uma propriedade personalizada

A regra @property regista uma propriedade personalizada com tipo de valor, herança e valor inicial.

Versão: CSS modules; structured CSSWG indexes reconciled with pinned MDN BCD; Chromium 152 scope gate, per-example verification still required

Sintaxe

@property <custom-property-name># {
  <declaration-list>
} | @property <custom-property-name> <css-type>? [ : <declaration-value>? ]? ;

A forma de bloco @property <custom-property-name># { <declaration-list> } pode registar um nome ou uma lista separada por vírgulas. O descritor syntax tem por omissão *, inherits ativa a herança por omissão e omitir initial-value mantém o valor inicial garantidamente inválido. A especificação também admite a instrução abreviada @property <custom-property-name> <css-type>? [ : <declaration-value>? ]? ;, que conserva sempre a herança predefinida.

O tipo registado é verificado no momento do valor calculado, não na análise inicial da declaração. Um valor inicial fornecido tem de corresponder à gramática; descritores desconhecidos são ignorados. Se várias regras registarem o mesmo nome, vence a última regra válida pela ordem da folha, enquanto um registo por CSS.registerProperty() tem precedência sobre todas.

O registo permite interpolar números, cores ou comprimentos e definir a herança de uma API de componente. O exemplo regista --tone como <color> sem herança. O valor incompatível 10px passa a análise da declaração mas falha ao calcular, portanto o descendente recebe o verde inicial; um azul válido continua azul. O objeto CSSPropertyRule confirma o nome e o indicador de herança.

Exemplos

const style = document.createElement('style');
style.textContent = `@property --tone { syntax: "<color>"; inherits: false; initial-value: rgb(0 128 0); }
.parent { --tone: red; }
.invalid { --tone: 10px; color: var(--tone); }
.valid { --tone: blue; color: var(--tone); }`;
document.head.append(style);
const parent = document.createElement('div');
parent.className = 'parent';
parent.innerHTML = '<span class="invalid">invalid</span><span class="valid">valid</span>';
document.body.append(parent);
const invalid = getComputedStyle(parent.children[0]);
const valid = getComputedStyle(parent.children[1]);
const rule = style.sheet.cssRules[0];
console.log('rule=' + rule.constructor.name + '; name=' + rule.name + '; invalid=' + invalid.getPropertyValue('--tone').trim() + '; valid=' + valid.getPropertyValue('--tone').trim() + '; inherits=' + rule.inherits);

Resultado

rule=CSSPropertyRule; name=--tone; invalid=rgb(0, 128, 0); valid=rgb(0, 0, 255); inherits=false

A regra @property regista uma propriedade personalizada com tipo de valor, herança e valor inicial.

Fontes