Restrições de JavaScript
Importante
A plataforma de impressão moderna é o meio preferencial do Windows para se comunicar com as impressoras. Recomendamos que você use o driver de classe de caixa de entrada IPP da Microsoft juntamente com PSA (Aplicativos de Suporte à Impressão) para personalizar a experiência de impressão no Windows 10 e 11 para o desenvolvimento de dispositivos de impressora.
Para obter mais informações, consulte Plataformade impressão moderna e o Guia de design do aplicativo de suporte de impressão.
O modelo de driver de impressora v4 dá suporte a um novo modelo para restrição estendida e tratamento de PrintTicket derivado da interface IPrintOemPrintTicketProvider v3.
No entanto, em vez de usar um plug-in de configuração compilado, os drivers de impressora v4 usam JavaScript para implementar APIs chamadas restrições JavaScript, e o driver de impressora pode implementar uma ou mais delas conforme necessário. Para obter mais informações, consulte as funções na seção APIs de restrição JavaScript no final deste tópico.
As restrições JavaScript podem ser usadas para aumentar PrintCapabilities, validar PrintTickets e lidar com a conversão de PrintTicket em DEVMODE e vice-versa. No entanto, as restrições de JavaScript têm algumas limitações. Veja a seguir uma lista das principais limitações:
Os recursos e opções adicionados usando CompletePrintCapabilities, bem como as restrições especificadas em validatePrintTicket, não são mostrados na janela de preferências da impressora desktop.
Os recursos e opções adicionados usando CompletePrintCapabilities não são persistidos no DEVMODE público.
As restrições de JavaScript não podem acessar recursos de linguagem de dlls de recursos para localizar recursos e opções ou parâmetros adicionados.
Dessa forma, recomendamos que as restrições JavaScript sejam usadas somente quando apropriado. Recursos e opções devem ser especificados nos arquivos GPD ou PPD sempre que possível, e apenas restrições complicadas devem ser representadas em JavaScript.
Depurando arquivos JavaScript
A validação sintática básica de arquivos JavaScript é suportada pela abertura do arquivo JavaScript no Host de Script baseado em Windows. Para fazer isso, clique com o botão direito do mouse no arquivo JavaScript e selecione Abrir com e escolha a entrada Host de Script baseado em Windows na lista. Se nenhum erro for lançado, o JavaScript será sintaticamente válido. Caso contrário, ele apontará o número da linha do problema, conforme mostrado na captura de tela a seguir.
As ferramentas de validação de JavaScript disponíveis publicamente também podem ser valiosas como auxiliares na avaliação do estilo dos arquivos JavaScript.
A depuração interativa pode ser habilitada criando a seguinte chave do Registro:
Nome da chave: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Print
Nome do valor: EnableJavaScriptDebugging
Tipo: DWORD
Valor: 1
No entanto, como PrintConfig.dll é carregado e descarregado com frequência, depurar um aplicativo que imprime não é uma estratégia de teste/depuração recomendada. Em vez disso, a Microsoft recomenda que os fabricantes criem um aplicativo de teste que chame cada um dos pontos de entrada relevantes para restrições JavaScript usando estas APIs públicas: PTGetPrintCapabilities, PTConvertDevModeToPrintTicket, PTConvertPrintTicketToDevMode, e PTMergeAndValidatePrintTicket.
O aplicativo de teste sozinho é suficiente para habilitar a depuração, mas também é benéfico adicionar testes de unidade para garantir que todo o driver esteja lidando com PrintTicket, PrintCapabilities e restrições conforme o esperado. Para obter mais informações sobre como criar testes de unidade no Visual Studio, consulte o seguinte tópico:
Um passo a passo de teste de unidade com o Visual Studio Team Test
Depois que a chave do Registro mostrada no texto anterior for criada e o processo de hospedagem for reiniciado, você poderá depurar o arquivo de origem JavaScript.
É importante observar que, se o arquivo de origem não for analisado, o depurador não será invocado e parecerá que o ambiente de depuração falhou. Se o arquivo de origem não for analisado, consulte Windows Script Host para obter mais informações sobre como proceder.
Se não houver erros e o arquivo de origem for analisado com êxito, depure o arquivo de origem da seguinte maneira:
Instalar o Microsoft Visual Studio 2012 ou posterior no computador de teste
Criar uma fila de impressão usando o driver que tem as restrições de código JavaScript
Defina essa fila de impressão como padrão.
Inicie seu aplicativo de teste ou um aplicativo que imprime e inicie um cenário que fará com que as restrições de JavaScript sejam invocadas. O aplicativo deve chamar as APIs PrintTicket/PrintCapabilities para interromper as restrições de JavaScript; aplicativos mais antigos, como o Bloco de Notas, não chamam essas APIs, mas o aplicativo XPS Viewer sim. A Microsoft recomenda usar um aplicativo de teste aqui, pois os cenários podem ser isolados e reproduzidos com mais facilidade.
Neste momento, o "Depurador Just-In-Time do Visual Studio" aparecerá dizendo "Ocorreu uma exceção sem tratamento em <seu aplicativo>"
Iniciar uma nova instância do Visual Studio 2012 ou posterior
Escolha Depurar, então Anexar ao Processo.
Na caixa de diálogo Anexar ao Processo, certifique-se de que Anexar a: esteja definido como Código de script
Agora escolha o aplicativo de teste ou a impressão do aplicativo e, finalmente, escolha Anexar
Clique em "Quebrar tudo"
Agora volte para a caixa de diálogo "Depurador Just-In-Time do Visual Studio" e clique em "Não"
O Visual Studio entrará no depurador no local chamado pelo teste atual. Agora você pode depurar o código normalmente.
APIs de restrição JavaScript
Esta seção especifica as funções que servem como pontos de entrada da API para uso no arquivo de restrição JavaScript. Estas são as funções:
validatePrintTicket
completePrintCapabilities
convertDevModeToPrintTicket
convertPrintTicketToDevMode
Função validatePrintTicket
Essa API é chamada para validar se um objeto PrintTicket é válido para uma impressora específica. Isso é análogo em função à API IPrintOemPrintTicketProvider::ValidatePrintTicket.
sintaxe validatePrintTicket
function validatePrintTicket(printTicket, scriptContext)
Parâmetros validatePrintTicket
printTicket
[in][out] O objeto IPrintSchemaTicket a ser validado.
scriptContext
[in] O objeto IPrinterScriptContext que fornece acesso ao recipiente de propriedades do driver, ao recipiente de propriedades da fila e ao recipiente de propriedades do usuário.
valor de retorno validatePrintTicket
| Valor retornado | Descrição |
|---|---|
| 0 | Indica que o parâmetro printTicket era inválido e não pôde ser corrigido. Equivalente a E_PRINTTICKET_FORMAT. |
| 1 | Indica que o parâmetro printTicket é um PrintTicket válido para esta impressora. Equivalente a S_PT_NO_CONFLICT. |
| 2 | Indica que o parâmetro printTicket foi modificado para torná-lo válido. Equivalente a S_PT_CONFLICT_RESOLVED. |
função completePrintCapabilities
Essa API é chamada para permitir que o objeto PrintCapabilities seja modificado. Isso deve ser usado para recursos condicionais (por exemplo, sem bordas é suportado apenas em papel fotográfico) ou para representar recursos que não poderiam ser gerados por um arquivo GPD ou PPD (por exemplo, definições de recursos aninhados). Isso é análogo em função à API IPrintOemPrintTicketProvider::CompletePrintCapabilities.
sintaxe completePrintCapabilities
function completePrintCapabilities(printTicket, scriptContext, printCapabilities)
parâmetros completePrintCapabilities
printTicket
[in] A entrada do objeto IPrintSchemaTicket para restringir o documento PrintCapabilities gerado a.
scriptContext
[in] O objeto IPrinterScriptContext que fornece acesso ao recipiente de propriedades do driver, ao recipiente de propriedades da fila e ao recipiente de propriedades do usuário.
printCapabilities
[in][out] O objeto IPrintSchemaCapabilities que representa o objeto PrintCapabilities base que foi gerado pelo módulo de configuração.
valor retornado completePrintCapabilities
Nenhum.
função convertDevModeToPrintTicket
Essa API é chamada para converter valores do recipiente de propriedades DEVMODE em um PrintTicket. Isso é análogo em função à API IPrintOemPrintTicketProvider::ConvertDevModeToPrintTicket, exceto que essa implementação encapsula a seção privada do DEVMODE em um objeto IPrinterScriptablePropertyBag e não permite acesso à seção pública do DEVMODE.
Sintaxe convertDevModeToPrintTicket
function convertDevModeToPrintTicket(devModeProperties, scriptContext, printTicket)
parâmetros convertDevModeToPrintTicket
- devModeProperties
[in] O objeto IPrinterScriptablePropertyBag que representa o Recipiente de Propriedades DEVMODE.
scriptContext
[in] O objeto IPrinterScriptContext que fornece acesso ao recipiente de propriedades do driver, ao recipiente de propriedades da fila e ao recipiente de propriedades do usuário.
printTicket
[in][out] O objeto IPrintSchemaTicket que representa o PrintTicket.
valor retornado convertDevModeToPrintTicket
Nenhum.
função convertPrintTicketToDevMode
Esta API é chamada para converter valores de um PrintTicket no conjunto de propriedades DEVMODE. Isto é análogo em função à API IPrintOemPrintTicketProvider::ConvertPrintTicketToDevMode, exceto que esta implementação encapsula a seção privada do DEVMODE em um objeto IPrinterScriptablePropertyBag e não permite acesso à seção pública do DEVMODE.
sintaxe convertPrintTicketToDevMode
function convertPrintTicketToDevMode(printTicket, scriptContext, devModeProperties)
parâmetros convertPrintTicketToDevMode
printTicket
[in] O objeto IPrintSchemaTicket que representa o PrintTicket a ser convertido.
scriptContext
[in] O objeto IPrinterScriptContext que fornece acesso ao recipiente de propriedades do driver, ao recipiente de propriedades da fila e ao recipiente de propriedades do usuário.
devModeProperties
[in][out] O objeto IPrinterScriptablePropertyBag que representa o Recipiente de Propriedades DEVMODE.
valor retornado convertPrintTicketToDevMode
Nenhum.
Práticas recomendadas de restrição
A caixa de diálogo de impressão do Windows 8 e a experiência de preferências de impressão dão suporte apenas a um subconjunto do namespace Palavras-chave do Esquema de Impressão. Como resultado, a Microsoft não recomenda o uso de restrições entre os recursos com suporte na caixa de diálogo de impressão do Windows 8 ou na interface do usuário de preferências de impressão e os recursos que não estão nessa interface do usuário, pois os usuários não terão oportunidade de resolver essas restrições.
Por exemplo, se a opção PageMediaType chamada Photo for restrita a funcionar apenas com um valor PageResolution de 1200 dpi, os usuários nunca poderão escolher o tipo de mídia Photo. Em casos como esse, é melhor corresponder à intenção do usuário (mídia de foto) e ajustar as configurações necessárias para que isso ocorra. Esses ajustes podem ser feitos no código de restrição JavaScript.
Se um driver não utilizar restrições JavaScript, não haverá nenhum requisito de que um arquivo seja fornecido. Se um driver utilizar restrições JavaScript para apenas um subconjunto dos pontos de entrada (por exemplo, validatePrintTicket), os outros pontos de entrada deverão ser totalmente omitidos do arquivo JavaScript.