Pular para o conteúdo principal

Referências de recursos

"Referências de recursos" permitem usar arquivos externos em Blueprints.

Etapas de Blueprint como installPlugin ou installTheme exigem a localização do plugin ou tema que será instalado.

Essa localização pode ser definida como um recurso URL do arquivo .zip que contém o tema ou plugin. Ela também pode ser definida como um recurso wordpress.org/plugins ou wordpress.org/themes para plugins/temas publicados nos diretórios oficiais do WordPress.

As seguintes referências de recursos estão disponíveis:

URLReference​

O recurso URLReference é usado para referenciar arquivos armazenados em um servidor remoto. O recurso URLReference é definido assim:

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

Para usar o recurso URLReference, você precisa fornecer a URL do arquivo. Por exemplo, para referenciar um arquivo chamado "index.html" armazenado em um servidor remoto, crie um URLReference assim:

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

O recurso url funciona com etapas de Blueprint como installPlugin ou installTheme. Essas etapas exigem um ResourceType para definir a localização do plugin ou tema a instalar.

Com "resource": "url", podemos definir a localização de um .zip que contém o plugin/tema. Use isso para artefatos ZIP já criados e hospedados em uma URL publicamente acessível que não exija autenticação, como um asset de release. URLs de download direto de artefatos de CI podem funcionar, mas costumam ter duração curta ou acesso restrito.

Para código-fonte armazenado em um repositório Git, prefira git:directory. Ele pode buscar um subdiretório de repositório a partir de um branch, tag ou commit sem exigir um arquivo ZIP.

Antes de usar um recurso url, verifique se a URL:

  • Baixa o arquivo diretamente. Ela não deve retornar uma página HTML, aviso de redirecionamento, página de login, visualizador de arquivo de repositório ou página de erro de proxy.
  • Está disponível sem cookies, autenticação, VPN ou sessão temporária do navegador.
  • Envia cabeçalhos CORS que permitem que o Playground a busque.
  • Aponta para o tipo de arquivo esperado. installPlugin e installTheme precisam de um arquivo ZIP de plugin ou tema, a menos que você use outro tipo de recurso.
  • Permanecerá disponível. URLs temporárias de túnel, assets de release em rascunho e artefatos de CI de curta duração podem expirar.
  • É um arquivo ZIP real quando a etapa espera um ZIP. Downloads muito pequenos costumam significar que o servidor retornou uma página HTML de erro em vez do arquivo.

Para código-fonte no GitHub, não aponte url para uma página de repositório ou para um ZIP gerado de um branch quando você puder usar git:directory. Use url para artefatos ZIP criados e git:directory para diretórios de código-fonte.

GitDirectoryReference​

O recurso GitDirectoryReference é usado para referenciar um diretório dentro de um repositório Git. Isso é útil quando um plugin ou tema fica em uma subpasta de um repositório, ou quando você quer instalar a partir de um branch, tag ou 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
};

Exemplo:

{
	"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"
	}
}

Observações:

  • Ao usar um nome de branch ou tag em ref, você deve especificar refType (por exemplo, "refType": "branch"). Sem isso, somente HEAD é resolvido de forma confiável.
  • O Playground detecta automaticamente provedores como GitHub e GitLab.
  • URLs de repositório podem incluir ou omitir o sufixo .git final. Barras finais extras são ignoradas.
  • Ele lida com buscas via proxy CORS e checkouts esparsos, então você pode usar URLs que apontam para subdiretórios ou branches específicos.
  • Esse recurso pode ser usado com etapas como installPlugin e installTheme.
  • Defina ".git": true para incluir uma pasta .git contendo packfiles e refs, para que ferramentas cientes de Git possam detectar o checkout. Atualmente, isso espelha um clone raso do ref selecionado.
  • O nome da pasta é derivado da URL por padrão (por exemplo, https-github-com-WordPress-block-development-examples-HEAD-at-plugins-data-basics-59c8f8). Use options.targetFolderName na etapa para sobrescrevê-lo, como mostrado no exemplo acima.

CoreThemeReference​

O recurso CoreThemeReference é usado para referenciar temas principais do WordPress. O recurso CoreThemeReference é definido assim:

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

Para usar o recurso CoreThemeReference, você precisa fornecer o slug do tema. Por exemplo, para referenciar o tema "Twenty Twenty-One", crie um CoreThemeReference assim:

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

CorePluginReference​

O recurso CorePluginReference é usado para referenciar plugins principais do WordPress. O recurso CorePluginReference é definido assim:

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

Para usar o recurso CorePluginReference, você precisa fornecer o slug do plugin. Por exemplo, para referenciar o plugin "Akismet", crie um CorePluginReference assim:

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

VFSReference​

O recurso VFSReference é usado para referenciar arquivos armazenados em um sistema de arquivos virtual (VFS). O VFS é um sistema de arquivos armazenado em memória e pode ser usado para armazenar arquivos que não fazem parte do sistema de arquivos do sistema operacional. O recurso VFSReference é definido assim:

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

Para usar o recurso VFSReference, você precisa fornecer o caminho para o arquivo no VFS. Por exemplo, para referenciar um arquivo chamado "index.html" armazenado na raiz do VFS, crie um VFSReference assim:

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

LiteralReference​

O recurso LiteralReference é usado para referenciar arquivos armazenados como literais no código. O recurso LiteralReference é definido assim:

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

Para usar o recurso LiteralReference, você precisa fornecer o nome do arquivo e o conteúdo dele. Por exemplo, para referenciar um arquivo chamado "index.html" que contém o texto "Hello, World!", crie um LiteralReference assim:

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

BundledReference​

O recurso BundledReference é usado para referenciar arquivos empacotados com o próprio Blueprint. Isso é especialmente útil para criar pacotes de Blueprint autocontidos que incluem todos os recursos necessários. O recurso BundledReference é definido assim:

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

Para usar o BundledReference, você precisa fornecer o caminho relativo para o arquivo dentro do pacote. Por exemplo, para referenciar um arquivo chamado "plugin.php" que está empacotado com o Blueprint, crie um BundledReference assim:

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

Pacotes de Blueprint podem ser distribuídos em vários formatos, incluindo:

  • Arquivos ZIP com um arquivo blueprint.json no nível superior
  • Diretórios contendo um arquivo blueprint.json e recursos relacionados
  • URLs remotas onde o Blueprint e seus recursos estão hospedados juntos

Para mais informações sobre pacotes de Blueprint, consulte a documentação de Pacotes de Blueprint.