Eventos de botones de UI

Maneja eventos de botones en UI entities.

Para crear un botón en tu UI, crea un Button elemento de UI con las siguientes propiedades:

• valor: Una cadena con el texto que se mostrará en el botón.

• onMouseDown: Una función callback que se ejecuta cada vez que el usuario presiona el botón del puntero sobre la entidad.

• uiTransform: Propiedades de posicionamiento del elemento de UI.

El siguiente ejemplo muestra cómo crear un botón de UI clicable.

archivo ui.tsx:

import { Button } from '@dcl/sdk/react-ecs'

export const uiMenu = () => (
	<Button
		value="Click me"
		uiTransform={{ width: 100, height: 100 }}
		onMouseDown={() => {
			console.log('Clicked on the UI')
		}}
	/>
)

archivo index.ts:

import { ReactEcsRenderer } from '@dcl/sdk/react-ecs'
import { uiMenu } from './ui'

export function main() {
    ReactEcsRenderer.setUiRenderer(uiMenu, { virtualWidth: 1920, virtualHeight: 1080 })
}

📔 Nota: Todos los fragmentos siguientes en esta página asumen que tienes un .ts similar al anterior, ejecutando la ReactEcsRenderer.setUiRenderer() función.

También puedes escribir la función que se ejecuta al hacer clic fuera de la definición de UI, y referenciarla por nombre. Esto ayuda a mantener el código de UI más legible, y también es útil si múltiples entidades clicables necesitan llamar a la misma función.

import { Button } from '@dcl/sdk/react-ecs'

function handleClick() {
	// Haz algo onClick
	console.log('Clicked on the UI')
}
export const uiMenu = () => (
	<Button
		value="Click me"
		uiTransform={{ width: 100 }}
		onMouseDown={{ handleClick }}
	/>
)

Los siguientes campos pueden añadirse a un Button elemento de UI:

• onMouseDown: Una función callback que se ejecuta cada vez que el usuario presiona el botón del puntero sobre la entidad.

• onMouseUp: Una función callback que se ejecuta cada vez que se levanta el botón del puntero mientras apunta a la entidad.

• onMouseEnter: Una función callback que se ejecuta cada vez que el puntero comienza a pasar por encima del botón.

• onMouseLeave: Una función callback que se ejecuta cada vez que el puntero deja de pasar por encima del botón.

• color: Color de fondo del botón.

• font: Fuente del texto en el botón.

• textAlign: Alineación del texto dentro del botón

• uiTransform: Propiedades de posicionamiento del elemento de UI.

• uiBackground: Establece el color o la textura del elemento de UI.

• variant: Usa esta propiedad para establecer el estilo del botón como uno de los predeterminados. primary y secondary están disponibles.

• disabled: Booleano para desactivar un botón. Cuando disabled está establecido en true, los onMouseDown y onMouseUp actions ya no se llaman. Además el alpha valor del color tanto del texto como del fondo se reduce a la mitad, por lo que el botón aparece "atenuado" y destaca menos.

Estilizado de Button

Establece la variant a primary o secondary para aprovechar las opciones de estilo predeterminadas para botones. primary hace que tu botón sea rojo con texto blanco, secondary hace que tu botón sea blanco con texto rojo.

import { UiEntity, Button, ReactEcs } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'

export const uiMenu = () => (
	<UiEntity
		uiTransform={{
			width: 500,
			height: 230,
			margin: '16px 0 8px 270px',
			padding: 4,
			alignSelf: 'center',
		}}
		uiBackground={{ color: Color4.Gray() }}
	>
		<Button
			value="Click Me"
			variant="primary"
			uiTransform={{ width: 80, height: 20, margin: 4 }}
			onMouseDown={() => {
				console.log('Clicked on the UI')
			}}
		/>
		<Button
			value="Click Me"
			variant="secondary"
			uiTransform={{ width: 80, height: 20, margin: 4 }}
			onMouseDown={() => {
				console.log('Clicked on the UI')
			}}
		/>
	</UiEntity>
)

También eres libre de usar todas las propiedades en background libremente. También puedes establecer una variant y luego sobrescribir algunas de sus propiedades. Este ejemplo usa la primary variant, pero sobrescribe el color para que sea verde:

import { Button } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'

export const uiMenu = () => (
	<Button
		value="My Button!"
		variant="primary"
		uiTransform={{ width: 100, height: 100 }}
		onMouseDown={() => {
			console.log('Clicked on My Button!')
		}}
		uiBackground={{
			color: Color4.Green(),
		}}
	/>
)

Botones alternables

Un caso de uso común es hacer que un botón alterne entre dos estados, como un interruptor. El ejemplo a continuación cambia entre dos colores cada vez que se presiona el botón:

import { Button } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'

let buttonEnabled = false

export const uiMenu = () => (
	<Button
		value="My Button"
		variant="primary"
		uiTransform={{ width: 100, height: 100 }}
		onMouseDown={() => {
			console.log('Clicked on My Button!')
			buttonEnabled = !buttonEnabled
			if (buttonEnabled) {
				// haz algo
			} else {
				// haz otra cosa
			}
		}}
		uiBackground={{
			color: buttonEnabled ? Color4.Green() : Color4.Red(),
		}}
	/>
)

Ten en cuenta que en el ejemplo anterior, el color depende de una buttonEnabled variable. Siempre que el valor de esta variable cambie, afecta inmediatamente al color de fondo.

Feedback al pasar el cursor

Otro caso de uso común es mostrar algún tipo de indicación visual al pasar el cursor sobre un botón, para aclarar que es interactivo, o incluso mostrar una pista al pasar el cursor que explique lo que hace este botón. Usa los onMouseEnter y onMouseLeave callbacks para detectar cuando el cursor del jugador está sobre el botón, y reaccionar en consecuencia.

import { Button } from '@dcl/sdk/react-ecs'

let buttonEnabled = false

export const uiMenu = () => (
	<Button
		value="My Button"
		uiTransform={{ width: 100, height: 100 }}
		onMouseDown={() => {
			// función del botón
		}}
		onMouseEnter={() => {
			// mostrar pista
		}}
		onMouseLeave={() => {
			// ocultar pista
		}}
	/>
)

Hacer otros elementos clicables

Cualquier elemento en la UI puede hacerse clicable añadiéndole una onMouseDown propiedad, funciona idénticamente a un botón. El siguiente ejemplo añade onMouseDown propiedades a imágenes de fondo y texto.

import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'

export const uiMenu = () => (
	<UiEntity
		onMouseDown={() => {
			console.log('Background clicked!')
		}}
		uiTransform={{
			width: 400,
			height: 230,
		}}
		uiBackground={{ color: Color4.create(0.5, 0.8, 0.1, 0.6) }}
	>
		<Label
			onMouseDown={() => {
				console.log('Label clicked!')
			}}
			value={`Player: ${getPlayerPosition()}`}
			fontSize={18}
			uiTransform={{ width: '100%', height: 30 }}
		/>
	</UiEntity>
)

Bloqueo de puntero

Todas las entidades de UI no bloquean el puntero por defecto, lo que significa que los clics de los jugadores pasarán a través de ellas e interactuarán con objetos en el espacio 3D detrás de ellas. Si una entidad tiene un onMouseDown callback, entonces se convierte en bloqueadora de puntero, por lo que los clics del jugador no afectan lo que está detrás de esa entidad de UI.

Puedes cambiar este comportamiento por defecto cambiando el valor de la pointerFilter propiedad en el uiTransform componente en cualquier entidad de UI. Por ejemplo para establecer una entidad que no tiene onMouseDown que sea bloqueadora de puntero.

Los valores soportados para pointerFilter son:

• block: El elemento de UI bloquea el puntero, los jugadores no pueden hacer clic en nada detrás de este elemento de UI.

• none: El elemento de UI no bloquea el puntero. El elemento no es clicable y cualquier cosa detrás de él puede ser clicada.

A continuación hay una UI simple que no tiene un onMouseDown, pero que anula el comportamiento por defecto de no bloquear el puntero estableciendo pointerFilter a block.

import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'

// dibujar UI
export const uiMenu = () => (
	<UiEntity
		uiTransform={{
			width: '100%',
			height: '100px',
			pointerFilter: `block`,
		}}
		uiText={{ value: `This element is pointer blocking`, fontSize: 40 }}
		uiBackground={{ color: Color4.create(0.5, 0.8, 0.1, 0.6) }}
	/>
)