Restricciones de JavaScript
Importante
La plataforma de impresión moderna es el medio preferido de Windows para comunicarse con impresoras. Se recomienda usar el controlador de clase de bandeja de entrada IPP de Microsoft, junto con aplicaciones de soporte técnico de impresión (PSA), para personalizar la experiencia de impresión en Windows 10 y 11 para el desarrollo de dispositivos de impresora.
Para obtener más información, consulte Plataforma de impresión moderna y la Guía de diseño de aplicaciones para compatibilidad con impresión.
El modelo de controlador de impresora v4 admite un nuevo modelo para la restricción extendida y el control PrintTicket derivado de la interfaz IPrintOemPrintOemPrintTicketProvider v3.
Sin embargo, en lugar de usar un complemento de configuración compilado, los controladores de impresora v4 usan JavaScript para implementar API denominadas restricciones de JavaScript y el controlador de impresora puede implementar uno o varios de ellos según sea necesario. Para obtener más información, consulte la sección funciones de API de restricción de JavaScript al final de este tema.
Las restricciones de JavaScript se pueden usar para aumentar PrintCapabilities, validar PrintTickets y controlar la conversión de PrintTicket a DEVMODE y viceversa. Sin embargo, las restricciones de JavaScript tienen algunas limitaciones. La siguiente es una lista de las principales limitaciones:
Las características y opciones agregadas mediante CompletePrintCapabilities, así como las restricciones especificadas en validatePrintTicket no se muestran en la ventana preferencias de impresora de escritorio.
Las características y opciones agregadas al usar CompletePrintCapabilities no se conservan en el DEVMODE público.
Las restricciones de JavaScript no pueden acceder a los recursos de lenguaje de los archivos DLL de recursos para localizar características y opciones o parámetros agregados.
Por lo tanto, se recomienda que las restricciones de JavaScript solo se usen cuando proceda. Las características y opciones deben especificarse en los archivos GPD o PPD siempre que sea posible, y solo deben representarse restricciones complicadas en JavaScript.
Depuración de archivos JavaScript
Se admite la validación sintáctica básica de los archivos JavaScript abriendo el archivo JavaScript en el host de script basado en Windows. Para ello, haga clic con el botón derecho en el archivo JavaScript y seleccione Abrir con y elija la entrada Host de script basado en Windows en la lista. Si no se produce ningún error, JavaScript es sintácticamente válido. De lo contrario, señalará el número de línea del problema, como se muestra en la captura de pantalla siguiente.
Las herramientas de validación de JavaScript disponibles públicamente también pueden ser útiles para evaluar el estilo de los archivos JavaScript.
La depuración interactiva se puede habilitar mediante la creación de la siguiente clave del Registro:
Nombre de clave: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Print
Nombre del valor: EnableJavaScriptDebugging
Tipo: DWORD
Valor: 1
Sin embargo, dado que PrintConfig.dll se carga y descarga con frecuencia, la depuración de una aplicación que imprime no es una estrategia de prueba o depuración recomendada. En su lugar, Microsoft recomienda que los fabricantes creen una aplicación de prueba que llame a cada uno de los puntos de entrada pertinentes para las restricciones de JavaScript mediante estas API públicas: PTGetPrintCapabilities, PTConvertDevModeToPrintTicket, PTConvertPrintTicketToDevMode y PTMergeAndValidatePrintTicket.
La aplicación de prueba es suficiente para habilitar la depuración, pero también es beneficioso agregar pruebas unitarias para asegurarse de que todo el controlador controla PrintTicket, PrintCapabilities y restricciones según lo previsto. Para obtener más información sobre cómo crear pruebas unitarias en Visual Studio, consulte el tema siguiente:
Tutorial de pruebas unitarias con Visual Studio Team Test
Una vez creada la clave del Registro que se muestra en el texto anterior y se ha reiniciado el proceso de hospedaje, puede depurar el archivo de origen de JavaScript.
Es importante tener en cuenta que si el archivo de origen no se puede analizar, el depurador no se invoca y parecerá como si el entorno de depuración hubiera fallado. Si el archivo de origen no se puede analizar, consulte Host de script de Windows para obtener más información sobre cómo continuar.
Si no hay errores y el archivo de origen se analiza correctamente, depure el archivo de origen de la siguiente manera:
Instalación de Microsoft Visual Studio 2012 o posterior en la máquina de prueba
Creación de una cola de impresión mediante el controlador que tiene las restricciones código JavaScript
Establezca esta cola de impresión como valor predeterminado.
Inicie la aplicación de prueba o una aplicación que imprima e inicie un escenario que hará que se invoquen restricciones de JavaScript. La aplicación debe llamar a las API PrintTicket/PrintCapabilities para interrumpir las restricciones de JavaScript; las aplicaciones anteriores, como el Bloc de notas, no llaman a estas API, pero la aplicación XPS Viewer sí. Microsoft recomienda usar una aplicación de prueba aquí, ya que los escenarios se pueden aislar y reproducir más fácilmente.
En este momento, el "Depurador Just-In-Time" de Visual Studio aparecerá indicando "Se produjo una excepción no controlada en <la aplicación>".
Inicio de una nueva instancia de Visual Studio 2012 o posterior
Elija Depurar, Asociar al proceso.
En el cuadro de diálogo Asociar a proceso, asegúrese de que Asociar a: esté establecido en Código de script.
Ahora elija la aplicación de prueba o impresión y, por último, elija Asociar.
Haga clic en "Interrumpir todo"
Ahora vuelva al cuadro de diálogo "Depurador Just-In-Time" de Visual Studio y haga clic en "No"
Visual Studio entrará en el depurador en la ubicación a la que llama la prueba actual. Ahora puede depurar el código normalmente.
API de restricción de JavaScript
En esta sección se especifican las funciones que sirven como puntos de entrada de API para su uso en el archivo de restricción de JavaScript. Estas son las funciones:
validatePrintTicket
completePrintCapabilities
convertDevModeToPrintTicket
convertPrintTicketToDevMode
Función validatePrintTicket
Se llama a esta API para validar que un objeto PrintTicket es válido para una impresora determinada. Esto es análogo a la API IPrintOemPrintTicketProvider::ValidatePrintTicket.
Sintaxis validatePrintTicket
function validatePrintTicket(printTicket, scriptContext)
Parámetros validatePrintTicket
printTicket
[in] [out] Objeto IPrintSchemaTicket que se va a validar.
scriptContext
[in] Objeto IPrinterScriptContext que proporciona acceso al contenedor de propiedades del controlador, al contenedor de propiedades de cola y al contenedor de propiedades de usuario.
Valor devuelto validatePrintTicket
| Valor devuelto | Descripción |
|---|---|
| 0 | Indica que el parámetro printTicket no era válido y no se pudo corregir. Equivalente a E_PRINTTICKET_FORMAT. |
| 1 | Indica que el parámetro printTicket es un PrintTicket válido para esta impresora. Equivalente a S_PT_NO_CONFLICT. |
| 2 | Indica que se modificó el parámetro printTicket para que sea válido. Equivalente a S_PT_CONFLICT_RESOLVED. |
Función completePrintCapabilities
Se llama a esta API para permitir que se modifique el objeto PrintCapabilities. Esto se debe usar para las características condicionales (por ejemplo, solo se admite en papel fotográfico) o para representar características que, de lo contrario, no se pueden generar mediante un archivo GPD o PPD (por ejemplo, definiciones de características anidadas). Esto es análogo a la API IPrintOemPrintTicketProvider::CompletePrintCapabilities.
Sintaxis completePrintCapabilities
function completePrintCapabilities(printTicket, scriptContext, printCapabilities)
Parámetros completePrintCapabilities
printTicket
[in] Entrada del objeto IPrintSchemaTicket para restringir el documento PrintCapabilities generado.
scriptContext
[in] Objeto IPrinterScriptContext que proporciona acceso al contenedor de propiedades del controlador, al contenedor de propiedades de cola y al contenedor de propiedades de usuario.
printCapabilities
[in] [out] Objeto IPrintSchemaCapabilities que representa el objeto PrintCapabilities base generado por el módulo de configuración.
Valor devuelto completePrintCapabilities
Ninguno.
Función convertDevModeToPrintTicket
Se llama a esta API para convertir valores del contenedor de propiedades DEVMODE en un PrintTicket. Esto es análogo a la API IPrintOemPrintTicketProvider::ConvertDevModeToPrintTicket, salvo que esta implementación encapsula la sección privada del DEVMODE en un objeto IPrinterScriptablePropertyBag y no permite acceso a la sección pública del DEVMODE.
Sintaxis convertDevModeToPrintTicket
function convertDevModeToPrintTicket(devModeProperties, scriptContext, printTicket)
Parámetros convertDevModeToPrintTicket
- devModeProperties
[in] Objeto IPrinterScriptablePropertyBag que representa el contenedor de propiedades DEVMODE.
scriptContext
[in] Objeto IPrinterScriptContext que proporciona acceso al contenedor de propiedades del controlador, al contenedor de propiedades de cola y al contenedor de propiedades de usuario.
printTicket
[in] [out] Objeto IPrintSchemaTicket que representa printTicket.
Valor devuelto convertDevModeToPrintTicket
Ninguno.
Función convertPrintTicketToDevMode
Se llama a esta API para convertir valores de un PrintTicket en el contenedor de propiedades DEVMODE. Esto es análogo a la API IPrintOemPrintTicketProvider::ConvertPrintTicketToDevMode, salvo que esta implementación encapsula la sección privada del DEVMODE en un objeto IPrinterScriptablePropertyBag y no permite acceso a la sección pública del DEVMODE.
Sintaxis convertPrintTicketToDevMode
function convertPrintTicketToDevMode(printTicket, scriptContext, devModeProperties)
Parámetros convertPrintTicketToDevMode
printTicket
[in] Objeto IPrintSchemaTicket que representa el PrintTicket que se va a convertir.
scriptContext
[in] Objeto IPrinterScriptContext que proporciona acceso al contenedor de propiedades del controlador, al contenedor de propiedades de cola y al contenedor de propiedades de usuario.
devModeProperties
[in][out] Objeto IPrinterScriptablePropertyBag que representa el contenedor de propiedades DEVMODE.
Valor devuelto convertPrintTicketToDevMode
Ninguno.
Procedimientos recomendados de restricciones
El cuadro de diálogo de impresión de Windows 8 y la experiencia de preferencias de impresión solo admiten un subconjunto del espacio de nombres de palabras clave del esquema de impresión. Como resultado, Microsoft no recomienda usar restricciones entre las características que se admiten en el cuadro de diálogo de impresión de Windows 8 o la interfaz de usuario de preferencias de impresión y características que no están en esa interfaz de usuario, ya que los usuarios no tendrán la oportunidad de resolver estas restricciones.
Por ejemplo, si la opción PageMediaType denominada Photo está restringida para que solo funcione con un valor PageResolution de 1200 ppp, los usuarios nunca podrán elegir el tipo de medio Photo. En los casos como este, es mejor que coincida con la intención del usuario (medios fotográficos) y ajustar cualquier configuración necesaria para que esto ocurra. Estos ajustes se pueden realizar en el código de restricción de JavaScript.
Si un controlador no utiliza restricciones de JavaScript, no hay ningún requisito de que se proporcione un archivo. Si un controlador utiliza restricciones de JavaScript solo para un subconjunto de los puntos de entrada (por ejemplo, validatePrintTicket), los demás puntos de entrada deben omitirse completamente del archivo JavaScript.