Documentation du Widget PDF

Aperçu​

Le widget PDF vous permet d'afficher des documents PDF directement dans votre interface. Il rend les PDF en utilisant une iframe et fournit une gestion de secours pour les cas où le PDF ne peut pas être chargé ou aucune source n'est fournie.

Options de Configuration​

Configuration Globale​

Paramètres de Base​

Nom

• Champ: Identifiant du nom du widget
• Utilisation: Définissez un nom descriptif pour une identification facile dans l'interface
• Exemple: "Document de Contrat", "Manuel Utilisateur"

Variable/Modèle

• Champ: Liaison de modèle pour les sources PDF dynamiques
• Utilisation: Liez à une variable qui contient l'URL PDF
• Format: Nom de variable (par ex., documentUrl, pdfSource)
• Dynamique: Peut être mise à jour par programmation pour modifier le PDF affiché

Valeur par Défaut

• Champ: URL de source PDF statique
• Utilisation: Définissez un PDF par défaut à afficher lorsqu'aucune source dynamique n'est fournie
• Format: URL complète vers le fichier PDF
• Exemples:
  • https://example.com/documents/manual.pdf
  • https://storage.googleapis.com/bucket/document.pdf
  • /assets/files/sample.pdf

Comportement du Contenu​

Le widget suit cet ordre de priorité pour les sources PDF:

1. Valeur de Modèle Dynamique: Si un modèle est lié et a une valeur, il a la priorité
2. Valeur par Défaut Statique: Utilisée lorsqu'aucune valeur de modèle n'est disponible
3. Placeholder: Affiche le message "Aucun PDF à lire" lorsqu'aucune source n'est disponible

Configuration de Validation​

Visibilité Basée sur l'Écran​

Configurez le comportement du widget sur différentes tailles d'écran et contextes:

Disponible

• Objectif: Contrôle si le widget apparaît dans l'interface
• Options: Activez/désactivez par type d'écran
• Cas d'Utilisation: Masquez le visionneur PDF sur les appareils mobiles pour une meilleure performance

Visible

• Objectif: Visibilité dynamique basée sur les conditions
• Options:
  • Bouton bascule booléen pour l'affichage/masquage simple
  • Conditions avancées utilisant les expressions JavaScript
• Exemples:
  • {{user.role}} === 'admin' - Afficher uniquement pour les utilisateurs administrateur
  • {{documentType}} === 'contract' - Afficher uniquement pour les documents de contrat

Requis

• Objectif: Marquer le widget PDF comme obligatoire pour la validation du formulaire
• Comportement: Généralement utilisé lorsque la visualisation du PDF est requise avant de continuer
• Remarque: Plus applicable lorsque le widget PDF fait partie des flux de travail de formulaire

Désactiver

• Objectif: Empêcher l'interaction avec le widget
• Cas d'Utilisation: Afficher le PDF mais empêcher l'interaction utilisateur dans certains états

Configuration du Style​

Dimensions​

Largeur

• Champ: Largeur du widget en pixels ou en pourcentage
• Format: Nombre + unité
• Exemples: 800px, 100%, 50vw
• Par Défaut: 100% (largeur complète du conteneur)

Hauteur

• Champ: Hauteur du widget en pixels ou en pourcentage
• Format: Nombre + unité
• Exemples: 600px, 80vh, 400px
• Par Défaut: 100% (hauteur complète du conteneur)

Style CSS​

Noms de Classes

• Champ: Classes CSS personnalisées pour le style
• Format: Noms de classes séparés par des espaces
• Exemples: pdf-viewer, document-container bordered
• Utilisation: Appliquez un style personnalisé ou intégrez-vous aux systèmes de conception

Classes Dynamiques

• Objectif: Appliquez conditionnellement les classes CSS en fonction des données
• Format: Expressions JavaScript renvoyant les noms de classes
• Exemple: {{status === 'approved' ? 'approved-document' : 'pending-document'}}

Configuration Avancée​

Gestion des Erreurs​

Le widget gère automatiquement les erreurs courantes de chargement de PDF:

• 403 Interdit: Affiche un placeholder lorsque l'accès est refusé
• 404 Non Trouvé: Affiche un placeholder pour les fichiers manquants
• URLs Invalides: Revient gracieusement au placeholder
• Problèmes Réseau: Fournit un état d'erreur convivial

États de Chargement​

Chargement Initial

• Affiche immédiatement l'iframe lorsque la source est disponible
• Affiche un placeholder lors de la détermination de la disponibilité du contenu

Récupération d'Erreur

• Réessaye automatiquement le chargement lorsque la source change
• Fournit un retour visuel pour les échecs de chargement

Cas d'Utilisation​

Visionneur de Documents​

• Afficher des contrats, des manuels ou des rapports
• Fournir des capacités d'examen de documents en application
• Éliminer le besoin d'applications PDF externes

Intégration de Formulaire​

• Afficher les termes et conditions lors de l'inscription
• Afficher les documents de référence à côté des champs de formulaire
• Prévisualiser les documents générés avant la soumission

Gestion de Contenu​

• Parcourir les bibliothèques de documents
• Prévisualiser les fichiers avant le téléchargement
• Afficher la documentation avec pertinence contextuelle

Contenu Éducatif​

• Afficher le matériel de cours ou les feuilles de travail
• Afficher les guides de référence et les tutoriels
• Fournir des ressources d'apprentissage interactives

Meilleures Pratiques​

Optimisation des Performances​

1. Utilisez des dimensions appropriées: Ne rendez pas les PDF inutilement volumineux
2. Implémentez le chargement paresseux: Utilisez les conditions de visibilité pour charger les PDF uniquement quand nécessaire
3. Optimisez les fichiers PDF: Assurez-vous que les PDF sources sont optimisés pour le web
4. Considérez l'expérience mobile: Les PDF peuvent ne pas s'afficher correctement sur les petits écrans

Expérience Utilisateur​

1. Fournissez des indicateurs de chargement: Les utilisateurs doivent savoir quand le contenu se charge
2. Gérez les erreurs gracieusement: Affichage de messages significatifs pour les chargements échoués
3. Assurez l'accessibilité: Tenez compte des utilisateurs qui pourraient avoir besoin de formats de document alternatifs
4. Testez sur les navigateurs: Le rendu PDF peut varier entre les navigateurs

Considérations de Sécurité​

1. Validez les sources PDF: Assurez-vous que les URL pointent vers des fichiers PDF légitimes
2. Utilisez HTTPS: Connexions sécurisées pour le contenu PDF
3. Contrôle d'accès: Implémentez une authentification appropriée pour les documents sensibles
4. Validation du contenu: Vérifiez que le contenu PDF est approprié et sûr

Dépannage​

Problèmes Courants​

PDF ne s'affiche pas

• Vérifiez que l'URL source est accessible
• Vérifiez les restrictions CORS sur le serveur PDF
• Assurez-vous que le fichier est un format PDF valide

Problèmes de disposition

• Ajustez les paramètres de largeur et de hauteur
• Vérifiez les contraintes CSS du conteneur parent
• Testez le comportement réactif sur différentes tailles d'écran

Problèmes de performance

• Optimisez les tailles de fichiers PDF
• Implémentez le chargement conditionnel
• Envisagez la pagination pour les grands documents

Compatibilité des navigateurs

• Testez le rendu PDF sur différents navigateurs
• Fournissez des options de secours pour les navigateurs non pris en charge
• Envisagez d'utiliser PDF.js pour un rendu cohérent

Support des Navigateurs​

Le widget PDF s'appuie sur le support natif des PDF du navigateur ou les plugins:

• Chrome/Edge: Visionneur PDF natif
• Firefox: Rendu PDF.js intégré
• Safari: Support PDF natif
• Navigateurs mobiles: Peut nécessiter des applications PDF externes

Pour garantir la compatibilité entre navigateurs, envisagez d'implémenter PDF.js comme rendu de secours.