Como adicionar uma seleção de imagem em seu bloco personalizado WordPress Gutenberg

Este post é para você que está criando um bloco Gutenberg personalizado e precisa de uma maneira de selecionar ou fazer upload de uma imagem da Biblioteca de Mídia. A maioria dos outros tipos de campo, como caixas de seleção, entradas de texto ou seletores de cores, são muito fáceis de adicionar, mas um carregador de mídia requer um pouco mais de código. Criaremos um componente Inspector que será responsável por renderizar um botão para abrir a Biblioteca de Mídia, selecionar uma imagem e, opcionalmente, removê-la ou alterá-la posteriormente. Todos usando componentes padrão do WordPress.

Antes de mergulharmos no código, lembre-se de que este post requer algum conhecimento do Gutenberg sobre como escrever blocos personalizados. Vamos nos concentrar apenas na parte do uploader de mídia e não em como registrar e fazer um bloco Gutenberg em si. Se você não tiver certeza sobre como escrever um bloco personalizado do Gutenberg, tenho uma série de tutoriais cobrindo exatamente isso:

Com isso fora do caminho, vamos mergulhar de cabeça!

O que vamos fazer

A função de seleção de mídia será funcionalmente exatamente igual à função de imagem em destaque do WordPress. Vamos dentro do Inspector adicionar um painel que consiste em um botão para escolher uma imagem.

Ao clicar no botão, a janela "Selecionar ou fazer upload de mídia" será exibida, permitindo que você selecione um arquivo da Biblioteca de mídia. Limitamos a Biblioteca de mídia a mostrar apenas imagens. Depois que uma imagem é selecionada, o pop-up é fechado e o painel visualiza uma pequena miniatura da imagem selecionada. Abaixo os botões de visualização para alterar e remover a imagem serão exibidos. Exatamente como na imagem em destaque.

Este tutorial pressupõe que você usará a imagem selecionada como plano de fundo do bloco – apenas como exemplo. É por isso que armazenamos o URL da imagem. Vou incluir um exemplo de como usar a imagem selecionada (tanto na função editquanto na savefunção). Ao escolher uma imagem, a imagem aparecerá como plano de fundo do nosso bloco, tanto dentro do editor quanto no frontend.

Armazenamos o ID da mídia e a URL da mídia nos atributos do bloco. O código usa withSelect, um componente de ordem superior fornecido no wp.datapacote, para consultar mais informações sobre a mídia selecionada, por ID.

Também estou “pegando emprestado" nomes de classe da funcionalidade de imagem em destaque do WordPress para garantir que tudo pareça bom e não haja necessidade de escrever nenhum CSS por conta própria. Claro que isso é opcional.

Salvando a mídia selecionada em atributos

O que você precisa salvar nos atributos do seu bloco depende um pouco de você. No mínimo, precisamos armazenar o ID da mídia, obviamente. Isso pode ser suficiente se você não precisar usar o URL da mídia em nenhum lugar no código do script. Por exemplo, se você usar ServerSideRenderonde o PHP é responsável por renderizar a saída do bloco. Nesse caso, você pode obter facilmente o URL da imagem do ID da mídia usando, por exemplo, [wp_get_attachment_image_src](https://developer.wordpress.org/reference/functions/wp_get_attachment_image_src/)(). Porém no exemplo abaixo estou mostrando um exemplo simples de exibição da imagem como plano de fundo do nosso bloco, então também armazeno a URL da mídia como atributo. Usaremos o atributo URL em ambos edit(para adicionar o plano de fundo no editor) e no save(para adicionar o plano de fundo no frontend).

Vamos começar definindo nossos atributos. O ID da mídia deve ser o número do tipo e o padrão é 0. Isso facilita a comparação. E o URL da mídia deve ser tipo string com string vazia padrão.

attributes: {
    mediaId: {
        type: 'number',
        default: 0
    },
    mediaUrl: {
        type: 'string',
        default: ''
    }
},

Criando o componente

Para tornar nosso código mais ordenado, definimos um componente separado para a editfunção do bloco. Mais tarde, passaremos esse componente withSelectpara envolvê-lo em nosso componente.

No retorno do componente renderizamos um simples <div>para o conteúdo do bloco. Suponho que você terá ou terá mais conteúdo de bloco real para substituir o conteúdo de exemplo fictício. Também renderizamos InspectorControls(package wp.blockEditor) para adicionar uma seção ao inspetor. Por enquanto eu adiciono um vazio PanelBodydentro do arquivo InspectorControls. Eu adiciono um <div>com a mesma classe que a seção de imagens em destaque do WordPress usa. Isso garante que nosso estilo pareça bom. Mais tarde, preencheremos isso PanelBodycom o código para a funcionalidade de seleção de mídia.

Mas primeiro, vamos desestruturar o componente necessário no início do arquivo:

const { InspectorControls } = wp.blockEditor;
const { PanelBody } = wp.components;
const { Fragment } = wp.element;

Acima do registerBlockTypeeu defino um componente simples chamado BlockEdit. Se você preferir mover isso para um arquivo separado, você pode fazê-lo. Isso é comum e recomendado, mas para este tutorial estou mantendo as coisas simples e mantendo-as no mesmo arquivo.

Agora queremos renderizar este componente em nossa editfunção. Mas queremos envolvê-lo em um arquivo withSelect.

Usando withSelectna editfunção

Se você não estiver familiarizado com withSelect, é um componente útil de ordem superior que nos permite realizar consultas. Você pode, por exemplo, consultar postagens com isso. No entanto, usaremos a função select('core').getMedia()para consultar o ID da mídia. Como resposta, obteremos um objeto com todas as informações da mídia. O objeto de mídia que recebemos em resposta será fornecido como prop em nosso BlockEditcomponente, pronto para uso. Bonito.

Certificamo-nos de consultar a mídia apenas se o atributo de ID de mídia estiver realmente definido como algo diferente de 0. É assim que nossa função de edição se parecerá:

No final, após fechar withSelecta fila #3é onde pedimos withSelectpara devolver nosso BlockEditcomponente. Com isso nosso BlockEditcomponente agora tem acesso a props.media.

Renderizando uma seleção de mídia

Finalmente vem a parte divertida: A parte do Inspetor.

O componente em que estamos interessados ​​é MediaUpload(package wp.blockEditor). Se você estiver interessado, o repositório Github do WordPress para Gutenberg tem alguma documentação sobre este componente. Também envolveremos este componente dentro de um componente chamado MediaUploadCheck(package wp.blockEditor). Esse componente garante que o usuário atual tenha recursos para usar a Biblioteca de mídia, portanto, é uma boa prática usá-lo.

O MediaUploadcomponente tem uma prop necessária: render. A forma como este componente funciona é que definimos uma função para o renderprop onde renderizamos a saída para a “área de upload de mídia”. No nosso caso vamos renderizar um Button(package wp.components). Dentro do suporte de renderização do MediaUpload, temos acesso à openfunção que podemos chamar para fazer o WordPress abrir o pop-up da Biblioteca de Mídia:

Há mais alguns adereços disponíveis para MediaUpload. Abordaremos os importantes para torná-lo funcional neste tutorial, mas há mais alguns com os quais você pode brincar. Você pode pelo menos estar interessado no prop allowedTypesonde você pode limitar quais tipos de arquivo são possíveis de selecionar na Biblioteca. No nosso caso, configuramos para permitir apenas imagens.

Adicionando oMediaUpload

Desestruturar os novos componentes primeiro;

const { Button } = wp.components;
const { MediaUpload, MediaUploadCheck } = wp.blockEditor;

Vamos adicionar MediaUploadChecke MediaUploaddentro do nosso divem nosso PanelBody:

O código acima desestrutura opendentro da função para render. Renderizamos um simples Buttononde sua onClickpropriedade executará a openfunção. Também adicionei os mesmos nomes de classe que a funcionalidade de imagem em destaque do WordPress para garantir que não precisamos adicionar nenhum estilo.

Dentro do Buttoncomponente verificamos se uma imagem foi definida ou não (attributes.mediaId). Caso contrário, ecoamos o texto “Escolha uma imagem”. Devemos agora obter isso em nosso bloco.

Ao clicar no botão, o pop-up Biblioteca de mídia deve aparecer. No entanto, selecionar uma imagem não funciona no momento, porque estamos perdendo os adereços onSelecte em. Vamos corrigir isso agora. Definimos para o ID de mídia selecionado e configuramos para executar uma função que definiremos mais tarde dentro de nosso componente.value``MediaUpload``value``onSelect

Vamos definir a onSelectMediafunção dentro do nosso componente.

Manipulando a seleção de mídia

Nota: Estou definindo minhas funções como funções de seta (onSelectMedia =() => { }). As funções de seta são muito novas no ESNext e muito bacanas. A desvantagem é que o uso de funções de seta requer que você adicione suporte para isso em sua configuração do Babel. Se você ainda não fez isso, recomendo olhar sob o título “Configurando o Babel” neste post.

Logo antes da instrução de retorno do componente, defino uma onSelectMediafunção. Tudo o que precisamos fazer é atualizar nossos atributos usando setAttributes(). Como parâmetro para onSelectMediaobtermos um objeto de mídia. Simplesmente extraímos o que precisamos do objeto de mídia. No nosso caso, é o ID da mídia e o URL de tamanho completo, que são as propriedades ide, urlrespectivamente.

Experimente agora e agora você poderá selecionar uma imagem da Biblioteca de mídia. A mídia selecionada é salva nos atributos do bloco. No entanto, ainda não há visualização no Inspetor e, como você selecionou uma imagem, o botão para selecionar uma imagem desaparece. O painel agora está vazio. A próxima etapa é renderizar a visualização sempre que uma imagem for selecionada, além de fornecer opções para removê-la ou alterá-la.

Renderizando uma imagem de visualização

Dentro do Buttoncomponente que renderizamos dentro MediaUploadda renderprop, ecoamos um texto “Escolha uma imagem” se uma imagem ainda não estiver definida. Mas precisamos adicionar algum código para quando uma imagem for definida aqui; uma prévia.

Para nos ajudar a renderizar uma boa visualização, usamos o componente ResponsiveWrapper(package wp.components). Para ResponsiveWrapperfuncionar plenamente, precisamos fornecer adereços para a altura e a largura. Também precisamos do URL da miniatura. Não adianta usar a URL completa (que pode ser gigantesca) para renderizar uma visualização dentro do Inspector. É aqui que withSelectentra o prop. Dentro do componente nós renderizamos uma simples <img>tag HTML.

Primeiro desestruturamos o componente necessário:

const { ResponsiveWrapper } = wp.components;

Como você pode ver, acessamos o prop que o withSelectcomponente nos forneceu, props.media. Buscamos a largura, altura e url para o tamanho da miniatura da mídia do objeto.

Agora você deve obter uma boa visualização da imagem selecionada!

Como renderizamos a imagem de visualização dentro, Buttonclicar na imagem de visualização acionará a Buttonfunção do onClick– que é abrir a Biblioteca de Mídia. Dessa forma você já pode alterar a imagem selecionada.

Atualmente não há como remover ou redefinir a imagem selecionada. Vamos consertar isso!

Adicionando uma função de remoção

Devemos, no mínimo, oferecer ao usuário a possibilidade de remover a imagem selecionada. A partir de agora, depois de selecionar uma imagem, você só pode alterá-la, mas não removê-la.

Faremos o mesmo que o WordPress faz para a imagem em destaque: Um novo Buttonabaixo da imagem de visualização (totalmente fora de seu MediaUploadCheck). Ao fornecer alguns adereços inteligentes Button, fazemos com que pareça um link (isLink) com a cor de texto vermelha (isDestructive). Leia a documentação do Button para ver o que mais é possível. Envolvemos o botão dentro de outro MediaUploadCheck, apenas para garantir que o usuário tenha os recursos certos.

Para este evento executamos uma nova função dentro Buttondo onClicknosso componente: removeMedia(). Nós o definimos em algum lugar logo antes da função de retorno do componente, como fizemos com onSelectMedia.

Tudo o que essa função faz é redefinir nossos dois valores de atributo.

Agora teremos um link bom e claro para remover a imagem:

Quando você clica no botão novo, a imagem selecionada e o próprio botão desaparecem, e o botão para selecionar uma imagem aparece novamente.

Adicionando um botão de substituição

Esta etapa é totalmente opcional. Como mencionado anteriormente, clicar na imagem de visualização da imagem abrirá a Biblioteca de mídia e permitirá que você altere a imagem. No entanto, isso pode não ser tão intuitivo para todos entenderem. O WordPress adiciona um botão separado para alterar a imagem, apenas para deixar bem claro. Nós podemos fazer o mesmo.

Para renderizar um botão de mudança de imagem, basicamente repetimos o código que temos para selecionar a imagem: outro MediaUploadcomponente. Fornecemos a mesma função para onSelect, allowedFileTypese valuecomo antes. Dentro do renderprop para MediaUploadnós simplesmente renderizamos outro Buttonque abre a Media Library. Vamos colocar este botão antes do botão Remover – pois isso faz mais sentido para o usuário final:

Então agora você deve obter isso:

Usando a imagem selecionada

Até agora deve estar bem claro como você pode usar a imagem selecionada. Você tem o ID da mídia e o URL da mídia armazenados nos atributos do seu bloco. No entanto, como exemplo simples, incluirei um código que define a imagem selecionada como plano de fundo do bloco. O código pode ser feito exatamente da mesma forma nas funções the edite the save. Simplesmente criamos um objeto de estilo que aplicamos na div de encapsulamento do bloco. No objeto de estilo, definimos a imagem de fundo para o URL da mídia.

Com o resto do seu conteúdo de bloco personalizado, poderia facilmente ser algo assim:

Se você aplicar o estilo de bloco em edite save, seu bloco agora deve obter a mídia selecionada como plano de fundo. Tanto dentro do editor quanto no frontend.

Conclusão

Selecionar uma imagem (ou arquivo) da Biblioteca de Mídia é uma função que você, como desenvolvedor do Gutenberg, sem dúvida precisará para seus blocos. Aprendemos como adicionar uma função para selecionar uma imagem da Biblioteca de mídia em nosso bloco Gutenberg personalizado. Fizemos da mesma forma que o próprio WordPress faz para a imagem em destaque. (Editar maio de 2020: o WordPress agora atualizou a imagem em destaque para usar useSelecto gancho React). Isso garante que nosso código não seja "hackeado" com um alto risco de quebrar em atualizações futuras.

Deixe-me saber se você já usou isso!

Código completo

Abaixo está o código completo de um bloco personalizado que apresenta a funcionalidade de mídia selecionada. E nada mais realmente. Essa parte é com você!