Paramètre Range Shopify: Corriger l'erreur « 101 étapes maximum »

L'erreur « Range settings must have at most 101 steps » signifie que votre combinaison min, max et step produit plus de 101 positions de curseur possibles. Corrigez-la en augmentant step, en réduisant max, ou en basculant vers le type d'entrée number quand vous avez vraiment besoin d'une plage numérique large. La cause racine est toujours arithmétique, pas un bogue.

Points clés à retenir

• Shopify limite les paramètres range à 101 étapes maximum (appliqué au moment de l'analyse du schéma).
• Le nombre d'étapes est calculé comme (max - min) / step ; ce résultat doit être inférieur ou égal à 100.
• L'erreur apparaît dans l'éditeur de thème Shopify et empêche la section de s'afficher.
• Changer step: 1 par un entier plus grand est généralement le correctif le plus rapide.
• Quand vous avez besoin d'une entrée entière sans limite, remplacez range par number.

Qu'est-ce que la règle des 101 étapes ?

Le type d'entrée range de Shopify affiche un curseur dans l'éditeur de thème. La plateforme impose une limite stricte : le curseur peut avoir au maximum 101 positions (étapes 0 à 100, incluses). Shopify calcule le nombre d'étapes en interne comme :

steps = (max - min) / step

Si ce calcul produit une valeur supérieure à 100, Shopify rejette le schéma et génère :

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

Cette validation s'exécute chaque fois que l'éditeur de thème charge la section, donc la section devient complètement non fonctionnelle jusqu'à ce que le schéma soit corrigé.

Remarque : Comme Shopify l'a confirmé dans leur documentation sur les paramètres d'entrée, les quatre attributs range (min, max, step, default) doivent être des valeurs numériques, pas des chaînes. Passer une chaîne pour n'importe lequel d'entre eux génère également une erreur.

Les trois déclencheurs les plus courants

Voici les modèles que je vois le plus souvent quand les commerçants ou les développeurs juniors rencontrent ce problème :

1. Grande plage avec step: 1, Définir min: 0, max: 500, step: 1 crée 500 étapes. C'est le cas le plus fréquent.
2. Augmenter un max existant sans ajuster l'étape, Un développeur change max de 100 à 300 sur un curseur de largeur de logo, oubliant que l'étape reste à 1.
3. Copier un range depuis un exemple de spec HTML, HTML standard autorise n'importe quel nombre d'étapes ; Shopify ne le fait pas.

Les exemples réels de la communauté incluent un curseur free_shipping_threshold défini sur min: 0, max: 500, step: 1 et un curseur logo_max_width passé de 300px à 550px sans recalculer l'étape.

Comment calculer si votre range est valide

Avant d'écrire une seule ligne de schéma, exécutez cette vérification :

(max - min) / step <= 100   →  valide
(max - min) / step > 100    →  génère l'erreur 101 étapes

Exemples rapides

La limite est exactement 100 étapes calculées (ce qui donne 101 positions de curseur incluant le point de départ). Toute valeur supérieure à 100 est rejetée.

Trois façons de corriger

1. Augmenter la valeur step

C'est le correctif correct dans la plupart des cas. Un curseur de remplissage qui va de 0 à 200px par étapes de 2 donne aux commerçants 101 positions et reste dans la limite.

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

Quand l'utiliser : Presque toujours. La plupart des valeurs de conception (remplissage, tailles de police, pourcentages d'opacité) n'ont pas besoin de précision d'une unité sur une large plage.

2. Réduire la valeur max

Si la précision d'une seule étape compte (par exemple, une évaluation par étoiles de 1 à 5 ou un pourcentage de 0 à 100), réduisez simplement max pour rester dans 100 étapes à step: 1.

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

Ce correctif vérifié par la communauté était la solution acceptée pour le cas free_shipping_threshold qui s'est propagé dans les forums Shopify.

3. Basculer vers le type number

Quand vous avez vraiment besoin qu'un commerçant entre n'importe quel entier (un délai d'animation en millisecondes, un nombre de produits supérieur à 100, un seuil pouvant être 0-9999), le type range n'est pas du tout le bon outil. Utilisez number à la place.

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

Le type number accepte n'importe quel entier, n'a pas de limite de curseur, et est accédé de manière identique dans Liquid via section.settings.free_shipping_threshold. Le compromis est un champ de texte au lieu d'un curseur, donc les commerçants peuvent entrer des valeurs en dehors de la plage. Si les garde-fous comptent, ajoutez une vérification Liquid dans le code de votre section.

Choisir le bon correctif : un tableau de décision

Une chose que beaucoup de tutoriels sautent : range supporte uniquement les entiers

L'entrée range de Shopify ne supporte pas les valeurs step décimales. Si vous avez besoin d'une étape de 0.1 pour l'opacité, la solution consiste à stocker la valeur sous forme d'entier (0 à 100) et à diviser par 100 dans votre sortie Liquid :

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

Ce modèle est plus propre qu'il n'y paraît : le commerçant voit un curseur 0-100, votre CSS obtient un flottant 0.0-1.0. Aucun hack nécessaire.

Vérifier votre correctif avant de publier

Theme Check, l'outil CLI officiel de Shopify, détecte cette erreur pendant le développement local. Exécutez-le avant de pousser tout changement de schéma :

shopify theme check

Si vous travaillez directement dans l'éditeur de code Shopify admin (sans configuration CLI locale), enregistrez le fichier de section et rechargez l'aperçu de l'éditeur de thème. L'erreur apparaît sous forme de bannière rouge en haut du personnaliseur si le schéma n'est toujours pas valide.

Pour un examen plus approfondi de la façon dont Theme Check gère la validation du schéma et les erreurs d'argument, voir Shopify Theme Check: Why a Single File Path Argument Does Not Work.

Liste de contrôle pratique avant d'ajouter un paramètre range

Utilisez cette liste chaque fois que vous écrivez un nouveau bloc range :

• Calculez (max - min) / step et confirmez que le résultat est 100 ou moins.
• Confirmez que les quatre attributs (min, max, step, default) sont des entiers, pas des chaînes.
• Confirmez que default se situe entre min et max.
• Demandez-vous : cette valeur bénéficie-t-elle vraiment d'un curseur ? Si non, utilisez number, select ou text.
• Testez dans l'éditeur de thème avant de pousser en production.

Pour une ventilation complète de chaque type d'entrée de schéma et quand utiliser chacun, voir le guide de développement de thème Shopify.

Résumé

L'erreur « range parameters must have at most 101 steps » est pure arithmétique. La formule (max - min) / step doit produire 100 ou moins. Augmentez votre étape, limitez votre max, ou basculez vers le type number. Aucun de ces correctifs ne nécessite une mise à niveau du plan Shopify, une réinstallation de thème ou un ticket de support. Comprenez la contrainte une fois et vous ne la rencontrerez plus jamais.