Valores de Atributo

Atributos são como o OneEntry descreve o conteúdo: uma página, produto, bloco, usuário, pedido ou campo de formulário carrega um mapa de valores de atributo indexados por marcador. O SDK normaliza cada atributo de cada resposta para a mesma forma, então o mesmo campo parece o mesmo, não importa qual módulo o retornou.

const page = await Pages.getPageByUrl('catalog');

page.attributeValues.title.value;   // "Catalog"        — string
page.attributeValues.amount.value;  // 5                — number
page.attributeValues.cover.value;   // { downloadLink } — the file object itself
page.attributeValues.notes.value;   // null             — no value set

A forma normalizada

Um valor de atributo é um IAttributeValue: { type, value, position?, additionalFields? }. O que value contém depende de type:

Tipo de atributo	value
string, text	string
integer, float, real	number — convertido da forma de string da API
image, file com um arquivo	o próprio objeto de arquivo
image, file com vários arquivos	um array de objetos de arquivo
groupOfImages	sempre um array — é uma coleção por definição
list	um array
timeInterval	um array de grupos — veja Intervalos de Tempo
nenhum valor definido	sempre null

Atributos de arquivo único são descompactados

Quando um atributo image ou file contém exatamente um arquivo, seu value é o próprio objeto de arquivo. Apenas valores com dois ou mais arquivos permanecem como um array.

const block = await Blocks.getBlockByMarker('promo');

// before: block.attributeValues.img.value[0].downloadLink
// now:    block.attributeValues.img.value.downloadLink

Isso se aplica em todos os módulos. Anteriormente, a descompactação ocorria apenas em produtos, menus, formulários, campos de dados de formulários, conjuntos de atributos, coleções de integração e Pages.searchPage, e apenas na chave attributeValues — em todos os outros lugares (blocos, todos os outros métodos de páginas, Products.getProductsEmptyPage, Products.getProductBlockById, admins, descontos, templates, pedidos, usuários) o mesmo atributo chegava como um array de um elemento, então os consumidores tinham que ramificar com base na forma. Os attributes de formulário, campos de dados de formulário e additionalFields aninhados nunca foram descompactados.

⚠️ Migração: código que lê value[0] de produtos ou menus não é afetado — esses módulos já retornavam o objeto. Código que lê value[0] de blocos, páginas, usuários ou pedidos deve remover o índice.

groupOfImages é uma coleção por definição e sempre permanece como um array. No lado da solicitação, IBodyTypeFile.value é tipado como IFileValue | IFileValue[] de acordo.

Números são números

Valores integer, float e real são convertidos para um número. real costumava ser deixado como uma string, então o mesmo campo numérico chegava ao consumidor como 10 ou como "10", dependendo de qual dos três tipos foi declarado:

const page = await Pages.getPageByUrl('catalog');

// before: page.attributeValues.amount.value // "5"
// now:    page.attributeValues.amount.value // 5

A normalização numérica também ocorre em atributos de formulário e campos de dados de formulário, que foram totalmente ignorados — um campo de rating de um atributo de formulário integer é um number, não uma string.

Ao enviar dados, envie uma string: IBodyTypeStringNumberFloat.value é string | number | null, e as respostas voltam normalizadas.

Um valor vazio é sempre nulo

A API retorna um mapa de localização vazio para um valor não definido. O SDK costumava passar isso para tipos semelhantes a texto, enquanto tipos numéricos se tornavam null — o mesmo estado de "sem valor" tinha três representações. Agora é sempre null.

if (page.attributeValues.notes.value === null) {
  // nothing configured for this attribute
}

⚠️ Migração: um integer/float não definido não é mais 0. Number(null) é 0, então um null explícito da API costumava ser relatado como um zero real — um valor indistinguível de um 0 configurado.

Tudo é ordenado por posição

attributeValues sempre foi retornado na ordem de position, e os attributes de formulário agora também são. A API retorna campos de formulário desordenados — um campo com position: 10 poderia chegar após position: 14 — então renderizar um formulário na ordem do CMS exigia ordenação do lado do consumidor.

Um formulário sem atributos retorna attributes: []. A API envia um objeto vazio nesse caso, e o SDK o normaliza para um array vazio, então attributes é sempre IFormAttribute[] e form.attributes.map(...) é seguro em todos os formulários.

Campos aninhados: additionalFields

Valores de atributo aninhados chegam sob additionalFields. Por padrão, o SDK converte o array que a API retorna em um objeto indexado por marker; defina rawData: true na configuração para manter o array original — veja Formato de Campos Adicionais.

// default (rawData: false)
attribute.additionalFields['my_field'].value;

// rawData: true
attribute.additionalFields.find((f) => f.marker === 'my_field').value;

additionalFields aninhados passam pela mesma normalização que atributos de nível superior — arquivos únicos são descompactados e números também são convertidos lá.

Tipando um valor de atributo

IAttributeValue.value é tipado como unknown, porque sua forma depende de type. Restringa-o antes do uso — para atributos timeInterval, o SDK fornece um guardião de tipo:

import { isTimeIntervalAttribute } from 'oneentry';
import type { IAttributeValues } from 'oneentry';

function readText(values: IAttributeValues, marker: string): string {
  const value = values[marker]?.value;
  return typeof value === 'string' ? value : '';
}

---

🔗 Documentação Relacionada

• Intervalos de Tempo - expandindo atributos timeInterval em slots
• Importando Tipos - IAttributeValue, IAttributeValues e o resto
• Módulo AttributesSets - como os atributos são configurados

---