Vincoli JavaScript
Importante
La piattaforma di stampa moderna è il mezzo preferito di Windows per comunicare con le stampanti. Ti consigliamo di usare il driver di classe IPP di Microsoft, insieme a Print Support Apps (PSA), per personalizzare l'esperienza di stampa in Windows 10 e 11 per lo sviluppo di dispositivi per stampanti.
Per altre informazioni, vedere Piattaforma di stampa moderna e guida alla progettazione dell'app di supporto per la stampa.
Il modello di driver della stampante v4 supporta un nuovo modello per il vincolo esteso e la gestione PrintTicket derivata dall'interfaccia IPrintOemPrintTicketProvider v3.
Invece di usare un plug-in di configurazione compilato, tuttavia, i driver della stampante v4 usano JavaScript per implementare API denominate vincoli JavaScript e il driver della stampante può implementarne uno o più in base alle esigenze. Per altre informazioni, vedere le funzioni nella sezione API vincolo JavaScript alla fine di questo argomento.
I vincoli JavaScript possono essere usati per aumentare PrintCapabilities, convalidare PrintTickets e gestire la conversione di PrintTicket in DEVMODE e viceversa. Tuttavia, i vincoli JavaScript presentano alcune limitazioni. Di seguito è riportato un elenco delle limitazioni principali:
Le funzionalità e le opzioni aggiunte tramite CompletePrintCapabilities, nonché i vincoli specificati in validatePrintTicket non vengono visualizzati nella finestra delle preferenze della stampante desktop.
Le funzionalità e le opzioni aggiunte in con CompletePrintCapabilities non vengono rese persistenti in DEVMODE pubblico.
I vincoli JavaScript non possono accedere alle risorse del linguaggio dalle DLL delle risorse per localizzare le funzionalità e le opzioni o i parametri aggiunti.
Di conseguenza, è consigliabile usare i vincoli JavaScript solo se appropriato. Le funzionalità e le opzioni devono essere specificate nei file GPD o PPD, dove possibile, e devono essere rappresentati solo vincoli complessi in JavaScript.
Debug di file JavaScript
La convalida sintattica di base dei file JavaScript è supportata aprendo il file JavaScript nell'host di script basato su Windows. A tale scopo, fare clic con il pulsante destro del mouse sul file JavaScript e scegliere Apri con e scegliere la voce Host script basato su Windows nell'elenco. Se non vengono generati errori, JavaScript è sintatticamente valido. In caso contrario, indica il numero di riga del problema, come illustrato nello screenshot seguente.
Gli strumenti di convalida JavaScript disponibili pubblicamente possono essere utili anche per valutare lo stile dei file JavaScript.
Il debug interattivo può essere abilitato creando la chiave del Registro di sistema seguente:
Nome chiave: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Print
Nome valore: EnableJavaScriptDebugging
Tipo: DWORD
Valore: 1
Tuttavia, poiché PrintConfig.dll viene caricato e scaricato di frequente, il debug di un'app che stampa non è una strategia di test/debug consigliata. Microsoft consiglia invece ai produttori di creare un'app di test che chiama ognuno dei punti di ingresso pertinenti per i vincoli JavaScript usando queste API pubbliche: PTGetPrintCapabilities, PTConvertDevModeToPrintTicket, PTConvertPrintTicketToDevMode e PTMergeAndValidatePrintTicket.
L'app di test da sola è sufficiente per abilitare il debug, ma è anche utile aggiungere unit test per garantire che l'intero driver gestisca PrintTicket, PrintCapabilities e vincoli come previsto. Per altre informazioni su come compilare unit test in Visual Studio, vedere l'argomento seguente:
Procedura dettagliata per unit test con Visual Studio Team Test
Dopo aver creato la chiave del Registro di sistema illustrata nel testo precedente e il processo di hosting è stato riavviato, è possibile eseguire il debug del file di origine JavaScript.
È importante notare che se il file di origine non riesce ad analizzare, il debugger non viene richiamato e sembra che l'ambiente di debug non sia riuscito. Se il file di origine non riesce ad analizzare, vedere Windows Script Host per altre informazioni su come procedere.
Se non sono presenti errori e il file di origine viene analizzato correttamente, eseguire il debug del file di origine come indicato di seguito:
Installare Microsoft Visual Studio 2012 o versione successiva nel computer di test
Creare una coda di stampa usando il driver con i vincoli del codice JavaScript
Impostare questa coda di stampa come predefinita.
Avviare l'app di test o un'app che stampa e iniziare uno scenario che causerà la chiamata dei vincoli JavaScript. L'app deve chiamare le API PrintTicket/PrintCapabilities per suddividere i vincoli JavaScript; le app precedenti come Blocco note non chiamano queste API, ma l'app XPS Viewer fa. Microsoft consiglia di usare un'app di test qui, poiché gli scenari possono essere più facilmente isolati e riprodotti.
A questo punto, il "Debugger JUST-In-Time di Visual Studio" verrà visualizzato dicendo "Si è verificata un'eccezione non gestita nell'app<>"
Avviare una nuova istanza di Visual Studio 2012 o versione successiva
Scegliere Debug, quindi Collega a processo
Nella finestra di dialogo Connetti a processo verificare che Connetti a: sia impostato su Codice script
Scegliere ora l'app di test o la stampa di app e infine scegliere Connetti
Fare clic su "Interrompi tutto"
Tornare ora alla finestra di dialogo "Debugger JUST-In-Time di Visual Studio" e fare clic su "No"
Visual Studio eseguirà un'interruzione nel debugger nel percorso chiamato dal test corrente. È ora possibile eseguire il debug del codice normalmente.
API dei vincoli JavaScript
Questa sezione specifica le funzioni che fungono da punti di ingresso dell'API da usare nel file di vincoli JavaScript. Queste sono le funzioni seguenti:
validatePrintTicket
completePrintCapabilities
convertDevModeToPrintTicket
convertPrintTicketToDevMode
Funzione validatePrintTicket
Questa API viene chiamata per verificare che un oggetto PrintTicket sia valido per una determinata stampante. Questa operazione è analoga alla funzione dell'API IPrintOemPrintTicketProvider::ValidatePrintTicket .
sintassi validatePrintTicket
function validatePrintTicket(printTicket, scriptContext)
parametri validatePrintTicket
printTicket
[in] [out] Oggetto IPrintSchemaTicket da convalidare.
scriptContext
[in] Oggetto IPrinterScriptContext che consente di accedere al contenitore delle proprietà driver, al contenitore delle proprietà della coda e al contenitore delle proprietà utente.
valore restituito validatePrintTicket
| Valore restituito | Descrizione |
|---|---|
| 0 | Indica che il parametro printTicket non è valido e non è stato possibile correggerlo. Equivale a E_PRINTTICKET_FORMAT. |
| 1 | Indica che il parametro printTicket è un printTicket valido per questa stampante. Equivalente a S_PT_NO_CONFLICT. |
| 2 | Indica che il parametro printTicket è stato modificato per renderlo valido. Equivale a S_PT_CONFLICT_RESOLVED. |
funzione completePrintCapabilities
Questa API viene chiamata per consentire la modifica dell'oggetto PrintCapabilities. Questa opzione deve essere usata per le funzionalità condizionali(ad esempio, senza bordi è supportata solo su carta fotografica) o per rappresentare le funzionalità che non possono essere altrimenti generate da un file GPD o PPD (ad esempio, definizioni di funzionalità annidate). Questa operazione è analoga alla funzione dell'API IPrintOemPrintTicketProvider::CompletePrintCapabilities .
sintassi completePrintCapabilities
function completePrintCapabilities(printTicket, scriptContext, printCapabilities)
parametri completePrintCapabilities
printTicket
[in] Input dell'oggetto IPrintSchemaTicket per vincolare il documento PrintCapabilities generato.
scriptContext
[in] Oggetto IPrinterScriptContext che consente di accedere al contenitore delle proprietà driver, al contenitore delle proprietà della coda e al contenitore delle proprietà utente.
printCapabilities
[in] [out] Oggetto IPrintSchemaCapabilities che rappresenta l'oggetto PrintCapabilities di base generato dal modulo di configurazione.
valore restituito completePrintCapabilities
Nessuno.
Funzione convertDevModeToPrintTicket
Questa API viene chiamata per convertire i valori dal contenitore delle proprietà DEVMODE in printticket. Questa operazione è analoga alla funzione dell'API IPrintOemPrintTicketProvider::ConvertDevModeToPrintTicket, ad eccezione del fatto che questa implementazione incapsula la sezione privata di DEVMODE in un oggetto IPrinterScriptablePropertyBag e non consente l'accesso alla sezione pubblica di DEVMODE.
Sintassi convertDevModeToPrintTicket
function convertDevModeToPrintTicket(devModeProperties, scriptContext, printTicket)
Parametri convertDevModeToPrintTicket
- devModeProperties
[in] Oggetto IPrinterScriptablePropertyBag che rappresenta il contenitore delle proprietà DEVMODE.
scriptContext
[in] Oggetto IPrinterScriptContext che consente di accedere al contenitore delle proprietà driver, al contenitore delle proprietà della coda e al contenitore delle proprietà utente.
printTicket
[in] [out] Oggetto IPrintSchemaTicket che rappresenta PrintTicket.
valore restituito convertDevModeToPrintTicket
Nessuno.
funzione convertPrintTicketToDevMode
Questa API viene chiamata per convertire i valori da printticket nel contenitore delle proprietà DEVMODE. Questa operazione è analoga all'API IPrintOemPrintTicketProvider::ConvertPrintTicketToDevMode, ad eccezione del fatto che questa implementazione incapsula la sezione privata di DEVMODE in un oggetto IPrinterScriptablePropertyBag e non consente l'accesso alla sezione pubblica di DEVMODE.
Sintassi convertPrintTicketToDevMode
function convertPrintTicketToDevMode(printTicket, scriptContext, devModeProperties)
parametri convertPrintTicketToDevMode
printTicket
[in] Oggetto IPrintSchemaTicket che rappresenta printticket da convertire.
scriptContext
[in] Oggetto IPrinterScriptContext che consente di accedere al contenitore delle proprietà driver, al contenitore delle proprietà della coda e al contenitore delle proprietà utente.
devModeProperties
[in] [out] Oggetto IPrinterScriptablePropertyBag che rappresenta il contenitore delle proprietà DEVMODE.
convertPrintTicketToDevMode valore restituito
Nessuno.
Procedure consigliate per i vincoli
La finestra di dialogo di stampa di Windows 8 e l'esperienza delle preferenze di stampa supportano solo un subset dello spazio dei nomi Parole chiave dello schema di stampa. Di conseguenza, Microsoft non consiglia l'uso di vincoli tra le funzionalità supportate nella finestra di dialogo di stampa di Windows 8 o nell'interfaccia utente delle preferenze di stampa e le funzionalità che non si trovano in tale interfaccia utente, poiché gli utenti non avranno la possibilità di risolvere tali vincoli.
Ad esempio, se l'opzione PageMediaType denominata Photo è vincolata a funzionare solo con un valore PageResolution pari a 1200dpi, gli utenti non potranno mai scegliere il tipo di supporto Foto. In casi come questo, è meglio abbinare la finalità dell'utente (supporti fotografici) e regolare le impostazioni necessarie per farlo. Queste modifiche possono essere apportate nel codice del vincolo JavaScript.
Se un driver non utilizza vincoli JavaScript, non è necessario specificare un file. Se un driver utilizza vincoli JavaScript solo per un subset dei punti di ingresso ,ad esempio validatePrintTicket, gli altri punti di ingresso devono essere completamente omessi dal file JavaScript.