Impostazione Range Shopify: Correggi l'errore "Range Parameters Must Have at Most 101 Steps"

L'errore "Range settings must have at most 101 steps" significa che la tua combinazione di min, max e step genera più di 101 posizioni possibili nel slider. Correggilo aumentando step, riducendo max, oppure passando al tipo input number quando hai veramente bisogno di un ampio intervallo numerico. La causa è sempre aritmetica, non un bug.

Punti chiave

• Shopify limita le impostazioni range a massimo 101 step (applicato al momento del parsing dello schema).
• Il numero di step si calcola come (max - min) / step; il risultato deve essere 100 o inferiore.
• L'errore appare nell'editor tema Shopify e blocca il rendering della sezione.
• Cambiare step: 1 a un numero intero più alto è solitamente la soluzione più rapida.
• Quando hai bisogno di un input numerico senza limiti, sostituisci range con number.

Cos'è la regola dei 101 step?

Il tipo di input range di Shopify renderizza uno slider nell'editor tema. La piattaforma applica un limite rigido: lo slider può avere al massimo 101 posizioni (step da 0 a 100, inclusi). Shopify calcola internamente il numero di step come:

steps = (max - min) / step

Se questo calcolo produce un valore maggiore di 100, Shopify rifiuta lo schema e genera:

Error: Invalid schema: setting with id="[your_id]" step invalid.
Range settings must have at most 101 steps.

Questa convalida viene eseguita ogni volta che l'editor tema carica la sezione, quindi la sezione diventa completamente non funzionante finché lo schema non viene corretto.

Nota: Come confermato da Shopify nella loro documentazione sulle impostazioni di input, tutti e quattro gli attributi range (min, max, step, default) devono essere valori numerici, non stringhe. Passare una stringa per uno qualsiasi di essi genera un errore.

I tre trigger più comuni

Questi sono i pattern che vedo più spesso quando i merchant o gli sviluppatori junior si scontrano con questo problema:

1. Ampio intervallo con step: 1. Impostare min: 0, max: 500, step: 1 crea 500 step. Questo è il caso più frequente.
2. Aumentare un max esistente senza regolare lo step. Uno sviluppatore cambia max da 100 a 300 su uno slider di larghezza logo, dimenticando che lo step rimane a 1.
3. Copiare un range da un esempio di specifica HTML. Lo standard HTML consente qualsiasi numero di step; Shopify no.

Esempi reali dalla comunità includono uno slider free_shipping_threshold impostato a min: 0, max: 500, step: 1 e uno slider logo_max_width aumentato da 300px a 550px senza ricalcolare lo step.

Come calcolare se il tuo range è valido

Prima di scrivere una sola riga di schema, esegui questo controllo:

(max - min) / step <= 100   →  valido
(max - min) / step > 100    →  genererà l'errore dei 101 step

Esempi rapidi

Il limite è esattamente 100 step calcolati (che danno 101 posizioni dello slider includendo il punto di partenza). Qualsiasi valore superiore a 100 viene rifiutato.

Tre modi per correggerlo

1. Aumenta il valore dello step

Questa è la correzione corretta nella maggior parte dei casi. Uno slider di padding che va da 0 a 200px in step di 2 dà ai merchant 101 posizioni e rimane entro il limite.

{
  "type": "range",
  "id": "section_padding",
  "label": "Section padding",
  "min": 0,
  "max": 200,
  "step": 2,
  "unit": "px",
  "default": 40
}

Quando usare: Quasi sempre. La maggior parte dei valori di design (padding, dimensioni font, percentuali di opacità) non necessita di precisione a unità singola su un ampio intervallo.

2. Riduci il valore max

Se la precisione a step singolo è importante (per esempio, una valutazione da 1 a 5 stelle o una percentuale da 0 a 100), semplicemente riduci max per stare entro 100 step con step: 1.

{
  "type": "range",
  "id": "free_shipping_threshold",
  "label": "Free shipping threshold",
  "min": 0,
  "max": 100,
  "step": 1,
  "unit": "$",
  "default": 50
}

Questa soluzione verificata dalla comunità è stata la soluzione accettata per il caso free_shipping_threshold che si è diffuso nei forum Shopify.

3. Passa al tipo number

Quando hai veramente bisogno che un merchant inserisca qualsiasi numero intero (un ritardo di animazione in millisecondi, un conteggio di prodotti superiore a 100, una soglia che potrebbe essere 0-9999), il tipo range non è lo strumento giusto. Usa number invece.

{
  "type": "number",
  "id": "free_shipping_threshold",
  "label": "Free shipping threshold ($)",
  "default": 50
}

Il tipo number accetta qualsiasi numero intero, non ha limiti al numero di slider, ed è accessibile identicamente in Liquid tramite section.settings.free_shipping_threshold. Il compromesso è un input di testo invece di uno slider, quindi i merchant possono inserire valori fuori intervallo. Se i vincoli sono importanti, aggiungi un controllo Liquid nel codice della tua sezione.

Scegliere la correzione giusta: una tabella decisionale

Una cosa che molti tutorial saltano: range supporta solo interi

L'input range di Shopify non supporta valori di step decimali. Se hai bisogno di uno step di 0.1 per l'opacità, il workaround è memorizzare il valore come numero intero (da 0 a 100) e dividere per 100 nel tuo output Liquid:

{% assign opacity = section.settings.overlay_opacity | divided_by: 100.0 %}
<div style="opacity: {{ opacity }}">

Questo pattern è più pulito di quanto sembri: il merchant vede uno slider 0-100, il tuo CSS riceve un float 0.0-1.0. Non sono necessari hack.

Verificare la tua correzione prima di pubblicare

Theme Check, lo strumento CLI ufficiale di linting di Shopify, cattura questo errore durante lo sviluppo locale. Eseguilo prima di fare il push di qualsiasi modifica dello schema:

shopify theme check

Se stai lavorando direttamente nell'editor di codice dell'admin Shopify (senza una configurazione CLI locale), salva il file della sezione e ricarica l'anteprima dell'editor tema. L'errore appare come un banner rosso nella parte superiore del customizer se lo schema è ancora non valido.

Per uno sguardo più profondo a come Theme Check gestisce la convalida dello schema e gli errori di argomento, vedi Shopify Theme Check: Why a Single File Path Argument Does Not Work.

Checklist pratica prima di aggiungere qualsiasi impostazione range

Usa questa lista ogni volta che scrivi un nuovo blocco range:

• Calcola (max - min) / step e conferma che il risultato è 100 o inferiore.
• Conferma che tutti e quattro gli attributi (min, max, step, default) sono numeri interi, non stringhe.
• Conferma che default sia tra min e max.
• Domandati: questo valore beneficia veramente di uno slider? Se no, usa number, select o text.
• Testa nell'editor tema prima di fare il push in produzione.

Per una scomposizione completa di ogni tipo di input dello schema e quando usare ognuno, vedi la guida allo sviluppo dei temi Shopify.

Riepilogo

L'errore "range parameters must have at most 101 steps" è pura aritmetica. La formula (max - min) / step deve produrre 100 o meno. Aumenta il tuo step, riduci il tuo max, o passa al tipo number. Nessuna di queste correzioni richiede un aggiornamento del piano Shopify, una reinstallazione del tema, o un ticket di supporto. Comprendi il vincolo una volta e non lo colpirai mai più.