Cómo agregar configuraciones de color a su bloque de Gutenberg personalizado

Esta publicación profundizará en cómo agregar configuraciones de color a su bloque personalizado de WordPress Gutenberg. Aprenderemos cómo agregar el mismo componente de configuración de color, que presenta la elección de colores de paleta y color personalizado, como usan muchos de los bloques predeterminados de WordPress.

Esto es lo que agregaremos a nuestro bloque personalizado:

Al usar los componentes de Gutenberg, podemos implementar muy fácilmente esta paleta/sección de color en nuestro propio bloque personalizado. Puede definir la configuración de color para afectar cualquier color que desee; fondo, color de texto, color de borde o cualquier otra cosa. También puede agregar tantas configuraciones de color como desee dentro de este panel.

Antes de sumergirnos en el código, hay algunas cosas que debe tener en cuenta. No salte al código, ya que la siguiente sección explicará mucho por qué el código debe hacerlo como lo hace.

Lo que necesitas saber primero

Los componentes para implementar configuraciones de paleta/color son PanelColorSettingsy withColorsdel wp.blockEditorpaquete. El componente withColorses un llamado componente de orden superior y debe implementarse de manera un poco diferente a la simple salida de un componente normal. Voy a entrar en un poco más de detalle más adelante. Pero primero debemos ser conscientes de los conceptos básicos sobre cómo Gutenberg maneja la configuración de color de bloque.

Cómo los bloques de Gutenberg manejan la configuración de color

Hay ciertas reglas sobre cómo Gutenberg maneja la configuración de color en bloques. Si alguna vez ha diseñado un tema compatible con Gutenberg antes, probablemente ya esté familiarizado con estas reglas. Sin embargo, los revisaremos rápidamente porque tenemos que manejar esto en nuestro código de bloque.

• Cuando se elige un color de paleta, el elemento del bloque de nodos obtendrá una clase de un patrón determinado. La clase comienza con " has-", y luego viene el slug de la paleta. El final depende de qué elemento debe afectar el color. Para el color del texto, termina con " -color". Para el color de fondo, termina con " -background-color". Como ejemplo, un bloque con un color de paleta "rojo" elegido como color de fondo obtendrá la clase " has-red-background-color".
• Cuando se elige un color personalizado (del selector de color), el elemento del bloque de nodos obtendrá un estilo en línea con el código hexadecimal. Por ejemplo, un color personalizado #DD0000 elegido como color de fondo obtendrá el atributo " style="background-color: #DD0000;".

Cuando implementemos la configuración de color para nuestro bloque, necesitaremos implementar la clase correcta y el estilo en línea. Lo haremos al final de este tutorial.

como trabajar conwithColors

Como se mencionó anteriormente withColors, es un componente de orden superior. Básicamente, eso significa que es un componente que toma un componente y devuelve un nuevo componente. En el componente devuelto, obtenemos accesorios útiles del componente de orden superior. En pocas palabras, utilizaremos withColorspara devolver nuestro propio componente para nuestro bloque personalizado. Nuestro componente de bloque obtiene los accesorios necesarios para trabajar con colores de withColors.

El componente withColorsmaneja el estado y mucha funcionalidad para trabajar con colores. Y obtenemos mucha automatización en este proceso. Esto es muy útil para averiguar si el color elegido es un color de paleta (necesitamos agregar una clase) o un color personalizado (necesitamos agregar un estilo en línea). withColorssimplificar mucho el proceso de almacenar el color elegido, cualquiera que sea, en los atributos de nuestro bloque. Hablando de atributos..

Atributos ywithColors

Obviamente, su bloque necesita atributos para almacenar el color elegido. Para beneficiarse de la automatización de withColor para almacenar el color correcto, en realidad necesita definir dos atributos para cada configuración de color. Uno para almacenar el slug del color de la paleta y otro para almacenar el código hexadecimal. Sin embargo, hay algunas reglas.

Supongamos que desea agregar una configuración de color para el color del texto del bloque, por lo que decide definir un atributo llamado " textColor". Luego deberá definir otro atributo en el patrón " customYourOriginalAttribute". En este ejemplo, el segundo atributo deberá llamarse " customTextColor". Cuidado con camelCase (mayúsculas) aquí. Siguiendo este patrón withColorsautomáticamente:

• Si se ha elegido un color de paleta, el atributo ” textColor" contendrá el slug de la paleta.
• Si se ha elegido un color personalizado, ” customTextColor” se completará con el código hexadecimal.

Estos dos trabajan en tándem. Si se elige un color personalizado, textColorautomáticamente será undefined, y viceversa.

Y finalmente, una última cosa para recordar: ¡no necesitará usar setAttributes()para actualizar sus atributos de color! Los accesorios provistos withColorsincluyen una función que actualiza automáticamente sus atributos por usted. Todo lo que necesita hacer es pasar esta función al onChangeevento al PanelColorSettingscomponente, y sus atributos se actualizarán automáticamente.

Ok, ¡es hora de ver todo esto en la práctica!

Implementación de configuraciones de color en un bloque personalizado

Para empezar, tengo un bloque personalizado bastante inútil que no hace nada más que mostrar un texto codificado. Esto solo facilita la separación de lo que necesitamos codificar para agregar configuraciones de color. Tengo una serie de tutoriales sobre cómo crear sus propios bloques personalizados si está interesado en obtener más información.

Nota: Estoy escribiendo todo el código en ES6/ESNext. Esto incluye funciones de flecha que requieren un cuidado especial en la configuración de Babel/webpack. Si recibe errores en algunos de los códigos a continuación, siga mi guía sobre cómo configurar Webpack y Babel para ES6/ESNext o ajuste el código para que no use "sintaxis experimentales".

Este es mi bloque personalizado básico antes de hacer nada con la configuración de color:

Es bastante básico. Tenga en cuenta que la editfunción simplemente se refiere a un componente separado BlockWithColorSettings, en lugar de escribirlo en línea. Esto hace que sea más fácil de implementar withColorsmás adelante.

¡Bien, es hora de implementar la configuración de color en nuestro bloque! Como ejemplo, quiero configurar el color del texto.

Agregar atributos

Como se mencionó anteriormente, necesitamos definir dos atributos para cada configuración de color. Y tenemos que tener mucho cuidado en su nombramiento. Quiero agregar un atributo de color de texto, así que estoy nombrando el atributo textColor. Lo que significa que también agregaré un atributo customTextColor. Ambos deben ser de tipo cadena.

Nuestros atributos están listos para almacenar la configuración de color del texto del bloque. Ahora es el momento de implementar withColorsy PanelColorSettings.

ImplementarwithColors

Como se mencionó anteriormente withColors, es un componente de orden superior que debe tomar un componente para regresar. Obviamente queremos que devuelva nuestro componente de edición, BlockWithColorSettings. Pero como parámetro withColorsproporcionamos un objeto.

En el objeto pasado withColors, debemos indicar withColorsqué atributo queremos usar para almacenar el color y qué tipo de elemento coloreará (en nuestro caso, color de texto, que significa "color" de la regla CSS). Informar sobre la regla CSS asegura que los nombres de clase devueltos sean correctos. Debido a que este es el color del texto, queremos nombres de clase como "has–color".

Primero algo de desestructuración en la parte superior. withColorsreside en el wp.blockEditorpaquete.

const { withColors } = wp.blockEditor;

Cambiaremos la editfunción a:

Con este código, nuestro componente BlockWithColorSettingsrecibirá algunos accesorios adicionales:

• props.textColor: Es un objeto que consta de toda la información sobre el color elegido. Si se eligió un color de paleta, almacenará propiedades para código hexadecimal, slug de paleta, nombre de clase y más. Si se eligió un color personalizado, el objeto contendrá el código hexadecimal. El código hexadecimal siempre se encuentra en la propiedad color. Y el nombre de la clase (solo si se eligió un color de paleta) se establecerá en la propiedad class.
• props.setTextColor: Una función que actualizará nuestros atributos por nosotros. Proporcionamos esto para el onChangeevento de configuración de color como veremos más adelante. La función actualizará los atributos textColory. customTextColorDebido a que seguimos las reglas de nomenclatura, se actualizará automáticamente customTextColora pesar de que nunca proporcionamos este nombre de atributo.

Tenga en cuenta que la función "establecer" proporcionada como prop seguirá la regla: " setYourAttributeName". Debido a que proporcionamos textColor, la función se nombra setTextColor. Si, en cambio, nombramos nuestro atributo awesomeColory lo proporcionamos en el withColorsobjeto, la función de conjunto se llamaría setAwesomeColor().

ImplementarPanelColorSettings

El siguiente paso es implementar la sección Inspector real. Para ello añadimos PanelColorSettingsdentro un InspectorControlscomponente. Debido a que React requiere que todo esté dentro de un nodo raíz, también usamos Fragment(from wp.elements) para envolver todo dentro.

Primero algo de desestructuración en la parte superior del archivo:

const { Fragment } = wp.element;
const { InspectorControls, PanelColorSettings, withColors } = wp.blockEditor;

Y actualizamos nuestro BlockWithColorSettingscomponente en algo como esto:

Como puede ver en la línea #2, desestructuramos los accesorios recibidos de withColors, textColory setTextColor. Tenga en cuenta que props.textColores el objeto recibido de withColors, y props.attributes.textColores el atributo. Sin embargo, no tenemos necesidad de referirnos al atributo.

Como accesorios para el componente PanelColorSettings, podemos proporcionar un título para la sección (título en el cuadro plegable en Inspector). Lo importante aquí es el accesorio colorSettingsdonde necesitamos proporcionar una variedad de objetos de configuración de color. Para cada configuración de color (actualmente solo tenemos una) necesitamos proporcionar algunas propiedades. La propiedad valueespera el código hexadecimal elegido actualmente (aunque se haya elegido un color de paleta). Esto se proporciona para nosotros en el textColorprop, dentro de la propiedad color. Para la onChangepropiedad, simplemente proporcionamos la función "establecer" proporcionada por withColors, setTextColor. Y por último deberíamos dar a labelpara que el usuario sepa a qué elemento afectará este color. Aparecerá justo encima del área de elección de un color.

Así es como aparece nuestro componente en el editor de Gutenberg ahora mismo:

Ahora está actualizando con éxito nuestros atributos al elegir colores. Puede ver que recuerda su elección de color al guardar la publicación.

Sin embargo, no sucede nada visualmente cuando cambias de color. La elección de color se almacena en los atributos, pero no se produce ningún cambio de color en el editor, ni al obtener una vista previa de la publicación. Esto se debe a que necesitamos agregar código para las clases y estilos del bloque. Necesitamos hacer esto tanto para la editfunción (que es para el editor) como para la savefunción (interfaz). Ese es el siguiente paso.

Manejo de clases y estilos en línea enedit

Necesitamos construir la clase de nodo y los atributos de estilo del bloque de acuerdo con la configuración de color elegida. Afortunadamente withColors, conseguimos algo de automatización en esto. Recuerda que props.textColores un objeto que contiene toda la información que necesitamos, incluido el nombre de la clase.

Podríamos hacer algo como esto:

En línea #20, aplicamos la clase crítica y el estilo en línea al nodo raíz de nuestro bloque. Antes de eso, construimos la clase y el atributo de estilo en línea al verificar el props.textColorobjeto.

Después de este cambio, su bloque personalizado ahora debería ser completamente funcional en el editor. Siempre que cambies de color, el bloque cambiará el color del texto. ¡Impresionante! El último paso es hacer esto también para la savefunción, de modo que también obtengamos estas clases y estilos en la interfaz.

Manejo de clases y estilos en línea ensave

El concepto de construir la clase y los estilos en línea y aplicarlos al nodo raíz es el mismo saveque en edit. Pero hay una diferencia crucial. En saveno tenemos los accesorios proporcionados por withColors. Y no podemos agregar componentes de orden superior a la savefunción. Entonces, en la savefunción, toda la información que tenemos son los atributos.

Es una buena regla general evitar codificar nombres de clase "has-". ¿Qué pasa si WordPress decide cambiar esta regla en el futuro? Afortunadamente, tenemos una función que puede ayudarnos a generar los nombres de clase adecuados para nosotros: getColorClassName().

Antes de que olvidemos, vamos a desestructurarlo. También está en el wp.blockEditorpaquete.

const { InspectorControls, PanelColorSettings, withColors, getColorClassName } = wp.blockEditor;

El uso de la getColorClassName()función requiere dos parámetros. Primero una cadena para la regla CSS. Debido a que nuestra configuración de color es para el color del texto, proporcionamos ‘ color‘. Esto le dice a la función que debe devolver un nombre de clase de "tiene-algo-color" y no "tiene-algo-color-de-fondo", por ejemplo. Como segundo parámetro necesitamos proporcionar el valor del atributo.

El atributo de estilo se crea simplemente configurando "color" en el valor del atributo customTextColor, si está definido.

Y, por supuesto, no olvide aplicar la clase y el estilo en el nodo raíz de su bloque; como en linea #12.

PD: si está probando su bloque en el editor mientras escribe este código, ahora obtendrá un error de bloque. Esto sucede porque ahora hemos cambiado la salida de la savefunción y todo lo que haya guardado anteriormente está en conflicto. Deberá eliminar el bloque y volver a agregarlo.

Después de este cambio, su bloque ahora también debería aplicar correctamente el color de texto elegido en la interfaz.

¡Y eso es! Ahora ha implementado con éxito la configuración de color en su bloque. Si está interesado en agregar varias configuraciones de color (no solo el color del texto), siga leyendo.

Una nota sobre la configuración de varios colores

A estas alturas, debería poder implementar múltiples configuraciones de color. Es posible que desee agregar configuraciones para el color de fondo, el color del texto, el color del borde o cualquier otra cosa para su bloque. En esta sección, haré una descripción general rápida de lo que debemos hacer para implementar múltiples configuraciones de color.

Supongamos que también quiero agregar color de fondo a mi bloque.

Primero necesito definir un nuevo atributo llamado creativamente backgroundColor. Defino otro atributo customBackgroundColortambién.

En la editfunción cambio el objeto provisto withColorscomo tal:

withColors({textColor: 'color', backgroundColor: 'background-color'})

Esto indica withColorsque mi textColoratributo es para la regla CSS " color" (para el color del texto), y el atributo backgroundColores para la regla CSS " background-color". withColorsreconocerá y actualizará automáticamente los atributos y también customTextColor.customBackgroundColor

En el PanelColorSettingscomponente, proporciono otro objeto a la matriz para el accesorio colorSettings. Al igual que:

Con esto, debería obtener dos configuraciones de color separadas dentro del cuadro Inspector para la configuración de color.

El último paso es construir los nombres y estilos de clase apropiados en ambos edity save. Este es un paso bastante simple, ya que solo se trata de construir una cadena o un objeto de estilo correctamente. Recuerde que el nombre de su clase debe admitir varias clases de color (por ejemplo, si se eligieron tanto el color del texto como el color de fondo). Simplemente agregue un espacio entre cada nombre de clase.

PD: si necesita manejar muchos nombres de clase para su bloque, puede beneficiarse instalando el classnamespaquete. Prácticamente todos los componentes de Gutenberg utilizan esta biblioteca para combinar nombres de clases más fácilmente.

Conclusión y código completo.

Ahora debería haber aprendido cómo implementar configuraciones de color en su bloque personalizado. ¡Espero que esto te haya servido de algo! Tuve que agregar esta característica a mi proyecto, y realmente no pude encontrar ninguna información o buena documentación. Así que este es el resultado de consolidar todo lo que aprendí sobre este tema, después de mucho ensayo y error.

Aquí está el código final, en conjunto, para el bloque personalizado de ejemplo con configuración de color de texto: