Eventos de Botão de UI

Lide com eventos de botão em entidades de UI.

Para criar um botão na sua UI, crie um Button elemento de UI com as seguintes propriedades:

• valor: Uma string com o texto a ser exibido no botão.

• onMouseDown: Uma função callback que é executada toda vez que o usuário pressiona o botão do ponteiro sobre a entidade.

• uiTransform: Propriedades de posicionamento do elemento de UI.

O exemplo a seguir mostra como criar um botão de UI clicável.

arquivo 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')
		}}
	/>
)

arquivo 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 os trechos a seguir nesta página presumem que você tem um .ts similar ao acima, executando a ReactEcsRenderer.setUiRenderer() função.

Você também pode escrever a função que é executada pelo clique fora da definição da UI e referenciá-la por nome. Isso ajuda a manter o código da UI mais legível e também é útil se várias entidades de UI clicáveis precisarem chamar a mesma função.

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

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

Os campos a seguir podem ser adicionados a um Button elemento de UI:

• onMouseDown: Uma função callback que é executada toda vez que o usuário pressiona o botão do ponteiro sobre a entidade.

• onMouseUp: Uma função callback que é executada sempre que o botão do ponteiro é levantado enquanto aponta para a entidade.

• onMouseEnter: Uma função callback que é executada toda vez que o ponteiro começa a passar o cursor sobre o botão.

• onMouseLeave: Uma função callback que é executada toda vez que o ponteiro para de passar o cursor sobre o botão.

• color: Cor de fundo do botão.

• font: Fonte do texto no botão.

• textAlign: Alinhamento do texto dentro do botão

• uiTransform: Propriedades de posicionamento do elemento de UI.

• uiBackground: Define a cor ou textura do elemento de UI.

• variant: Use esta propriedade para definir o estilo do botão como um dos padrões. primary e secondary estão disponíveis.

• disabled: Booleano para definir um botão como desabilitado. Quando disabled é definido como true, o onMouseDown e onMouseUp ações não são mais chamadas. Além disso, o alpha valor da cor tanto do texto quanto do fundo é reduzido pela metade, então o botão fica "acinzentado" e se destaca menos.

Estilização de Button

Defina a variant para primary ou secondary para aproveitar as opções de estilo padrão para botões. primary faz seu botão ficar vermelho com texto branco, secondary faz seu botão ficar branco com texto vermelho.

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>
)

Você também é livre para usar todas as propriedades em background livremente. Você também pode definir uma variant e então sobrescrever algumas de suas propriedades. Este exemplo usa a primary variant, mas sobrescreve a cor para ser 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(),
		}}
	/>
)

Botões alternáveis

Um caso de uso comum é fazer um botão alternar entre dois estados, como um interruptor. O exemplo abaixo alterna entre duas cores cada vez que o botão é pressionado:

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) {
				// faça algo
			} else {
				// faça outra coisa
			}
		}}
		uiBackground={{
			color: buttonEnabled ? Color4.Green() : Color4.Red(),
		}}
	/>
)

Observe que no exemplo acima, a cor depende de uma buttonEnabled variável. Sempre que o valor dessa variável muda, isso afeta imediatamente a cor de fundo.

Feedback ao passar o cursor

Outro caso de uso comum é exibir algum tipo de indicação visual ao passar o cursor sobre um botão, para esclarecer que isto é interativo, ou mesmo para exibir uma dica de hover explicando o que esse botão faz. Use os onMouseEnter e onMouseLeave callbacks para detectar quando o cursor do jogador está sobre o botão e reagir adequadamente.

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

let buttonEnabled = false

export const uiMenu = () => (
	<Button
		value="My Button"
		uiTransform={{ width: 100, height: 100 }}
		onMouseDown={() => {
			// função do botão
		}}
		onMouseEnter={() => {
			// mostrar dica
		}}
		onMouseLeave={() => {
			// ocultar dica
		}}
	/>
)

Tornando outros elementos clicáveis

Qualquer elemento na UI pode ser tornada clicável adicionando uma onMouseDown propriedade a ele; funciona de forma idêntica a um botão. O exemplo a seguir adiciona onMouseDown propriedades a imagens de fundo e 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>
)

Bloqueio de ponteiro

Todas as entidades de UI não bloqueiam ponteiros por padrão, o que significa que os cliques dos jogadores irão atravessá-las e interagir com objetos no espaço 3D atrás delas. Se uma entidade tiver um onMouseDown callback, então ela se torna bloqueadora de ponteiro, de modo que os cliques dos jogadores não afetam o que está atrás dessa entidade de UI.

Você pode mudar esse comportamento padrão alterando o valor do pointerFilter propriedade no uiTransform component on any UI entity. For example to set an entity that has no onMouseDown to be pointer blocking.

Os valores suportados para pointerFilter são:

• block: O elemento de UI bloqueia ponteiros; os jogadores não podem clicar em nada atrás deste elemento de UI.

• none: O elemento de UI não bloqueia ponteiros. O elemento não é clicável e qualquer coisa atrás dele pode ser clicada.

Abaixo está uma UI simples que não tem um onMouseDown, mas que sobrescreve o comportamento padrão de não bloquear ponteiros definindo pointerFilter para block.

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

// desenhar UI
export const uiMenu = () => (
	<UiEntity
		uiTransform={{
			width: '100%',
			height: '100px',
			pointerFilter: `block`,
		}}
		uiText={{ value: `Este elemento bloqueia ponteiros`, fontSize: 40 }}
		uiBackground={{ color: Color4.create(0.5, 0.8, 0.1, 0.6) }}
	/>
)