Apparence

Un seul objet appearance stylise tout : le checkout hébergé, la superposition et chaque composant de champ de paiement. Il comprend trois couches appliquées dans cet ordre.

1. Un préréglage theme, si vous en indiquez un.
2. Les clés de premier niveau, comme primaryColor.
3. variables et rules, pour un contrôle par jeton et par sélecteur.

Chaque couche remplace la précédente. Un préréglage constitue donc un point de départ, pas une contrainte. Depuis Wajub.js 1.8.0, inherit peut placer le style de votre propre page sous les trois : voir Reprendre le style de votre page.

await mount('#checkout', {
  sessionId,
  appearance: {
    theme: 'stripe',
    primaryColor: '#6366f1',
    colorScheme: 'auto',
    labels: 'floating',
    variables: { colorText: '#0f172a', fontSizeBase: '16px' },
    rules: { '.Input': { borderRadius: '8px' } },
  },
});

Préréglages

theme place un ensemble de clés de premier niveau sous les vôtres. Voici leurs valeurs exactes.

stripe correspond à l'apparence par défaut d'un checkout Wajub. L'indiquer ne change donc rien, sauf si vous remplacez également certaines de ses valeurs.

light, dark, system et auto ne sont pas des préréglages. Depuis Wajub.js 1.7.1, theme réglé sur l'une de ces valeurs est lu comme colorScheme, system valant auto, lorsque vous ne donnez pas de colorScheme. Les versions antérieures l'ignoraient.

Clés de premier niveau

Cette couche fournit les raccourcis. Chaque valeur est une simple chaîne CSS.

Variables

Cette couche concerne les jetons. Chaque clé définit un jeton de design. Elle atteint ainsi chaque composant qui utilise ce jeton, pas une seule surface.

Seules ces seize clés sont acceptées. Toute autre clé est ignorée lors de l'envoi.

appearance: {
  variables: {
    fontFamily: 'Inter, system-ui, sans-serif',
    fontSizeBase: '15px',
    fontWeightMedium: '600',
    spacingUnit: '4px',
  },
}

Si une clé de premier niveau et le jeton correspondant sont tous deux définis, la première l'emporte. Choisissez une méthode et conservez-la.

Depuis le checkout livré avec Wajub.js 1.7.1, quelle que soit la version chargée par votre page, fontFamily, fontSizeBase, colorText, colorTextSecondary, colorTextPlaceholder et borderRadius atteignent les champs eux-mêmes. inputBackgroundColor et inputBorderColor ne stylisent que les champs, alors qu'ils modifiaient tous les arrière-plans et toutes les bordures, et un colorScheme que vous donnez l'emporte sur l'appareil du payeur, dans un champ de paiement comme dans le checkout intégré.

Depuis le checkout livré avec Wajub.js 1.7.2, quelle que soit la version chargée par votre page :

• Le colorScheme que vous donnez s'applique dès le premier affichage sur chaque page, le checkout intégré et la page vers laquelle checkout() envoie le payeur compris, comme dans un champ de paiement. Quand vous en donnez un, auto compris, le checkout masque son bouton clair et sombre, que votre schéma annulait aussitôt.
• La page vers laquelle checkout() envoie le payeur prend votre apparence dès son premier rendu. Elle l'effaçait, et ne la retrouvait qu'à un rendu suivant.
• Une fontFamily que le checkout charge atteint aussi les champs de carte Stripe, qui revenaient à la police du système.
• Sans fontSizeBase, les champs font 16px sur téléphone ou tablette, champs de carte Stripe compris. Ils faisaient 15px, 13px pour un coupon, et iOS zoomait au focus.

Règles

Cette couche de sélecteurs est la plus limitée. Elle sert à modifier les champs du formulaire, pas à refaire le style du checkout.

Sélecteurs. Uniquement .Input et .Label, avec au maximum un seul parmi :hover, :focus, :focus-within, :disabled, ::placeholder, ::selection. .Input désigne la boîte d'un champ, sa bordure, son arrière-plan et ses angles, qui prend le focus avec son champ de saisie et se désactive avec lui. .Label désigne le libellé d'un champ. Depuis le checkout livré avec Wajub.js 1.7.2, quelle que soit la version chargée par votre page, la color et la police d'une règle .Input atteignent le texte saisi dans le champ, dans les champs de carte que le checkout dessine lui-même aussi, et la color d'une règle .Label atteint aussi le libellé du titulaire de la carte avec Adyen.

appearance: {
  rules: {
    '.Input': { borderRadius: '8px', borderColor: '#cbd5e1', padding: '12px' },
    '.Input:focus': { borderColor: '#6366f1', outline: '2px solid #c7d2fe' },
    '.Input::placeholder': { color: '#94a3b8' },
    '.Label': { fontWeight: '500', fontSize: '14px', letterSpacing: '0.01em' },
  },
}

Propriétés. Trente et une propriétés, en camelCase.

Valeurs. Uniquement des chaînes non vides. Une valeur qui pourrait charger une ressource (url(, image-set(, @import), exécuter un script (expression(, javascript:) ou sortir de sa déclaration (;, {, }, <, >, \) est refusée. Les images d'arrière-plan et les importations de polices sont donc exclues. Depuis le checkout livré avec Wajub.js 1.7.1, le checkout refuse lui-même ces valeurs, ainsi que celles de plus de 256 caractères, par tous les chemins : clés de premier niveau, variables et rules, au montage comme avec update({ appearance }), quelle que soit la version chargée par votre page. Depuis Wajub.js 1.7.2, le SDK écarte les mêmes valeurs de rules avant qu'elles quittent votre page.

Reprendre le style de votre page

Depuis Wajub.js 1.8.0, appearance.inherit donne à un champ de paiement ou à un checkout intégré le style de votre propre formulaire. Au montage, le SDK lit les styles de votre page tels que le payeur les voit (les styles calculés), en tire des clés d'apparence et les place sous celles que vous donnez.

factory.create('card', { appearance: { inherit: true, labels: 'floating' } }).mount('#card-fields');

factory.create('mobileMoney', {
  appearance: {
    inherit: {
      input: '#billing_email',
      label: 'label[for=billing_email]',
      button: '#place-order',
      background: '.checkout-box',
    },
  },
});

inherit: true cherche quatre éléments près du conteneur. Un InheritSource en désigne n'importe lequel, par un sélecteur CSS ou par l'élément lui-même, et le SDK cherche ceux que vous ne donnez pas.

Ce qui est lu, et ce qui est gardé :

• Vos clés l'emportent. Toute clé que vous donnez, et toute clé que fixe votre préréglage theme, l'emporte sur ce qui est lu. variables est fusionné clé par clé, et une variable lue sur la page est écartée quand vous donnez sa clé de premier niveau équivalente : primaryColor pour colorPrimary, fontFamily, borderRadius, backgroundColor pour colorBackground, textMutedColor pour colorTextSecondary.
• Le schéma suit le fond, clair ou sombre. Votre colorScheme, theme: 'dark' ou un préréglage sombre comme night décide à sa place : forcé en sombre sur une page claire, seuls la police, la taille et l'arrondi de la page sont repris. Avec colorScheme: 'auto', les couleurs de la page sont reprises quand l'appareil du payeur est, au montage, dans le schéma de la page.
• Lisible, ou laissé de côté. Les couleurs du champ ne sont reprises que si son texte se lit sur le fond (4,5:1), et celle du bouton que si un anneau de focus dessiné avec elle se voit (3:1).
• Une image ou un dégradé derrière le conteneur : le schéma suit la couleur du texte écrit dessus, et le fond reste celui du checkout.
• Bien formé, ou laissé de côté. Des couleurs en rgb() ou rgba() (le navigateur convertit oklch(), lab() ou color(), d'un thème Tailwind v4 par exemple), des tailles en px, une taille de police de 10 à 32px, une pile de polices sans caractère dangereux, coupée après sa dernière famille entière à 256 caractères. Une valeur illisible est laissée de côté, et une page illisible donne vos clés seules. inherit ne lève jamais d'erreur.
• Lu au montage, puis à chaque update({ appearance }). inherit lui-même, et les éléments qu'il désigne, n'atteignent jamais l'iframe : seules les clés qu'il a produites y vont.

Les champs de paiement le lisent au mount(), un checkout intégré avec mount() lit autour de son conteneur, et la superposition de open() lit toute la page. Pour voir ce qui serait lu, ou l'ajuster avant de le transmettre vous-même, appelez wajub.appearanceFrom(container, source?).

const look = wajub.appearanceFrom('#card-fields'); // {} quand il n'y a rien à lire

factory
  .create('card', { appearance: { ...look, variables: { ...look.variables, fontSizeBase: '16px' } } })
  .mount('#card-fields');

appearanceFrom() suit le schéma de la page, renvoie {} quand il n'y a rien à lire et ne lève jamais d'erreur. Le client Wajub() l'a aussi, et @wajub/js l'exporte en fonction asynchrone, qui renvoie null sur le serveur, et {} quand la page charge un Wajub.js antérieur à 1.8.0, un environnement d'exécution en cache ou figé qui n'a rien pour lire la page.

Modifier l'apparence après le montage

Ce que vous transmettez au montage est fixé au chargement du checkout. update() modifie ce que couvre le tableau ci-dessous, et tout le reste demande un nouveau montage. Les deux types d'instances acceptent update().

let checkout;

await mount('#checkout', { sessionId, onReady: (instance) => (checkout = instance) });

darkToggle.onchange = (event) =>
  checkout.update({ appearance: { colorScheme: event.target.checked ? 'dark' : 'light' } });

Jusqu'au checkout livré avec Wajub.js 1.7.2, quelle que soit la version chargée par votre page, update({ appearance }) sur un checkout intégré, avec mount() ou open(), ne tenait que jusqu'à la saisie ou l'étape suivante du payeur, qui remettait l'apparence donnée au montage. Il tient désormais.

Depuis Wajub.js 1.8.0, update({ appearance }) fusionne ce que vous donnez avec ce que le checkout ou le champ a déjà. Les clés données changent, les autres restent. Une clé donnée à undefined ou null est effacée. appearance: undefined ou null efface toute l'apparence : le checkout ou le champ reprend l'image de marque de votre Dashboard Wajub, et son prochain mount() part sans elle.

card.update({ appearance: { borderRadius: '16px' } }); // les autres clés restent
card.update({ appearance: { primaryColor: undefined } }); // efface cette clé
card.update({ appearance: undefined }); // retour à l'image de marque du Dashboard

Avec inherit, chaque update({ appearance }) relit la page, et effacer inherit efface aussi ce qu'il avait lu. update({ appearance: {} }) ne change aucune clé. Avant la 1.8.0, une clé ne pouvait pas être effacée, et appearance: undefined ne changeait rien.

Sur un checkout intégré, avec mount() ou open(), Wajub.js 1.8.0 fusionne vos propres clés, pas ce que le checkout affiche. Un nouveau preset theme remplace le précédent et tout ce qu'il apportait, comme sur un champ de paiement : update({ appearance: { theme: 'flat' } }) après night ne garde plus les couleurs de night. Une mise à jour qui ne laisse plus aucune clé arrive vide au checkout, et le checkout livré avec la 1.8.0 ramène une apparence vide à l'image de marque de votre Dashboard Wajub. Avant, elle partait à null, que le checkout ignorait, et une apparence vide gardait la précédente.

Avant Wajub.js 1.8.0, update({ layout }) sur le checkout hébergé enregistrait seulement la mise en page : appelez unmount() puis mount() pour recharger le checkout avec elle, ou configurez-la sur la session.

Dans React, Vue et Svelte, les composants de champs surveillent appearance, locale et layout, et frameTitle depuis la 1.8.0. Depuis la 1.8.0 aussi, CheckoutEmbed surveille appearance, theme, locale et layout. Tous appellent eux-mêmes update(), seulement quand le contenu d'une prop change. La prop appearance est envoyée entière : une clé que vous en retirez est effacée, et une appearance devenue undefined ou {} efface toute l'apparence. Avant la 1.8.0, CheckoutEmbed les lisait une seule fois : conservez l'instance reçue par onReady pour la piloter.

Locale

La locale transmise au montage est la langue dans laquelle le checkout ou le champ s'ouvre. Elle l'emporte sur la langue choisie par le payeur lors d'une visite précédente et sur la valeur par défaut de la session. Un code absent de la liste ci-dessous est ignoré. update({ locale }) la modifie ensuite, et le payeur peut toujours changer de langue dans le checkout hébergé.

await mount('#checkout', { sessionId, locale: 'fr' });
checkout.update({ locale: 'en' });

Valeurs prises en charge : fr, en, es, pt, ar. L'arabe s'affiche de droite à gauche. Si vous omettez locale, le checkout s'ouvre dans la dernière langue choisie par le payeur dans ce navigateur, sinon dans la valeur par défaut de la session. Celle-ci provient de l'image de marque de votre compte ou de la préférence enregistrée du client.

Mise en page

Quatre façons de disposer les moyens de paiement.

await mount('#checkout', { sessionId, layout: 'tabs' });

Si vous l'omettez, la valeur par défaut de la session s'applique. Elle diffère du design de page choisi dans Settings → Branding, qui définit le design de la page hébergée elle-même.

Image de marque serveur ou apparence client

Ces deux options ne s'excluent pas. L'image de marque définit l'apparence par défaut de tous vos checkouts. appearance définit l'apparence actuelle de cette intégration précise.

L'apparence client se superpose à l'image de marque définie dans le Dashboard. Seules les valeurs que vous indiquez sont remplacées. Ce que vous pouvez définir dans le Dashboard figure dans Image de marque et thème.