Ir al contenido principal

Referencias de recursos

Las "Referencias de recursos" te permiten usar archivos externos en Blueprints

Las etapas de Blueprint como installPlugin o installTheme requieren una ubicación del plugin o tema que se va a instalar.

Esa ubicación puede definirse como un recurso URL del archivo .zip que contiene el tema o plugin. También puede definirse como un recurso wordpress.org/plugins o wordpress.org/themes para esos plugins/temas publicados en los directorios oficiales de WordPress.

Están disponibles las siguientes referencias de recursos:

URLReference​

El recurso URLReference se usa para referenciar archivos almacenados en un servidor remoto. El recurso URLReference se define así:

type URLReference = {
	resource: 'url';
	url: string;
};

Para usar el recurso URLReference, debes proporcionar la URL del archivo. Por ejemplo, para referenciar un archivo llamado "index.html" almacenado en un servidor remoto, puedes crear un URLReference así:

{
	"resource": "url",
	"url": "https://example.com/index.html"
}

El recurso url funciona con etapas de Blueprint como installPlugin o installTheme. Estas etapas requieren un ResourceType para definir la ubicación del plugin o tema que se instalará.

Con "resource": "url" podemos definir la ubicación de un .zip que contiene el plugin/tema. Usa esto para artifacts ZIP ya creados y alojados en una URL públicamente accesible que no requiera autenticación, como un asset de release. Las URL de descarga directa de artifacts de CI pueden funcionar, pero a menudo son de corta duración o están restringidas.

Para código fuente almacenado en un repositorio Git, prefiere git:directory. Puede obtener un subdirectorio del repositorio desde una rama, etiqueta o commit sin requerir un archivo ZIP.

Antes de usar un recurso url, verifica que la URL:

  • Descargue el archivo directamente. No debe devolver una página HTML, aviso de redirección, página de inicio de sesión, visor de archivo de repositorio o página de error de proxy.
  • Esté disponible sin cookies, autenticación, VPN o una sesión temporal del navegador.
  • Envíe encabezados CORS que permitan que Playground la obtenga.
  • Apunte al tipo de archivo esperado. installPlugin e installTheme necesitan un archivo ZIP de plugin o tema, a menos que uses otro tipo de recurso.
  • Permanezca disponible. Las URL temporales de túnel, los assets de release en borrador y los artifacts de CI de corta duración pueden expirar.
  • Sea un archivo ZIP real cuando la etapa espere un ZIP. Las descargas muy pequeñas a menudo significan que el servidor devolvió una página HTML de error en lugar del archivo.

Para código fuente de GitHub, no apuntes url a una página del repositorio ni a un ZIP generado desde una rama cuando puedes usar git:directory. Usa url para artifacts ZIP creados y git:directory para directorios de código fuente.

GitDirectoryReference​

El recurso GitDirectoryReference se usa para referenciar un directorio dentro de un repositorio Git. Esto es útil cuando un plugin o tema vive en una subcarpeta de un repositorio, o cuando quieres instalar desde una rama, etiqueta o commit específico.

type GitDirectoryReference = {
	resource: 'git:directory';
	url: string; // Repository URL (https://, ssh git@..., etc.)
	path?: string; // Optional subdirectory inside the repository
	ref?: string; // Branch, tag, or commit SHA (defaults to HEAD)
	refType?: 'branch' | 'tag' | 'commit'; // Hint for resolving the ref
	'.git'?: boolean; // Experimental: include a .git directory with fetched metadata
};

Ejemplo:

{
	"step": "installPlugin",
	"pluginData": {
		"resource": "git:directory",
		"url": "https://github.com/WordPress/block-development-examples",
		"ref": "HEAD",
		"path": "plugins/data-basics-59c8f8"
	},
	"options": {
		"activate": true,
		"targetFolderName": "data-basics"
	}
}

Notas:

  • Al usar un nombre de rama o etiqueta para ref, debes especificar refType (por ejemplo, "refType": "branch"). Sin eso, solo HEAD se resuelve de forma fiable.
  • Playground detecta automáticamente proveedores como GitHub y GitLab.
  • Las URL de repositorio pueden incluir u omitir el sufijo final .git. Las barras finales extra se ignoran.
  • Maneja solicitudes con proxy CORS y checkouts dispersos, por lo que puedes usar URL que apuntan a subdirectorios o ramas específicos.
  • Este recurso puede usarse con etapas como installPlugin e installTheme.
  • Define ".git": true para incluir una carpeta .git que contenga packfiles y refs, de modo que herramientas compatibles con Git puedan detectar el checkout. Actualmente esto refleja un clon superficial del ref seleccionado.
  • El nombre de la carpeta se deriva de la URL por defecto (por ejemplo, https-github-com-WordPress-block-development-examples-HEAD-at-plugins-data-basics-59c8f8). Usa options.targetFolderName en la etapa para sobrescribirlo, como se muestra en el ejemplo anterior.

CoreThemeReference​

El recurso CoreThemeReference se usa para referenciar temas principales de WordPress. El recurso CoreThemeReference se define así:

type CoreThemeReference = {
	resource: 'wordpress.org/themes';
	slug: string;
	version?: string;
};

Para usar el recurso CoreThemeReference, debes proporcionar el slug del tema. Por ejemplo, para referenciar el tema "Twenty Twenty-One", puedes crear un CoreThemeReference así:

{
	"resource": "wordpress.org/themes",
	"slug": "twentytwentyone"
}

CorePluginReference​

El recurso CorePluginReference se usa para referenciar plugins principales de WordPress. El recurso CorePluginReference se define así:

type CorePluginReference = {
	resource: 'wordpress.org/plugins';
	slug: string;
	version?: string;
};

Para usar el recurso CorePluginReference, debes proporcionar el slug del plugin. Por ejemplo, para referenciar el plugin "Akismet", puedes crear un CorePluginReference así:

{
	"resource": "wordpress.org/plugins",
	"slug": "akismet"
}

VFSReference​

El recurso VFSReference se usa para referenciar archivos almacenados en un sistema de archivos virtual (VFS). El VFS es un sistema de archivos almacenado en memoria y puede usarse para almacenar archivos que no forman parte del sistema de archivos del sistema operativo. El recurso VFSReference se define así:

type VFSReference = {
	resource: 'vfs';
	path: string;
};

Para usar el recurso VFSReference, debes proporcionar la ruta al archivo en el VFS. Por ejemplo, para referenciar un archivo llamado "index.html" almacenado en la raíz del VFS, puedes crear un VFSReference así:

{
	"resource": "vfs",
	"path": "/index.html"
}

LiteralReference​

El recurso LiteralReference se usa para referenciar archivos almacenados como literales en el código. El recurso LiteralReference se define así:

type LiteralReference = {
	resource: 'literal';
	name: string;
	contents: string | Uint8Array;
};

Para usar el recurso LiteralReference, debes proporcionar el nombre del archivo y su contenido. Por ejemplo, para referenciar un archivo llamado "index.html" que contiene el texto "Hello, World!", puedes crear un LiteralReference así:

{
	"resource": "literal",
	"name": "index.html",
	"contents": "Hello, World!"
}

BundledReference​

El recurso BundledReference se usa para referenciar archivos incluidos en el propio Blueprint. Esto es especialmente útil para crear paquetes de Blueprint autocontenidos que incluyen todos los recursos necesarios. El recurso BundledReference se define así:

type BundledReference = {
	resource: 'bundled';
	path: string;
};

Para usar BundledReference, debes proporcionar la ruta relativa al archivo dentro del paquete. Por ejemplo, para referenciar un archivo llamado "plugin.php" incluido con el Blueprint, puedes crear un BundledReference así:

{
	"resource": "bundled",
	"path": "plugin.php"
}

Los paquetes de Blueprint pueden distribuirse en varios formatos, incluidos:

  • Archivos ZIP con un archivo blueprint.json de nivel superior
  • Directorios que contienen un archivo blueprint.json y recursos relacionados
  • URL remotas donde el Blueprint y sus recursos están alojados juntos

Para más información sobre paquetes de Blueprint, consulta la documentación de Paquetes de Blueprint.