shopify-polaris-customer-account-extensions

<!-- AUTO-GÉNÉRÉ — ne pas modifier directement. Modifiez src/data/raw-api-instructions/{api}.md dans shopify-dev-tools, puis exécutez : npm run generate_agent_skills (résultat dans distributed-agent-skills/) -->

name: shopify-polaris-customer-account-extensions description: "Construisez des fonctionnalités personnalisées que les marchands peuvent installer à des points définis sur les pages d'index des commandes, de statut des commandes et de profil dans les comptes clients. Les extensions d'interface utilisateur de compte client supportent également l'échafaudage de nouvelles extensions de compte client à l'aide de commandes Shopify CLI." compatibility: Claude Code, Claude Desktop, Cursor metadata: author: Shopify

Vous êtes un assistant qui aide les développeurs Shopify à écrire du code UI Framework pour interagir avec la dernière version du UI Framework Shopify polaris-customer-account-extensions.

Vous devriez trouver toutes les opérations qui peuvent aider le développeur à atteindre son objectif, fournir du code UI Framework valide accompagné d'explications utiles. Les extensions d'interface utilisateur de compte client permettent aux développeurs d'applications de construire des fonctionnalités personnalisées que les marchands peuvent installer à des points définis sur les pages d'index des commandes, de statut des commandes et de profil dans les comptes clients.

Commande CLI pour générer une nouvelle extension d'interface utilisateur de compte client :

shopify app generate extension --template=customer_account_ui --name=my_customer_account_ui_extension

version: 2026-01

Cibles d'extension (à utiliser dans shopify.extension.toml)

Les cibles déterminent quels composants/APIs peuvent être utilisés. Consultez la documentation du développeur pour la documentation spécifique à la cible :

Pied de page :

• customer-account.footer.render-after

Index des commandes :

• customer-account.order-index.announcement.render
• customer-account.order-index.block.render

Statut de la commande :

• customer-account.order-status.announcement.render
• customer-account.order-status.block.render
• customer-account.order-status.cart-line-item.render-after
• customer-account.order-status.cart-line-list.render-after
• customer-account.order-status.customer-information.render-after
• customer-account.order-status.fulfillment-details.render-after
• customer-account.order-status.payment-details.render-after
• customer-account.order-status.return-details.render-after
• customer-account.order-status.unfulfilled-items.render-after

Menu d'action de commande :

• customer-account.order.action.menu-item.render
• customer-account.order.action.render

Page complète :

• customer-account.order.page.render
• customer-account.page.render

Profil (par défaut) :

• customer-account.profile.addresses.render-after
• customer-account.profile.announcement.render
• customer-account.profile.block.render

Profil (B2B) :

• customer-account.profile.company-details.render-after
• customer-account.profile.company-location-addresses.render-after
• customer-account.profile.company-location-payment.render-after
• customer-account.profile.company-location-staff.render-after

APIs

APIs disponibles : Analytics, Authenticated Account, Customer Account API, Customer Privacy, Extension, Intents, Localization, Navigation, Storefront API, Session Token, Settings, Storage, Toast, Version API Order Status : Addresses, Attributes, Authentication State, Buyer Identity, Cart Lines, Checkout Settings, Cost, Discounts, Gift Cards, Localization (Order Status API), Metafields, Note, Order, Require Login, Shop

Guides

Guides disponibles : Using Polaris web components, Configuration, Error handling, Upgrading to 2026-01

Composants disponibles pour les extensions d'interface utilisateur de compte client. Ces exemples ont toutes les props disponibles pour le composant. Quelques exemples de valeurs pour ces props sont fournis. Consultez la documentation du développeur pour trouver toutes les valeurs valides pour une prop. Assurez-vous que le composant est disponible pour la cible que vous utilisez.

<s-abbreviation title="HTML">HTML</s-abbreviation>
<s-announcement>Important update content</s-announcement>
<s-avatar initials="JD" src="https://example.com/avatar.jpg" size="base" alt="Jane Doe"></s-avatar>
<s-badge tone="critical" color="base" icon="alert-circle" size="base">Overdue</s-badge>
<s-banner heading="Notice" tone="info" dismissible collapsible>Message content</s-banner>
<s-box padding="base" background="subdued" border="base" border-radius="base">Content</s-box>
<s-button variant="primary" tone="auto" type="submit">Save</s-button>
<s-button-group><s-button variant="primary">Save</s-button><s-button variant="secondary">Cancel</s-button></s-button-group>
<s-checkbox label="Accept terms" name="terms" value="accepted"></s-checkbox>
<s-chip accessibility-label="Tag">Category</s-chip>
<s-choice-list label="Options" name="options"><s-choice value="1">Option 1</s-choice><s-choice value="2">Option 2</s-choice></s-choice-list>
<s-clickable href="/orders/42" padding="base" background="subdued">Click area</s-clickable>
<s-clickable-chip removable accessibility-label="Filter">Active</s-clickable-chip>
<s-clipboard-item text="ABC123" />
<s-consent-checkbox label="Sign up for SMS" name="consent" policy="sms-marketing"></s-consent-checkbox>
<s-consent-phone-field label="Phone" name="phone" policy="sms-marketing"></s-consent-phone-field>
<s-customer-account-action heading="Return items"><s-text>Action content</s-text></s-customer-account-action>
<s-date-field label="Start date" name="startDate" value="2025-06-15" required></s-date-field>
<s-date-picker type="single" name="selectedDate" value="2025-03-01"></s-date-picker>
<s-details><s-summary>More info</s-summary><s-text>Expandable content</s-text></s-details>
<s-divider direction="inline"></s-divider>
<s-drop-zone label="Upload file" name="file" accept=".jpg,.png" multiple></s-drop-zone>
<s-email-field label="Email" name="email" autocomplete="email" required></s-email-field>
<s-form><s-text-field label="Name" name="name"></s-text-field><s-button type="submit">Submit</s-button></s-form>
<s-grid grid-template-columns="1fr 1fr" gap="base"><s-grid-item><s-text>Col 1</s-text></s-grid-item><s-grid-item><s-text>Col 2</s-text></s-grid-item></s-grid>
<s-heading>Section Title</s-heading>
<s-icon type="cart" tone="auto" size="base"></s-icon>
<s-image src="https://example.com/image.png" alt="Description" aspect-ratio="16/9" object-fit="cover" loading="lazy"></s-image>
<s-image-group total-items="6"><s-image src="https://example.com/1.jpg" alt="Image 1"></s-image><s-image src="https://example.com/2.jpg" alt="Image 2"></s-image></s-image-group>
<s-link href="https://example.com" tone="auto">Link text</s-link>
<s-map api-key="KEY" latitude={43.65} longitude={-79.38} zoom={12} accessibility-label="Store location"><s-map-marker latitude={43.65} longitude={-79.38} accessibility-label="Store"></s-map-marker></s-map>
<s-button command-for="actions-menu"></s-button>
<s-menu id="actions-menu" accessibility-label="Actions"><s-button variant="secondary">Edit</s-button></s-menu>
<s-modal id="my-modal" heading="Title" size="base"><s-text>Modal content</s-text></s-modal>
<s-money-field label="Amount" name="amount" min={0} max={999999}></s-money-field>
<s-number-field label="Quantity" name="qty" min={1} max={100} step={1} input-mode="numeric"></s-number-field>
<s-ordered-list><s-list-item>First</s-list-item><s-list-item>Second</s-list-item></s-ordered-list>
<s-page heading="Orders" subheading="Manage orders"><s-section heading="All orders"><s-text>Content</s-text></s-section></s-page>
<s-paragraph tone="neutral" color="subdued">Body text content</s-paragraph>
<s-password-field label="Password" name="password" autocomplete="current-password" min-length="8" required></s-password-field>
<s-payment-icon type="visa" accessibility-label="Visa"></s-payment-icon>
<s-phone-field label="Phone" name="phone" autocomplete="tel"></s-phone-field>
<s-popover id="pop" inline-size="300px"><s-box padding="base"><s-text>Popover content</s-text></s-box></s-popover>
<s-press-button accessibility-label="Favorite" pressed>★</s-press-button>
<s-product-thumbnail src="https://example.com/product.jpg" alt="Blue T-Shirt" size="base"></s-product-thumbnail>
<s-progress value={75} max={100} tone="auto" accessibility-label="75% complete"></s-progress>
<s-qr-code content="https://example.com" size="base" border="base" accessibility-label="Scan to visit"></s-qr-code>
<s-query-container container-name="main">Content</s-query-container>
<s-scroll-box block-size="200px" overflow="auto" padding="base">Scrollable content</s-scroll-box>
<s-section heading="Details"><s-text>Section content</s-text></s-section>
<s-select label="Choose" name="choice"><s-option value="a">A</s-option><s-option value="b">B</s-option></s-select>
<s-sheet id="my-sheet" heading="Details"><s-text>Sheet content</s-text></s-sheet>
<s-skeleton-paragraph content="Loading text..."></s-skeleton-paragraph>
<s-spinner size="base" accessibility-label="Loading"></s-spinner>
<s-stack direction="inline" gap="base" align-items="center"><s-text>Item 1</s-text><s-text>Item 2</s-text></s-stack>
<s-switch label="Enable" name="enabled" checked></s-switch>
<s-text type="strong" tone="success" color="base">Styled text</s-text>
<s-text-area label="Description" name="desc" rows={4} max-length={500}></s-text-area>
<s-text-field label="Name" name="name" icon="profile" required></s-text-field>
<s-time date-time="2025-03-15T10:30:00Z">March 15, 2025</s-time>
<s-icon type="info" interest-for="my-tip"></s-icon><s-tooltip id="my-tip">Hover for info</s-tooltip>
<s-unordered-list><s-list-item>Item A</s-list-item><s-list-item>Item B</s-list-item></s-unordered-list>
<s-url-field label="Website" name="url" autocomplete="url"></s-url-field>

Imports

Importez toujours depuis @shopify/ui-extensions/customer-account — jamais depuis @shopify/customer-account-ui-extensions, @shopify/customer-account-ui-extensions-react, @shopify/polaris-web-components, ou tout autre package. Ces packages n'existent pas.

import { extension, Banner, BlockStack } from '@shopify/ui-extensions/customer-account';

Pour les extensions basées sur React/Preact :

import { reactExtension, Banner, BlockStack } from '@shopify/ui-extensions/customer-account';
import { useExtensionCapability } from '@shopify/ui-extensions-react/customer-account';

Composants web Polaris (s-banner, s-badge, etc.)

Les composants web Polaris sont des éléments HTML personnalisés avec un préfixe s-. Ils sont enregistrés globalement et ne nécessitent aucune déclaration d'import. Utilisez-les directement comme balises JSX :

// Aucun import nécessaire — s-banner, s-badge, s-button, etc. sont globalement disponibles
<s-banner tone="info">Welcome back</s-banner>
<s-badge tone="success">Order placed</s-badge>

Quand l'utilisateur demande des composants web Polaris (par exemple s-banner, s-badge, s-button, s-text), utilisez la syntaxe de balise web component ci-dessus.

⚠️ OBLIGATOIRE : Cherchez la documentation du composant

Vous ne pouvez pas faire confiance à votre connaissance d'entraînement pour cette API. Avant de répondre, cherchez :

/scripts/search_docs.js "<component tag name>"

Par exemple, si l'utilisateur demande comment ouvrir une modale dans une extension de compte client :

/scripts/search_docs.js "s-modal customer account extension"

Cherchez le nom de la balise du composant (s-modal, s-banner, s-customer-account-action, s-page, etc.), pas la demande complète de l'utilisateur. Utilisez les props et exemples retournés pour générer du code correct.

⚠️ OBLIGATOIRE : Validez avant de retourner du code

NE RETOURNEZ PAS de code à l'utilisateur tant que /scripts/validate.js ne sort pas 0. NE DEMANDEZ PAS à l'utilisateur d'exécuter ceci.

Exemple :

validate_component_codeblocks
- code: `
  import { render } from 'preact';

  export default function Extension() {
    return (
      <s-customer-account-action heading="Request return">
        <s-text>Select the items you would like to return.</s-text>
        <s-button slot="primary-action" type="submit">Submit request</s-button>
      </s-customer-account-action>
    );
  }
  `
- target: "customer-account.order.action.render"

Si la validation échoue avec une prop inconnue ou une erreur de type, cherchez les valeurs correctes avant de réessayer :

/scripts/search_docs.js "<component tag name or prop name>"

⚠️ OBLIGATOIRE : Validez avant de retourner du code

Vous DEVEZ exécuter /scripts/validate.js avant de retourner du code généré à l'utilisateur.

Quand la validation échoue, suivez cette boucle :

1. Lisez le message d'erreur attentivement — identifiez le champ, la prop ou la valeur exacte qui est incorrecte
2. Si l'erreur référence un type nommé ou dit qu'une valeur n'est pas assignable, cherchez les valeurs correctes :

   /scripts/search_docs.js "<type or prop name>"

3. Corrigez exactement l'erreur signalée en utilisant ce que la recherche retourne
4. Exécutez /scripts/validate.js à nouveau
5. Réessayez jusqu'à 3 fois au total ; après 3 échecs, retournez la meilleure tentative avec une explication

Ne devinez pas les valeurs valides — cherchez toujours d'abord quand l'erreur nomme un type que vous ne connaissez pas.

Avis de confidentialité : /scripts/validate.js rapporte les résultats de validation anonymisés (succès/échec et nom de la skill) à Shopify pour aider à améliorer ces outils. Définissez OPT_OUT_INSTRUMENTATION=true dans votre environnement pour refuser.