Saltar al contenido
P4 Software P4 Software / BarcoderX Español

Agrega esta documentación a Claude

Hazle preguntas a Claude sobre esta documentación. Claude lee las páginas publicadas y te enlaza a ellas. Copia esta dirección:

https://p4-software.opendocs.page/mcp

En claude.ai o Claude Desktop: abre Configuración, luego Conectores, elige Agregar conector personalizado y pega la dirección.

En Claude Code, ejecuta:

claude mcp add --transport http docs https://p4-software.opendocs.page/mcp

El formato de plantilla de etiqueta

El formato de plantilla de etiqueta

Aplica a: BarcoderX Basic y Ultimate

Estado: Construido, aún sin publicar. El código que lee y escribe una plantilla en JSON existe y está probado. Es una biblioteca dentro del motor, que todavía se está construyendo. No hay ningún paquete publicado, no hay una interfaz pública que usted pueda llamar para leer o escribir una plantilla directamente, y el motor con licencia será la única vía pública para producir salida. Esta página describe el formato y lo que hacen el lector y el escritor. Los nombres de los miembros son nombres de trabajo hasta que se publique el formato. Todo lo que se indica como "planificado" todavía no se puede usar.

Una plantilla es un archivo de texto que describe una etiqueta. Esta página muestra cómo es una plantilla, qué ocurre cuando BarcoderX lee una y la escribe, los límites, y lo que debe hacer un programa que aloja BarcoderX para mantenerse seguro. Para las ideas que hay detrás de las plantillas, consulte Plantillas y datos.

La plantilla más pequeña

Esta plantilla tiene un texto, un cuadro y un código de barras EAN-13. Es real: el lector la acepta, y una prueba la lee.

{
  "schemaVersion": 1,
  "page": { "unit": "mm", "width": 100, "height": 50, "dpi": 203 },
  "elements": [
    { "type": "text", "id": "title", "x": 4, "y": 4, "width": 60, "height": 10,
      "content": { "text": "Hello" }, "font": { "size": 14, "bold": true } },
    { "type": "box", "id": "frame", "x": 2, "y": 2, "width": 96, "height": 46, "stroke": 0.4 },
    { "type": "barcode", "id": "code", "symbology": "ean-13", "x": 4, "y": 20, "width": 60, "height": 20,
      "content": { "text": "9501101531000" } }
  ]
}

Qué dice:

  • schemaVersion es la versión del formato. Por ahora es 1.
  • page da la unidad (aquí milímetros), el ancho y el alto de la etiqueta en esa unidad, y la resolución en puntos por pulgada. unit y dpi se pueden omitir. Entonces significan milímetros y 203.
  • elements es la lista de lo que hay en la etiqueta, del elemento de más abajo al de más arriba. Cada uno tiene un type y un id.
  • El texto tiene un contenido fijo, "Hello", en una fuente en negrita de 14 puntos. El cuadro tiene un borde de 0.4 mm de ancho. El código de barras tiene la simbología ean-13, el nombre de la simbología en el registro.
  • El número del código de barras, 9501101531000, es el EAN-13 impreso en la Figura 5-11, en la página 326, de las GS1 General Specifications, versión 26.0. Su último dígito, 0, es su dígito verificador.

Las partes de una plantilla

La parte superior del archivo

MiembroSignificado
schemaVersionObligatorio. Un número entero, la versión del formato. Por ahora es 1.
minReaderVersionLa versión más antigua del formato que necesita un lector para leer este archivo. Si falta, es igual a schemaVersion.
$schemaOpcional. La dirección web del esquema del formato. BarcoderX nunca la descarga. El escritor no agrega ninguna hasta que la dirección sea definitiva.
nameOpcional. Un nombre para mostrar.
pageObligatorio. La página, que se describe más abajo.
elementsObligatorio. La lista de elementos. El primero está en el fondo.
fields, variables, counters, masks, settingsOpcionales. Los campos, las variables, los contadores y las máscaras que usa la etiqueta, y sus ajustes. Se leen y se comprueban. Usarlos para armar una etiqueta está planificado.

La página

MiembroSignificado
unitLa unidad de cada longitud del archivo: in, mm, cm, dot, pt, pica, mil, twip o um. El valor predeterminado es mm.
width, heightEl tamaño de la etiqueta, en la unidad.
dpiPuntos por pulgada, un número entero de 96 a 1,200. El valor predeterminado es 203.
orientation0, 90, 180 o 270 grados.
colorModemono, gray o color.
media, layoutEl tipo de material de la etiqueta, y las columnas y filas de etiquetas en un rollo o una hoja.

Los elementos

Hoy se pueden leer cinco tipos de elemento: text, barcode, line, box y ellipse. Los tipos imagen, cuadrícula, repetidor, RFID y comando sin procesar están planificados. Una plantilla que use uno de ellos se rechaza con el código BX1113 hasta que se admita.

Cada elemento empieza con type y luego id. El type debe ser el primer miembro. El id debe ser distinto en cada elemento. Después siguen la posición y el tamaño (x, y, width, height, en la unidad de la página) y, donde el formato los tiene, rotation, name, anchor, printWhen, output, locked, locks, group, printSide, computed y comment.

TipoMiembros principales
textcontent, font (family, asset, size, bold, italic, underline, strikeout), color, background, box, align, valign, lineSpacing, charSpacing, sizing. Consulte Texto en una etiqueta.
barcodesymbology, content, xDimension, xDimensionUnit (page o dot), sizing (fixed o fit), barHeight, barWidthAdjust, quietZone, checkDigit, humanReadable (position: below, above u off), options, color, background. Consulte Códigos de barras.
linex2, y2, stroke, color
boxstroke, color, fill, radius
ellipsestroke, color, fill

Contenido. Un texto o un código de barras obtiene su contenido de exactamente uno de estos tres orígenes: text (texto fijo), field (un campo de sus datos) o expr (una expresión). Un código de barras también puede indicar cómo se convierte el contenido en bytes, con encoding (text, hex o base64) y escapes (none o tilde). Leer el contenido desde un campo o una expresión para armar una etiqueta está planificado.

Cómo se escriben los valores

  • Las longitudes son números sencillos en la unidad de la página. Los tamaños de fuente están en puntos. Los ángulos están en grados, en sentido horario.
  • Los colores son #RRGGBB o #RRGGBBAA, en mayúsculas o minúsculas.
  • Las opciones, como align, son palabras entre comillas, nunca números.
  • El ancho de un borde o un radio es un número, o una lista de cuatro números: arriba, derecha, abajo e izquierda para los lados, y arriba a la izquierda, arriba a la derecha, abajo a la derecha y abajo a la izquierda para las esquinas.
  • Un valor null en un miembro opcional significa que el miembro no está.
  • El asset de una fuente es un identificador con la forma xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Leer una plantilla

BarcoderX lee una plantilla desde texto, desde bytes o desde un flujo. Una plantilla que no es válida se rechaza con uno o más códigos de diagnóstico, y no se crea ningún diseño a partir de ella. Cuando el problema está en el archivo, el mensaje también dice dónde: una línea y una posición. Ambas empiezan en 1 y cuentan caracteres, no bytes.

El lector rechaza:

  • un archivo que supera el límite de tamaño, lo cual detecta antes de analizar nada (BX1100);
  • texto que no es UTF-8, y un archivo que empieza con una marca de orden de bytes (BX1101, BX1102);
  • JSON dañado: falta una coma o un corchete, un comentario, una coma final, un archivo que termina antes de tiempo (BX1103);
  • un anidamiento demasiado profundo (BX1104);
  • un miembro escrito dos veces en el mismo objeto, también dentro de las opciones y de los datos de extensión (BX1105);
  • un nombre o un texto demasiado largo, y un número demasiado grande o escrito como NaN (BX1106, BX1108, BX1109, BX1103);
  • la mitad de un código de carácter, como \ud800 (BX1107);
  • un elemento sin type, con un type que no es una palabra, que no es el primero o que no es un tipo conocido (BX1111 a BX1114);
  • un valor de otro tipo, como texto donde va un número, y un color o un identificador mal escrito (BX1115 a BX1124);
  • un objeto de contenido sin ningún origen, o con más de uno (BX1125);
  • una plantilla que necesita una versión más reciente de BarcoderX (BX1128).

Cuando el archivo se lee, las reglas del modelo comprueban el diseño: ids que se usan dos veces, números fuera de rango y los límites de más abajo (BX1001 a BX1027). Un solo problema de gravedad Error significa que no se devuelve ningún diseño. La lista completa de códigos, con sus textos en español y en inglés, está en Códigos de diagnóstico.

Qué ocurre con los miembros que BarcoderX no conoce

Qué esQué ocurre
Un miembro que el formato no define, en cualquier lugar salvo dentro de un objeto de contenidoSe conserva y se vuelve a escribir. Un archivo más nuevo no pierde nada cuando lo edita una herramienta más antigua. Una aplicación anfitriona puede guardar sus propios datos en miembros cuyos nombres empiezan con x- y un identificador del anfitrión.
Un miembro que el formato no define, dentro de un objeto de contenido (el objeto con text, field o expr)Es un error (BX1126). Un objeto de contenido solo contiene sus propios miembros.
Una opción que no es una palabra conocida, como "align": "left"Es un error (BX1121). No se ignora.
Un type de elemento que no se conoceEs un error (BX1113).
Un archivo que necesita un lector más recienteUn archivo cuyo minReaderVersion es mayor que la versión del lector se rechaza con BX1128, y nada se lee a medias. Un archivo que dice schemaVersion 2 y minReaderVersion 1 se lee como versión 1.

Una opción desconocida es un error porque un lector no puede descartarla y aun así hacer que el elemento tenga sentido. Por eso, un formato más nuevo que agregue una opción que cambie la salida también establece minReaderVersion, y un lector más antiguo rechaza el archivo con un mensaje claro.

Una versión 0 o menor no es una versión (BX1127).

Escribir una plantilla y la forma canónica

BarcoderX escribe una plantilla en una sola forma fija, llamada forma canónica. El mismo diseño da exactamente el mismo texto en todas las computadoras, en Windows x64, Linux x64 y Linux arm64. Si lee un archivo canónico y lo vuelve a escribir, obtiene los mismos bytes.

Las reglas de la forma canónica:

  • Orden. Un elemento empieza con type e id. Los demás miembros siguen en el orden del formato. Los miembros que BarcoderX no conoce van al final, en orden alfabético. Las claves de computed, de options y de cada objeto de extensión están en orden alfabético.
  • Los valores predeterminados se omiten. No se escribe un miembro cuyo valor es el predeterminado. La excepción está en la página: unit, dpi, width y height siempre se escriben, porque determinan qué significa cada número del archivo.
  • Los números se escriben en la forma más corta que se vuelve a leer con exactitud. La cultura de la computadora no interviene.
  • El texto es UTF-8. No hay marca de orden de bytes. Los únicos caracteres que se escapan son las comillas, la barra invertida, los caracteres de control (U+0000 a U+001F y U+007F a U+009F), U+2028 y U+2029. Todos los demás caracteres se escriben tal cual, incluidos <, >, & y '. La única excepción es la mitad de un par de códigos sustitutos sin la otra mitad, que solo puede darse en un diseño armado en código: se escribe como U+FFFD.
  • Presentación. Sangría de dos espacios, un salto de línea (\n) al final de cada línea y un salto de línea al final del archivo.
  • Detalles menores. Los colores se escriben en mayúsculas y los identificadores de recurso en minúsculas. Cuatro valores iguales de lados se escriben como un solo número.
  • Los valores de extensión se escriben compactos, en una sola línea.
  • $schema se escribe solo si el diseño lo tiene. El escritor nunca agrega uno.

Esta es la forma canónica de la plantilla más pequeña de arriba, exactamente como la produce el escritor:

{
  "schemaVersion": 1,
  "page": {
    "unit": "mm",
    "width": 100,
    "height": 50,
    "dpi": 203
  },
  "elements": [
    {
      "type": "text",
      "id": "title",
      "x": 4,
      "y": 4,
      "width": 60,
      "height": 10,
      "content": {
        "text": "Hello"
      },
      "font": {
        "size": 14,
        "bold": true
      }
    },
    {
      "type": "box",
      "id": "frame",
      "x": 2,
      "y": 2,
      "width": 96,
      "height": 46,
      "stroke": 0.4
    },
    {
      "type": "barcode",
      "id": "code",
      "x": 4,
      "y": 20,
      "width": 60,
      "height": 20,
      "symbology": "ean-13",
      "content": {
        "text": "9501101531000"
      }
    }
  ]
}

Un diseño que se leyó de una plantilla se puede escribir y volver a leer con los mismos límites. El escritor rechaza un diseño cuyo texto canónico sería mayor que el límite de tamaño (BX1130), y omite un valor de extensión que el lector rechazaría. Un miembro de extensión cuyo nombre es también el nombre de un miembro que define el formato se omite, para que no pueda ocultar al verdadero.

Límites

BarcoderX comprueba cada límite antes de usar la memoria que ese límite protege.

LímiteValor
Tamaño de un archivo de plantilla2 MB. El programa que aloja BarcoderX puede aumentarlo, nunca por encima de 10 MB.
Anidamiento64 niveles. Es fijo.
Un texto1,000,000 de caracteres
El nombre de un miembro128 caracteres
Un número1,024 caracteres
Elementos en una plantilla2,000
Campos, variables, contadores o máscaras, cada lista1,000
Propiedades calculadas en un elemento64
Opciones de un código de barras64
Datos de extensión en la plantilla, la página o un elemento, todos los miembros x- juntos4 KB
Lado más largo de una etiqueta1,000 mm
Hallazgos que se listan en un resultado200. Después de eso, un mensaje (BX1026) dice que el diseño no se comprobó por completo.

Los valores del nombre de un miembro, un número, las cuatro listas, las propiedades calculadas, las opciones y los hallazgos son primeras elecciones de quienes construyen BarcoderX. Todavía no se han confirmado y pueden cambiar antes de la primera versión.

Notas para desarrolladores que alojan BarcoderX

Estos puntos importan cuando su programa recibe plantillas de otras personas o muestra lo que informa BarcoderX.

  1. El texto canónico no está escapado para HTML. <, >, & y ' se escriben tal cual. Codifique el texto para HTML antes de ponerlo en una página, y para un atributo antes de ponerlo en un atributo entre comillas. Nunca lo ponga dentro de un bloque de script de HTML, a menos que antes escriba cada < que contenga como \u003C. Lo mismo vale para el texto sin procesar de un valor de extensión o de opción que conserva el motor.
  2. Un mensaje puede contener palabras de la plantilla. El id del elemento, los nombres de los campos, las variables, los contadores y las máscaras declarados, y los nombres de las propiedades calculadas aparecen en algunos diagnósticos (los códigos BX1001 a BX1027), cada uno con 128 caracteres como máximo. Pueden contener cualquier cosa que una persona pueda escribir, incluidos saltos de línea. Insértelos en una página como texto, nunca como marcado. Esto vale para todo el mensaje: el id del elemento y la ubicación que lo acompañan, cada valor y el texto terminado. Muestre los ids y los nombres en un contexto de dirección aislado (en HTML, un elemento <bdi>), porque los caracteres que invierten la dirección del texto, como U+202E, no cambian con la codificación HTML. Antes de escribir un mensaje en un registro, reemplace los retornos de carro, los saltos de línea, los demás caracteres de control y los caracteres de dirección U+061C, U+200E, U+200F, U+202A a U+202E y U+2066 a U+2069, para que una plantilla no pueda falsificar una línea de su registro. Los mensajes del propio lector (BX1100 a BX1130) nunca contienen texto del archivo. Los códigos de composición del texto pueden llevar el nombre de una fuente que vino de una plantilla (consulte Texto en una etiqueta), así que trátelos de la misma manera.
  3. Limite cuántas plantillas lee al mismo tiempo. La lectura usa memoria en proporción al tamaño del archivo. En la revisión de seguridad, una lectura reservó unos 100 MB con el límite predeterminado de 2 MB, y alrededor de medio gigabyte, hasta unos 0.6 GB, con el tope de 10 MB. Una lectura también puede usar hasta aproximadamente medio segundo de tiempo de procesador con el límite predeterminado, y algunos segundos con el tope. Mantenga el límite de tamaño tan bajo como lo permitan sus etiquetas, limite el tamaño de las solicitudes que acepta y limite el número de lecturas que se ejecutan a la vez. El programa que llama al lector puede cancelar una lectura.
  4. Compruebe que puede guardar una plantilla cuando la acepta. La forma canónica puede ser más grande que el archivo del que proviene, por su sangría, así que una plantilla que se lee dentro del límite de tamaño puede ser demasiado grande para volver a escribirse (BX1130). Si su programa guarda la forma canónica, escriba la plantilla en cuanto se suba y recházela ahí con BX1130, para no aceptar nunca una plantilla que no pueda guardar. Escriba con los mismos límites que tendrá el lector que vuelva a leer el texto: un valor que supera un límite más estricto se omite, y hoy nada lo informa.

Qué está planificado

  • Un archivo de esquema JSON publicado, para que pueda comprobar una plantilla antes de cargarla.
  • XML como equivalente exacto de JSON.
  • La actualización de plantillas escritas en versiones anteriores del formato.
  • Los tipos de elemento que todavía no se leen, y el uso de campos, expresiones, contadores y máscaras para armar etiquetas.

BarcoderX es un producto de P4 Software.

¿Te resultó útil esta página?