JavaScript-Einschränkungen
Wichtig
Die Modern Print-Plattform ist die von Windows bevorzugte Methode zur Kommunikation mit Druckern. Wir empfehlen die Verwendung des Microsoft IPP-Treibers für die Posteingangsklasse zusammen mit Print Support Apps (PSA), um das Druckverhalten in Windows 10 und 11 für die Entwicklung von Druckergeräten anzupassen.
Weitere Informationen finden Sie unter Modern Print-Plattform und der Anleitung zum Design der Print-Support-App.
Das v4-Druckertreibermodell unterstützt ein neues Modell für die erweiterte Constraint- und PrintTicket-Verarbeitung, das von der v3 IPrintOemPrintTicketProvider-Schnittstelle abgeleitet ist.
Anstelle eines kompilierten Konfigurations-Plug-Ins verwenden v4-Druckertreiber jedoch JavaScript zur Implementierung von APIs, die JavaScript-Einschränkungen genannt werden, und der Druckertreiber kann je nach Anforderung eine oder mehrere von ihnen implementieren. Weitere Informationen finden Sie unter den Funktionen im Abschnitt JavaScript-Constraint-APIs am Ende dieses Themas.
JavaScript-Einschränkungen können verwendet werden, um PrintCapabilities zu erweitern, PrintTickets zu validieren und die Konvertierung von PrintTicket in DEVMODE und umgekehrt zu steuern. JavaScript-Einschränkungen haben jedoch einige Einschränkungen. Im Folgenden finden Sie eine Liste der wichtigsten Einschränkungen:
Funktionen und Optionen, die mit CompletePrintCapabilities hinzugefügt wurden, sowie Einschränkungen, die in validatePrintTicket angegeben wurden, werden im Fenster mit den Desktop-Druckereinstellungen nicht angezeigt.
Funktionen und Optionen, die mit CompletePrintCapabilities hinzugefügt wurden, werden nicht in den öffentlichen DEVMODE übernommen.
JavaScript-Einschränkungen können nicht auf Sprachressourcen von Ressourcen-Dlls zugreifen, um hinzugefügte Funktionen und Optionen oder Parameter zu lokalisieren.
Daher empfehlen wir, JavaScript-Einschränkungen nur in geeigneten Fällen zu verwenden. Funktionen und Optionen sollten nach Möglichkeit in den GPD- oder PPD-Dateien angegeben werden, und nur komplizierte Beschränkungen sollten in JavaScript dargestellt werden.
Fehlersuche in JavaScript-Dateien
Die grundlegende syntaktische Überprüfung von JavaScript-Dateien wird durch das Öffnen der JavaScript-Datei im Windows-basierten Script Host unterstützt. Klicken Sie dazu mit der rechten Maustaste auf die JavaScript-Datei und wählen Sie Öffnen mit, und wählen Sie den Eintrag "Windows basierter Script Host" in der Liste. Wenn keine Fehler ausgelöst werden, ist das JavaScript syntaktisch gültig. Andernfalls wird die Zeilennummer des Fehlers angezeigt, wie im folgenden Screenshot zu sehen ist.
Öffentlich zugängliche JavaScript-Validierungstools können ebenfalls eine wertvolle Hilfe bei der Bewertung des Stils von JavaScript-Dateien sein.
Die interaktive Fehlersuche kann aktiviert werden, indem Sie den folgenden Registrierungsschlüssel erstellen:
Schlüsselname: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Print
Wertname: EnableJavaScriptDebugging
Typ: DWORD
Wert: 1
Da PrintConfig.dll jedoch häufig geladen und entladen wird, ist das Debuggen einer App, die druckt, keine empfohlene Test-/Debugging-Strategie. Stattdessen empfiehlt Microsoft, dass Hersteller eine App zum Testen erstellen, die jeden der relevanten Einstiegspunkte für JavaScript-Einschränkungen über diese öffentlichen APIs aufruft: PTGetPrintCapabilities, PTConvertDevModeToPrintTicket, PTConvertPrintTicketToDevMode, und PTMergeAndValidatePrintTicket.
Die Test-App allein reicht aus, um das Debugging zu ermöglichen, aber es ist auch von Vorteil, Unit-Tests hinzuzufügen, um sicherzustellen, dass der gesamte Treiber PrintTicket, PrintCapabilities und Constraints wie erwartet behandelt. Weitere Informationen über die Erstellung von Unit-Tests in Visual Studio finden Sie unter dem folgenden Thema:
Eine exemplarische Vorgehensweise für Unit-Tests mit Visual Studio Team Test
Nachdem der im vorangegangenen Text gezeigte Registrierungsschlüssel erstellt und der Host-Prozess neu gestartet wurde, können Sie Ihre JavaScript-Quelldatei debuggen.
Es ist wichtig zu beachten, dass der Debugger nicht aufgerufen wird, wenn die Quelldatei nicht geparst werden kann, und dass es so aussieht, als ob die Debug-Umgebung ausgefallen wäre. Wenn die Quelldatei nicht geparst werden kann, finden Sie unter Windows Script Host weitere Informationen über das weitere Vorgehen.
Wenn keine Fehler auftreten und Ihre Quelldatei erfolgreich geparst wird, debuggen Sie Ihre Quelldatei wie folgt:
Installieren Sie Microsoft Visual Studio 2012 oder höher auf dem Test Computer.
Erstellen Sie eine Warteschlange mit dem Treiber, der den JavaScript-Constrains-Code hat.
Legen Sie diese Warteschlange als Standard fest.
Starten Sie Ihre Test-App oder eine App, die druckt, und beginnen Sie ein Szenario, bei dem JavaScript-Einschränkungen aufgerufen werden. Die App muss die PrintTicket/PrintCapabilities-APIs aufrufen, um in die JavaScript-Einschränkungen einzugreifen. Ältere Apps wie Notepad rufen diese APIs nicht auf, aber die XPS Viewer-App schon. Microsoft empfiehlt hier die Verwendung einer Test-App, da sich die Szenarien so leichter isolieren und reproduzieren lassen.
Zu diesem Zeitpunkt wird der Visual Studio Just-in-Time Debugger mit der Meldung "In <Ihrer App> ist eine unbehandelte Ausnahme aufgetreten" angezeigt.
Starten Sie eine neue Instanz von Visual Studio 2012 oder höher.
Wählen Sie Debuggen und dann "An Prozess anhängen".
Stellen Sie im Dialog "An Prozess anhängen" sicher, dass "Anhängen an:" auf "Script Code" festgelegt ist.
Wählen Sie nun die Test-App oder den App-Druck und wählen Sie schließlich Anhängen.
Klicken Sie auf "Alles abbrechen".
Gehen Sie nun zurück zum Dialogfeld "Visual Studio Just-in-Time Debugger" und klicken Sie auf "Nein".
Visual Studio wird an dem Speicherort, den der aktuelle Test aufruft, in den Debugger wechseln. Sie können den Code nun normal debuggen.
JavaScript-Constraint-APIs
In diesem Abschnitt werden die Funktionen angegeben, die als API-Einstiegspunkte für die Verwendung in der JavaScript-Constraint-Datei dienen. Dies sind die Funktionen:
validatePrintTicket
completePrintCapabilities
convertDevModeToPrintTicket
convertPrintTicketToDevMode
validatePrintTicket-Funktion
Diese API wird aufgerufen, um zu überprüfen, ob ein PrintTicket-Objekt für einen bestimmten Drucker gültig ist. Die Funktion ist analog zur IPrintOemPrintTicketProvider::ValidatePrintTicket API.
validatePrintTicket-Syntax
function validatePrintTicket(printTicket, scriptContext)
validatePrintTicket-Parameter
printTicket
[in][out] Das IPrintSchemaTicket-Objekt, das validiert werden soll.
scriptContext
[in] Das IPrinterScriptContext-Objekt, das Zugriff auf die Property-Bag des Treibers, die Property-Bag der Warteschlange und die Property-Bag des Benutzers bietet.
validatePrintTicket-Rückgabewert
| Rückgabewert | BESCHREIBUNG |
|---|---|
| 0 | Gibt an, dass der Parameter printTicket ungültig war und nicht korrigiert werden konnte. Äquivalent zu E_PRINTTICKET_FORMAT. |
| 1 | Zeigt an, dass der Parameter printTicket ein gültiges PrintTicket für diesen Drucker ist. Äquivalent zu S_PT_NO_CONFLICT. |
| 2 | Zeigt an, dass der Parameter printTicket geändert wurde, um ihn gültig zu machen. Äquivalent zu S_PT_CONFLICT_RESOLVED. |
completePrintCapabilities-Funktion
Diese API wird aufgerufen, um die Möglichkeit zu bieten, das PrintCapabilities-Objekt zu ändern. Dies sollte für bedingte Funktionen verwendet werden (z. B. wird Randlos nur auf Fotopapier unterstützt) oder um Funktionen darzustellen, die sonst nicht von einer GPD- oder PPD-Datei generiert werden könnten (z.B . eingebettete Funktionsdefinitionen). Die Funktion ist analog zur IPrintOemPrintTicketProvider::CompletePrintCapabilities-API.
completePrintCapabilities-Syntax
function completePrintCapabilities(printTicket, scriptContext, printCapabilities)
completePrintCapabilities-Parameter
printTicket
[in] Das IPrintSchemaTicket-Objekt, auf das das generierte PrintCapabilities-Dokument beschränkt werden soll.
scriptContext
[in] Das IPrinterScriptContext-Objekt, das Zugriff auf die Property-Bag des Treibers, die Property-Bag der Warteschlange und die Property-Bag des Benutzers bietet.
printCapabilities
[in][out] Das IPrintSchemaCapabilities-Objekt, das das vom Konfigurationsmodul generierte Basisobjekt PrintCapabilities darstellt.
completePrintCapabilities-Rückgabewert
Keine.
convertDevModeToPrintTicket-Funktion
Diese API wird aufgerufen, um Werte aus der DEVMODE-Property-Bag in ein PrintTicket zu konvertieren. Die Funktion entspricht der IPrintOemPrintTicketProvider::ConvertDevModeToPrintTicket-API, mit der Ausnahme, dass diese Implementierung den privaten Teil des DEVMODE in ein IPrinterScriptablePropertyBag-Objekt kapselt und keinen Zugriff auf den öffentlichen Teil des DEVMODE zulässt.
convertDevModeToPrintTicket-Syntax
function convertDevModeToPrintTicket(devModeProperties, scriptContext, printTicket)
convertDevModeToPrintTicket-Parameter
- devModeProperties
[in] Das IPrinterScriptablePropertyBag-Objekt, das die DEVMODE-Property-Bag darstellt.
scriptContext
[in] Das IPrinterScriptContext-Objekt, das Zugriff auf die Property-Bag des Treibers, die Property-Bag der Warteschlange und die Property-Bag des Benutzers bietet.
printTicket
[in][out] Das IPrintSchemaTicket-Objekt, das das PrintTicket darstellt.
convertDevModeToPrintTicket-Rückgabewert
Keine.
convertPrintTicketToDevMode-Funktion
Diese API wird aufgerufen, um Werte aus einem PrintTicket in die DEVMODE-Property-Bag zu konvertieren. Die Funktion entspricht der IPrintOemPrintTicketProvider::ConvertPrintTicketToDevMode-API, mit der Ausnahme, dass diese Implementierung den privaten Bereich des DEVMODE in ein IPrinterScriptablePropertyBag-Objekt kapselt und keinen Zugriff auf den öffentlichen Bereich des DEVMODE zulässt.
convertPrintTicketToDevMode-Syntax
function convertPrintTicketToDevMode(printTicket, scriptContext, devModeProperties)
convertPrintTicketToDevMode-Parameter
printTicket
[in] Das IPrintSchemaTicket-Objekt, das das zu konvertierende PrintTicket darstellt.
scriptContext
[in] Das IPrinterScriptContext-Objekt, das Zugriff auf die Property-Bag des Treibers, die Property-Bag der Warteschlange und die Property-Bag des Benutzers bietet.
devModeProperties
[in][out] Das IPrinterScriptablePropertyBag-Objekt, das die DEVMODE-Property-Bag darstellt.
convertPrintTicketToDevMode-Rückgabewert
Keine.
Bewährte Verfahren für Constraints
Der Windows 8-Druckdialog und die Druckeinstellungen unterstützen nur eine Untermenge des Print Schema Keywords-Namespace. Daher rät Microsoft davon ab, Constraints zwischen Funktionen, die im Windows 8 Druckdialog oder in den Druckeinstellungen unterstützt werden, und Funktionen, die nicht in dieser Benutzeroberfläche enthalten sind, zu verwenden, da die Benutzer keine Möglichkeit haben, solche Constraints aufzulösen.
Wenn beispielsweise die Option PageMediaType namens Photo nur mit einem PageResolution-Wert von 1200 dpi funktioniert, können die Benutzenden niemals den Medientyp Photo auswählen. In solchen Fällen ist es besser, die Absicht des Benutzers (Fotomedien) zu berücksichtigen und die dafür erforderlichen Einstellungen anzupassen. Diese Anpassungen können im JavaScript-Constraint-Code vorgenommen werden.
Wenn ein Treiber keine JavaScript-Einschränkungen verwendet, ist die Bereitstellung einer Datei nicht erforderlich. Wenn ein Treiber JavaScript-Einschränkungen nur für eine Untermenge der Einstiegspunkte verwendet (z. B. validatePrintTicket), sollten die anderen Einstiegspunkte in der JavaScript-Datei ganz weggelassen werden.