Contraintes JavaScript
Important
La plateforme d’impression moderne est le moyen privilégié de Windows pour communiquer avec les imprimantes. Nous vous recommandons d’utiliser le pilote de classe IPP en boîte de Microsoft, ainsi que les applications de support d’impression (PSA), pour personnaliser l’expérience d’impression dans Windows 10 et 11 pour le développement de périphériques d’impression.
Pour plus d’informations, veuillez consulter la section Plateforme d’impression moderne et le Guide de conception des applications de support d’impression.
Le modèle de pilote d’imprimante v4 prend en charge un nouveau modèle pour la gestion des contraintes étendues et de PrintTicket dérivé de l’interface v3 IPrintOemPrintTicketProvider.
Cependant, au lieu d’utiliser un plug-in de configuration compilé, les pilotes d’imprimante v4 utilisent JavaScript pour implémenter des API appelées contraintes JavaScript, et le pilote d’imprimante peut en implémenter une ou plusieurs selon les besoins. Pour plus d’informations, veuillez consulter les fonctions de la section API de contraintes JavaScript à la fin de cette rubrique.
Les contraintes JavaScript peuvent être utilisées pour augmenter les PrintCapabilities, valider les PrintTickets et gérer la conversion de PrintTicket en DEVMODE et vice versa. Cependant, les contraintes JavaScript présentent quelques limitations. Voici une liste des principales limitations :
Les fonctionnalités et options ajoutées à l’aide de CompletePrintCapabilities, ainsi que les contraintes spécifiées dans validatePrintTicket, ne sont pas affichées dans la fenêtre des préférences de l’imprimante de bureau.
Les fonctionnalités et options ajoutées à l’aide de CompletePrintCapabilities ne sont pas conservées dans le DEVMODE public.
Les contraintes JavaScript ne peuvent pas accéder aux ressources linguistiques des DLL de ressources pour localiser les fonctionnalités, options ou paramètres ajoutés.
En tant que tel, nous recommandons d’utiliser les contraintes JavaScript uniquement lorsqu’elles sont appropriées. Les fonctionnalités et options doivent être spécifiées dans les fichiers GPD ou PPD dans la mesure du possible, et seules les contraintes complexes doivent être représentées en JavaScript.
Débogage des fichiers JavaScript
Une validation syntaxique de base des fichiers JavaScript est prise en charge en ouvrant le fichier JavaScript dans l’hôte de script basé sur Windows. Pour ce faire, faites un clic droit sur le fichier JavaScript et sélectionnez Ouvrir avec, puis choisissez l’entrée de l’hôte de script basé sur Windows dans la liste. Si aucune erreur n’est générée, alors le JavaScript est syntaxiquement valide. Sinon, il indiquera le numéro de ligne du problème, comme illustré dans la capture d’écran suivante.
Les outils de validation JavaScript disponibles publiquement peuvent également être précieux pour évaluer le style des fichiers JavaScript.
Le débogage interactif peut être activé en créant la clé de registre suivante :
Nom de la clé : HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Print
Nom de la valeur : EnableJavaScriptDebugging
Type : DWORD
Valeur : 1
Cependant, comme PrintConfig.dll est chargé et déchargé fréquemment, le débogage d’une application qui imprime n’est pas une stratégie de test/débogage recommandée. Microsoft recommande plutôt que les fabricants construisent une application de test qui appelle chacun des points d’entrée pertinents pour les contraintes JavaScript en utilisant ces API publiques : PTGetPrintCapabilities, PTConvertDevModeToPrintTicket, PTConvertPrintTicketToDevMode et PTMergeAndValidatePrintTicket.
L’application de test seule est suffisante pour permettre le débogage, mais il est également bénéfique d’ajouter des tests unitaires pour s’assurer que l’ensemble du pilote gère PrintTicket, PrintCapabilities et les contraintes comme prévu. Pour plus d’informations sur la création de tests unitaires dans Visual Studio, veuillez consulter la rubrique suivante :
Un guide pas à pas des tests unitaires avec Visual Studio Team Test
Après avoir créé la clé de registre mentionnée ci-dessus et redémarré le processus d’hébergement, vous pouvez déboguer votre fichier source JavaScript.
Il est important de noter que si le fichier source échoue à l’analyse, le débogueur n’est pas invoqué et il semblera que l’environnement de débogage a échoué. Si le fichier source échoue à l’analyse, veuillez consulter Windows Script Host pour plus d’informations sur la façon de procéder.
Si aucune erreur n’est rencontrée et que votre fichier source est analysé avec succès, déboguez votre fichier source comme suit :
Installez Microsoft Visual Studio 2012 ou une version ultérieure sur la machine de test.
Créez une file d’attente d’impression en utilisant le pilote qui contient le code de contraintes JavaScript.
Définissez cette file d’attente d’impression comme file d’attente par défaut.
Démarrez votre application de test ou une application qui imprime et commencez un scénario qui fera appel aux contraintes JavaScript. L’application doit faire appel aux API PrintTicket/PrintCapabilities pour entrer dans les contraintes JavaScript ; les anciennes applications comme Notepad n’appellent pas ces API, mais l’application XPS Viewer le fait. Microsoft recommande d’utiliser une application de test ici, car les scénarios peuvent être plus facilement isolés et reproduits.
À ce moment-là, le « Débogueur Just-In-Time de Visual Studio » apparaîtra en disant « Une exception non gérée s’est produite dans <votre application> ».
Lancez une nouvelle instance de Visual Studio 2012 ou une version ultérieure.
Choisissez Déboguer, puis Attacher au processus.
Dans la boîte de dialogue Attacher au processus, assurez-vous que Attacher à : est défini sur le code de script.
Choisissez maintenant l’application de test ou l’application d’impression, puis enfin choisissez Attacher.
Cliquez sur « Tout interrompre ».
Retournez maintenant à la boîte de dialogue « Débogueur Just-In-Time de Visual Studio » et cliquez sur « Non ».
Visual Studio entrera dans le débogueur à l’emplacement appelé par le test en cours. Vous pouvez maintenant déboguer le code normalement.
API de contraintes JavaScript
Cette section spécifie les fonctions qui servent de points d’entrée API pour une utilisation dans le fichier de contraintes JavaScript. Voici les fonctions :
validatePrintTicket
completePrintCapabilities
convertDevModeToPrintTicket
convertPrintTicketToDevMode
fonction validatePrintTicket
Cette API est appelée pour valider qu’un objet PrintTicket est valide pour une imprimante particulière. Cela est analogue en fonction à l’API IPrintOemPrintTicketProvider::ValidatePrintTicket.
syntaxe de validatePrintTicket
function validatePrintTicket(printTicket, scriptContext)
paramètres de validatePrintTicket
printTicket
[in][out] L’objet IPrintSchemaTicket à valider.
scriptContext
[in] L’objet IPrinterScriptContext qui fournit l’accès au driver property bag, au queue property bag et au user property bag.
valeur de retour de validatePrintTicket
| Valeur retournée | Description |
|---|---|
| 0 | Indique que le paramètre printTicket était invalide et n’a pas pu être corrigé. Équivalent à E_PRINTTICKET_FORMAT. |
| 1 | Indique que le paramètre printTicket est un PrintTicket valide pour cette imprimante. Équivalent à S_PT_NO_CONFLICT. |
| 2 | Indique que le paramètre printTicket a été modifié pour le rendre valide. Équivalent à S_PT_CONFLICT_RESOLVED. |
fonction completePrintCapabilities
Cette API est appelée pour permettre la modification de l’objet PrintCapabilities. Cela devrait être utilisé pour les fonctionnalités conditionnelles (par exemple, le sans bordure n’est pris en charge que sur le papier photo) ou pour représenter des fonctionnalités qui ne pourraient pas autrement être générées par un fichier GPD ou PPD (par exemple, des définitions de fonctionnalités imbriquées). Cela est analogue en fonction à l’API IPrintOemPrintTicketProvider::CompletePrintCapabilities.
syntaxe de completePrintCapabilities
function completePrintCapabilities(printTicket, scriptContext, printCapabilities)
paramètres de completePrintCapabilities
printTicket
[in] L’objet IPrintSchemaTicket fourni pour contraindre le document PrintCapabilities généré.
scriptContext
[in] L’objet IPrinterScriptContext qui fournit l’accès au driver property bag, au queue property bag et au user property bag.
printCapabilities
[in][out] L’objet IPrintSchemaCapabilities représentant l’objet PrintCapabilities de base généré par le module de configuration.
valeur de retour de completePrintCapabilities
Aucune.
fonction convertDevModeToPrintTicket
Cette API est appelée pour convertir les valeurs du property bag DEVMODE en un PrintTicket. Cela est analogue en fonction à l’API IPrintOemPrintTicketProvider::ConvertDevModeToPrintTicket, sauf que cette implémentation encapsule la section privée du DEVMODE dans un objet IPrinterScriptablePropertyBag et n’autorise aucun accès à la section publique du DEVMODE.
syntaxe de convertDevModeToPrintTicket
function convertDevModeToPrintTicket(devModeProperties, scriptContext, printTicket)
paramètres de convertDevModeToPrintTicket
- devModeProperties
[in] L’objet IPrinterScriptablePropertyBag représentant le Property Bag DEVMODE.
scriptContext
[in] L’objet IPrinterScriptContext qui fournit l’accès au driver property bag, au queue property bag et au user property bag.
printTicket
[in][out] L’objet IPrintSchemaTicket représentant le PrintTicket.
valeur de retour de convertDevModeToPrintTicket
Aucune.
fonction convertPrintTicketToDevMode
Cette API est appelée pour convertir les valeurs d’un PrintTicket dans le property bag DEVMODE. Cela est analogue en fonction à l’API IPrintOemPrintTicketProvider::ConvertPrintTicketToDevMode, sauf que cette implémentation encapsule la section privée du DEVMODE dans un objet IPrinterScriptablePropertyBag et n’autorise aucun accès à la section publique du DEVMODE.
syntaxe de convertPrintTicketToDevMode
function convertPrintTicketToDevMode(printTicket, scriptContext, devModeProperties)
paramètres de convertPrintTicketToDevMode
printTicket
[in] L’objet IPrintSchemaTicket représentant le PrintTicket à convertir.
scriptContext
[in] L’objet IPrinterScriptContext qui fournit l’accès au driver property bag, au queue property bag et au user property bag.
devModeProperties
[in][out] L’objet IPrinterScriptablePropertyBag représentant le Property Bag DEVMODE.
valeur de retour de convertPrintTicketToDevMode
Aucune.
Bonnes pratiques pour les contraintes
La boîte de dialogue d’impression de Windows 8 et l’expérience des préférences d’impression prennent en charge uniquement un sous-ensemble de l’espace de noms des mots-clés du schéma d’impression. Par conséquent, Microsoft ne recommande pas d’utiliser des contraintes entre des fonctionnalités prises en charge dans la boîte de dialogue d’impression de Windows 8 ou dans l’interface utilisateur des préférences d’impression et des fonctionnalités qui ne le sont pas, car les utilisateurs n’auront aucune possibilité de résoudre de telles contraintes.
Par exemple, si l’option PageMediaType appelée Photo est contrainte à ne fonctionner qu’avec une valeur PageResolution de 1200dpi, les utilisateurs ne pourront jamais choisir le type de média Photo. Dans de tels cas, il est préférable de correspondre à l’intention de l’utilisateur (média Photo) et d’ajuster tous les paramètres nécessaires pour que cela se produise. Ces ajustements peuvent être effectués dans le code de contrainte JavaScript.
Si un pilote n’utilise pas les contraintes JavaScript, il n’est pas nécessaire de fournir un fichier. Si un pilote utilise des contraintes JavaScript pour seulement un sous-ensemble des points d’entrée (par exemple, validatePrintTicket), les autres points d’entrée doivent être entièrement omis du fichier JavaScript.