Informazioni sui moduli headless: concetti e domande frequenti understanding-headless-forms
Questa guida risponde alle domande comuni sui moduli headless in generale e su come vengono applicati ad AEM Headless Adaptive Forms. Puoi utilizzarlo per decidere quando utilizzare un approccio headless e come implementare, assegnare stili e integrare i moduli nel tuo stack.
Nozioni di base e comprensione basics-understanding
Cos’è esattamente una libreria di moduli headless?
Una libreria di moduli headless è una soluzione di moduli che separa logica del modulo (stato, convalida, regole, invio) da presentazione (componenti e stile dell'interfaccia utente). L’intestazione è l’interfaccia utente del modulo visibile; "headless" significa che la libreria non detta o invia un’interfaccia utente fissa. Invece, espone:
- Un modello modulo (spesso JSON): struttura, campi, vincoli e regole.
- API o hook per leggere e aggiornare lo stato del modulo, eseguire la convalida e gestire l'invio.
- Eventi e ciclo di vita per consentire all'interfaccia utente di reagire alle modifiche.
In AEM Headless Adaptive Forms, il modulo è una struttura JSON ospitata su Adobe Experience Manager. Forms Web SDK (client-side runtime) fornisce il livello di logica, ovvero processore delle regole business, gestione dello stato e convalida, mentre l'app fornisce l'interfaccia utente che esegue il rendering di tale struttura.
Quali sono le differenze tra un modulo headless e una libreria di moduli tradizionale?
Con AEM Headless Adaptive Forms, crei e pubblichi un modulo una volta in AEM; qualsiasi client (React, Angular, mobile nativo, chatbot) può recuperare il modulo JSON ed eseguirne il rendering con l'interfaccia utente appropriata per quel canale.
Perché dovrei usare moduli headless invece di una soluzione di moduli basata su interfaccia utente?
Le forme headless sono ideali per:
- Coerenza del sistema di progettazione: utilizza i componenti e il marchio esistenti senza disattivare i valori predefiniti della libreria.
- Multicanale - Una definizione di modulo per web, dispositivi mobili e altri punti di contatto (vedi Panoramica).
- Moduli guidati da CMS o back-end - Gli autori modificano la struttura del modulo e le regole senza distribuzioni di codice; l'app utilizza solo il JSON.
- Flessibilità framework - La libreria AF-core è indipendente dal framework; le associazioni React sono fornite per comodità, ma puoi creare associazioni per altri framework.
- Funzionalità di back-end - Sfrutta AEM Forms per precompilare, convalidare, inviare, flussi di lavoro e Forms Data Model senza bloccarsi in uno stack di interfaccia utente specifico.
Quando ha senso utilizzare un approccio headless?
Utilizza i moduli headless quando:
- È disponibile o si desidera un sistema di progettazione o una libreria di componenti avanzata.
- Forms è creato da non sviluppatori (ad esempio, in un CMS) e deve funzionare su più app o canali.
- È necessaria la stessa logica del modulo (convalida, regole) tra client web, mobili o altri.
- Desideri ridurre al minimo i rendering e mantenere la logica del modulo testabile indipendentemente dall’interfaccia utente.
Considera una libreria di moduli tradizionale inclusa nell’interfaccia utente quando:
- Hai bisogno di un modulo di lavoro in una singola app web rapidamente e non ti importa dell’interfaccia utente personalizzata o del multicanale.
- Il tuo team preferisce definire i moduli solo nel codice in un unico framework.
"headless" è solo una parola d'ordine o risolve problemi reali?
Risolve i veri problemi architettonici:
- Separazione dei problemi - La struttura del modulo, le regole e la convalida sono attive nei dati e in un livello logico; il livello dell'interfaccia utente esegue il rendering e invia solo le azioni utente. Ciò migliora la testabilità e il riutilizzo.
- Indipendenza canale - Una definizione di modulo può gestire diverse interfacce utente (ad esempio, React Web, React Native, Angular o voice). AEM Headless Adaptive Forms è stato creato per questo: generare una volta, distribuirlo tra React, SPA, web, dispositivi mobili e altro ancora.
- Authoring senza codice - Gli utenti aziendali possono modificare campi e regole nell'Editor moduli adattivi; gli sviluppatori non devono ridistribuire le modifiche al contenuto.
- Integrazione con gli stack esistenti - Mantiene il sistema di progettazione, la gestione dello stato e il routing; il livello headless gestisce solo lo stato del modulo, la convalida e l'invio.
Attuazione e questioni tecniche implementation-technical
In che modo i moduli headless gestiscono lo stato?
In AEM Headless Adaptive Forms, lo stato è gestito da Forms Web SDK:
- Processore regole business: accetta il formato JSON, gestisce lo stato del campo ed esegue le regole e i gestori eventi definiti nel JSON.
- Binder React - Fornisce hook (ad esempio,
useRuleEngine) sul controller in modo che i componenti React ricevano lo stato corrente e i gestori; lo stesso stato può essere utilizzato dalle interfacce utente non React tramite le API di base. - Stato include i valori dei campi, la visibilità, la validità ed eventuali proprietà personalizzate definite nel modello di modulo.
I componenti dell'interfaccia utente ricevono lo stato e i gestori (ad esempio, [state, handlers] = useRuleEngine(props)). Il rendering viene eseguito da state e si chiama handlers quando l'utente interagisce. Il runtime mantiene lo stato sincronizzato con la definizione e le regole del modulo. Consulta Architettura e Utilizzare componenti personalizzati per eseguire il rendering di un modulo headless.
Come funziona la convalida in una configurazione di moduli headless?
La convalida fa parte del livello logica del modulo:
- I vincoli sono definiti nel formato JSON (ad esempio obbligatorio, min/max, pattern). Forms Web SDK applica questi vincoli ed espone lo stato di convalida (ad esempio, messaggi di errore validi/non validi) ai componenti.
- Convalida lato client applicata da SDK in base alla struttura del modulo. Nell'interfaccia utente vengono visualizzati errori dallo stato.
- La convalida lato server è disponibile tramite le API AEM (ad esempio, l'endpoint di convalida); è possibile eseguire la convalida prima o durante l'invio.
Non si implementa la logica di convalida nell’interfaccia utente, ma si visualizzano solo lo stato di convalida e i messaggi forniti dal runtime.
Posso integrare i moduli headless con la convalida dello schema (Yup, Zod, Joi)?
La convalida incorporata è guidata dai vincoli JSON del modulo. Per usare Yup, Zod, Joi o simili:
- Puoi derivare o generare il JSON del modulo adattivo headless dallo schema (ad esempio, convertire lo schema JSON in JSON) in modo che un'unica origine di verità determini sia la convalida dello schema che la struttura del modulo.
- Per la convalida personalizzata oltre al modulo JSON, puoi eseguire le tue convalide (Yup/Zod/Joi) nei gestori eventi o prima dell'invio e inviare i risultati allo stato del modulo o al blocco dell'invio. I punti di integrazione sono gli stessi hook/API utilizzati per lo stato e l’invio.
La specifica Forms adattiva e la formula JSON definiscono il modello di regole e vincoli utilizzato dal runtime.
Come posso gestire la convalida asincrona (ad esempio, disponibilità del nome utente)?
La convalida asincrona può essere implementata nel livello dell’applicazione:
- Utilizza regole o gestori eventi nel modulo JSON (se supportato) per attivare la logica quando un campo cambia.
- Nei componenti personalizzati, utilizza gli stessi hook stato/gestore per chiamare il backend (ad esempio, API disponibilità nome utente), quindi aggiorna la validità del campo o visualizza un errore tramite le API di runtime o lo stato locale visualizzato nell'interfaccia utente.
- In alternativa, eseguire il controllo in caso di sfocatura o prima dell'invio e impostare lo stato del campo su non valido con un messaggio personalizzato se il controllo asincrono non riesce.
Il modello esatto dipende dal modo in cui l'app si integra con il processore per regole business e i componenti personalizzati.
Come posso inviare dati alle API utilizzando moduli headless?
L’invio è separato dall’interfaccia utente:
- Azioni di invio AEM - Configura il modulo in AEM per l'invio a endpoint REST, e-mail o integrazioni (ad esempio, Microsoft Dynamics, Salesforce). Il modulo viene inviato tramite AEM, che gestisce la chiamata HTTP/backend effettiva. Vedi Utilizzare gli eventi per gestire e inviare i dati del modulo.
- Invio lato client - L'app può ascoltare o raccogliere i dati del modulo dallo stato di runtime e inviarli alle proprie API. Le API HTTP elencano, recuperano, convalidano, inviano e tengono traccia dello stato di invio.
- Precompilazione - I dati possono essere precompilati tramite endpoint REST o lato server in modo che, al caricamento del modulo, lo stato sia già popolato. Vedi Storybook - esempio di precompilazione.
Interfaccia utente e controllo della progettazione ui-design-control
Posso utilizzare un sistema di progettazione o una libreria di componenti personalizzati con moduli headless?
Sì. Questo è un vantaggio fondamentale dei moduli headless. Con AEM Headless Adaptive Forms:
- mappi i tuoi componenti al modello del modulo (per tipo di campo o di risorsa). Consulta Utilizzare componenti personalizzati per eseguire il rendering di un modulo headless e Utilizzare i componenti React dell'interfaccia utente di Google Material per eseguire il rendering di un modulo headless.
- Il runtime fornisce lo stato e i gestori; i componenti eseguono il rendering utilizzando il sistema di progettazione e chiamano i gestori in modo che la logica del modulo rimanga sincronizzata.
- Puoi utilizzare React Spectrum, Material UI, Chakra UI o qualsiasi libreria di componenti personalizzata; la specifica può essere estesa per i componenti personalizzati (ad esempio, Chakra UI, Vue.js). Vedi Domande frequenti - framework personalizzati.
I moduli headless supportano l’accessibilità (ARIA, gestione della tastiera)?
L'accessibilità è implementata nel livello interfaccia utente fornito. Il livello headless non esegue il rendering del DOM, pertanto non aggiunge ARIA o il comportamento della tastiera di per sé. Per ottenere l’accessibilità, segui questi passaggi:
- Utilizzo di componenti accessibili dal sistema di progettazione o dalla libreria (molti includono il supporto per ARIA e tastiera).
- Segui le best practice per l'accessibilità nei componenti dei campi personalizzati (etichette, messaggi di errore, gestione dello stato attivo, navigazione da tastiera).
- Assicurati che la struttura e lo stato del modulo ricevuti (ad esempio obbligatorio, non valido, visibile) si riflettano negli attributi e nel comportamento ARIA dei componenti.
Se utilizzi i componenti predefiniti basati su React Spectrum, puoi sfruttare la loro accessibilità incorporata.
Come posso gestire componenti dell’interfaccia utente complessi (selettori di date, elenchi a discesa personalizzati)?
Considerali come componenti personalizzati mappati ai tipi di campo corrispondenti o ai tipi di risorse personalizzate in formato JSON:
- Implementa il componente per accettare gli stessi prop/stato/gestori degli altri componenti del campo (ad esempio tramite
useRuleEngine). - Utilizza state per valore, visibilità e validità; utilizza handler per aggiornare il valore e attivare la convalida.
- Esegui il rendering del selettore di date o del menu a discesa personalizzato con la libreria dell’interfaccia utente scelta. Al momento della modifica, chiama il gestore con il nuovo valore in modo che lo stato del modulo rimanga corretto.
Vedi Utilizzare componenti personalizzati per eseguire il rendering di un modulo headless per la mappatura per tipo di campo e tipo di risorsa.
È possibile aggiungere o rimuovere campi (moduli dinamici) in modo dinamico?
La struttura del modulo è definita dal modulo JSON restituito dal server. Il comportamento dinamico si ottiene:
- Regole nel formato JSON: mostrare/nascondere, abilitare/disabilitare o impostare valori in base alle espressioni. Il processore regola business esegue queste regole. I componenti reagiscono a
state.visiblee simili. - Struttura basata su server - Utenti o contesti diversi possono ricevere JSON in moduli diversi (ad esempio passaggi o sezioni diverse), pertanto "dinamico" può significare "definizione di modulo diversa per richiesta".
- Modifiche lato client - Se l'app può modificare il modello del modulo (ad esempio, aggiungere/rimuovere elementi in una struttura ripetibile), il runtime può rifletterlo; la funzionalità esatta dipende dallo schema del modulo e dalle API di runtime.
Il Storybook include esempi di comportamento dinamico.
Come posso gestire i campi condizionali (mostrare/nascondere in base all’input)?
La visibilità condizionale è guidata da regole nel formato JSON, valutata dal processore delle regole business. È possibile definire le condizioni (ad esempio, "quando il campo A è uguale a X, mostra il campo B"); lo stato di aggiornamento del runtime (ad esempio, state.visible). I componenti devono solo rispettare lo stato (ad esempio, if (!state.visible) return null;). Non è richiesta alcuna logica aggiuntiva dell’interfaccia utente per mostrare/nascondere elementi oltre il rendering dallo stato. Il comportamento a cascata e condizionale è documentato nella specifica di Forms adattivo ed è dimostrato in Storybook - campi a cascata. Vedi anche Domande frequenti - campi a catena.
Prestazioni e scalabilità performance-scalability
I moduli headless sono più performanti delle librerie di moduli tradizionali?
Possono essere, ma dipende dall’implementazione:
- Aggiornamenti mirati - Un runtime headless ben progettato aggiorna solo lo stato che è stato modificato e notifica solo i componenti che dipendono da esso, riducendo così i rirendering non necessari rispetto a un componente modulo monolitico.
- Bundle interfaccia utente più piccolo - Spedisci solo i componenti dell'interfaccia utente utilizzati (sistema di progettazione), non un set completo di componenti libreria.
- Caricamento differito - Il JSON del modulo può essere recuperato quando necessario; il bundle iniziale può rimanere più piccolo.
Le prestazioni dipendono anche dal modo in cui vengono implementati i componenti (ad esempio, evitando rendering non necessari, memorie).
In che modo riducono al minimo i rendering?
- Forma stato - Il runtime mantiene lo stato del modulo in una struttura che consente aggiornamenti dettagliati, in modo che solo le parti interessate della struttura debbano essere rieseguite.
- Progettazione hook - È possibile implementare hook come
useRuleEngineper sottoscrivere i componenti solo allo stato in uso, pertanto le modifiche a livello di padre o di pari livello non forzano il rendering di ogni campo. - Responsabilità - Puoi ridurre ulteriormente i rendering utilizzando le best practice React (ad esempio,
React.memo, callback stabili) nei componenti personalizzati.
I moduli headless hanno una buona scalabilità per i moduli di grandi dimensioni e con più passaggi?
Sì, se progettato in modo appropriato:
- Definizione modulo - I moduli di grandi dimensioni possono essere suddivisi in passaggi o sezioni nel JSON; solo il passaggio o la sezione visibile potrebbe dover essere completamente attivo nell'interfaccia utente, con valutazione lenta delle regole per le sezioni nascoste, se supportata.
- Stato - Il runtime contiene uno stato di modulo coerente. La navigazione dei passaggi mostra o nasconde sezioni o aggiorna il "passaggio corrente" senza duplicare i dati.
- Chunking e caricamento lento - Puoi recuperare il JSON del modulo in blocchi o caricare sezioni aggiuntive al passaggio di avanzamento per mantenere basso il payload iniziale e il costo di analisi.
Per i moduli di grandi dimensioni, considera la struttura (ad esempio, i passaggi della procedura guidata), le varianti di moduli guidate dal server e la misurazione dell’esecuzione di rendering e regole con payload reali.
Integrazione ed ecosistema integration-ecosystem
I moduli headless possono funzionare con le azioni Next.js/SSR/Server?
- Next.js / React - Sì. Il renderer React e gli hook funzionano in un ambiente React. Utilizza Forms Web SDK nei componenti client; recupera il JSON modulo sul server o sul client in base alle esigenze.
- SSR - È possibile recuperare il modulo JSON sul server e passarlo al client in modo che il modulo si idrati con i dati. L’interattività del modulo (stato, convalida, regole) viene eseguita sul client in cui viene caricato SDK. Evita il rendering dei campi modulo che dipendono dallo stato solo del client durante SSR, oppure utilizza un segnaposto che idrata sul client.
- Azioni server (Next.js) - È possibile chiamare Azioni server dal gestore di invio: quando l'utente invia, il codice client raccoglie i dati del modulo (dallo stato headless) e chiama un'azione server invece o in aggiunta agli endpoint di invio di AEM.
In che modo i moduli headless si integrano con CMS, e-commerce headless o sistemi back-end?
- CMS - AEM è il CMS per la definizione del modulo: gli autori creano e pubblicano il modulo JSON. Altri CMS possono fare riferimento o collegarsi al modulo URL/API. L’app recupera il modulo da AEM (o da una rete CDN) e, facoltativamente, estrae una copia o un layout da un altro CMS.
- Precompila e invia - Precompila e invia possono raggiungere gli endpoint REST, quindi puoi precompilare da un back-end CRM, DAM o commerce e inviare allo stesso sistema o a sistemi diversi. AEM Forms supporta anche Microsoft Dynamics e Salesforce, REST, e-mail e azioni di invio personalizzate.
- Forms Data Model - AEM Forms fornisce un Forms Data Model per connettersi a diverse origini dati; i moduli headless possono utilizzare queste funzionalità per la precompilazione, la convalida e l'invio senza dover creare personalmente ogni integrazione.
Per gli scenari mobili e offline, l'approccio consigliato è quello di creare la propria app e recuperare le definizioni dei moduli tramite l'API Forms adattiva headless.