Tipos especiais da UI

Tipos especiais de entity para a UI, incluindo dropdowns e caixas de entrada.

Existem certos tipos especiais de entidade que permitem alguns tipos especiais de interações.

Dropdown

Crie uma Dropdown entidade para permitir que os usuários expandam e selecionem um item de uma lista.

A Dropdown entidade deve ter pelo menos as seguintes propriedades:

• options: Quais valores exibir quando o dropdown for expandido. Forneça um objeto contendo um array com um valor de string para cada option. O primeiro valor no array é exibido como a opção padrão.

• onChange: Uma função que é executada toda vez que um valor é selecionado no dropdown, usando

Você também pode configurar outros componentes da Dropdown entidade, como um uiTransform, assim como em outras entidades de UI.

arquivo ui.tsx:

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

function selectOption(index: number) {
  switch (index) {
    case 0:
      textColor = Color4.Red()
      break
    case 1:
      textColor = Color4.Blue()
      break
    case 2:
      textColor = Color4.Green()
      break
  }
}

let textColor: Color4Type = Color4.Red()

export const uiMenu = () => (
    <UiEntity
      uiTransform={{
        width: '200px',
        pointerFilter: `block`,
        alignContent: 'auto',
        flexDirection: 'column',
        alignSelf: 'center',
      }}
    >
      <Label
        value="Selecione uma cor"
        fontSize={18}
        color={textColor}
        uiTransform={{
          width: '140px',
          height: '40px',
        }}
      />
      <Dropdown
        options={[`Red`, `Blue`, `Green`]}
        onChange={selectOption}
        uiTransform={{
          width: '100px',
          height: '40px',
        }}
      />
    </UiEntity>
)

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

Texto de entrada

Crie uma Input entidade para permitir que os usuários digitem texto. Os jogadores precisam primeiro clicar nesta caixa antes de poderem escrever nela.

O comportamento da Input entidade é gerenciado pelas seguintes propriedades:

• onSubmit: Uma função que é executada quando o jogador pressiona Return/Enter, usando o texto fornecido como entrada. O campo de texto é limpo quando isso acontece.

• onChange: Uma função que é executada toda vez que um valor no texto de entrada é alterado. À medida que o jogador digita na caixa, essa função é executada uma vez para cada caractere adicionado ou removido. Ela também é chamada quando o jogador pressiona Return/Enter e o texto é limpo.

• disable: Se true, o jogador não poderá interagir com a entidade de entrada.

O exemplo a seguir usa onSubmit para registrar o texto fornecido no console.

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


export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 400,
      height: 300,
      positionType: 'absolute',
      position: {
        left: '35%',
        top: '40%',
      },
    }}
    uiBackground={{
      color: Color4.Gray(),
    }}
  >
    <Input
      onSubmit={(value) => {
        console.log('submitted value: ' + value)
      }}
      fontSize={35}
      placeholder={'digite algo'}
      placeholderColor={Color4.Black()}
      uiTransform={{
        width: '400px',
        height: '80px',
      }}
    ></Input>
  </UiEntity>
)

É uma boa prática fornecer tanto um botão para enviar quanto lidar com o onSubmit evento quando o jogador pressiona a tecla Enter/Return. O exemplo a seguir mostra como você pode fazer isso.

📔 Nota: Não não vincule o value propriedade do Input diretamente ao que o jogador digita via onChange. Isso cria uma comunicação de ida e volta entre a scene e o Explorer que faz com que caracteres sejam perdidos ao digitar rapidamente. Em vez disso, mantenha value como uma string vazia e só o altere quando quiser limpar o campo de entrada.

Para limpar o campo de entrada, defina value // desenhar UI ' ' (um único espaço). O Explorer trata isso como vazio e reativa o texto do placeholder. Como a função de UI é executada a cada frame, use uma flag para aplicar a limpeza apenas por um frame.

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

let inputText = ''
let clearInput = false

export const uiMenu = () => {
  const inputValue = clearInput ? ' ' : ''
  if (clearInput) clearInput = false

  return (
    <UiEntity
      uiTransform={{
        width: 400,
        height: 300,
        positionType: 'absolute',
        position: {
          left: '35%',
          top: '40%',
        },
        flexDirection: 'column',
      }}
      uiBackground={{
        color: Color4.Gray(),
      }}
    >
      <Input
        onSubmit={() => {
          console.log('submitted value: ' + inputText)
          inputText = ''
          clearInput = true
        }}
        fontSize={35}
        placeholder={'digite algo'}
        placeholderColor={Color4.Black()}
        value={inputValue}
        onChange={(value) => { inputText = value }}
        uiTransform={{
          height: '80px',
          margin: '15px',
        }}
      />
      <Button
        value="Enviar texto"
        variant="primary"
        uiTransform={{ alignSelf: 'center', padding: '25px' }}
        onMouseDown={() => {
          console.log('submitted value: ' + inputText)
          inputText = ''
          clearInput = true
        }}
      />
    </UiEntity>
  )
}

As seguintes propriedades também estão disponíveis para personalizar a aparência do campo de texto, a maioria delas semelhante às presentes em Label entities:

• placeHolder: String a ser exibida antes que o jogador comece a digitar qualquer coisa. É útil tornar esse texto uma dica sobre o que ele deve escrever.

• placeHolderColor: A cor a ser usada para o texto do placeholder, como uma Color4.

💡 Dica: Use um tom mais claro da cor do texto que o jogador escreve.

• fontSize: O tamanho do texto, como um número.

  NOTA: O fontSize não é afetado pelo tamanho de sua entidade ou de suas entidades pai.

• color: A cor do texto que o jogador escreve, como uma Color4.

📔 Nota: Certifique-se de usar uma cor diferente da placeHolderColor.

• font: A fonte a ser usada, tomando um valor do Font enum. Os valores suportados são: - F_SANS_SERIF - F_SERIF (padrão) - F_MONOSPACE

• textAlign: Como o texto se alinhará com seu pai. Ele recebe um valor de `TextAlignType`. TextAlignType = 'top-left' | 'top-center' | 'top-right' | 'middle-left' | 'middle-center' | 'middle-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';

Você também pode configurar outros componentes da Input entidade, como um uiTransform, OnMouseDown assim como em outras entidades de UI.

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

var currentTextString = ''

export const uiMenu = () => (
    <UiEntity
      uiTransform={{
        width: '50%',
        height: 150,
        flexDirection: 'column',
        alignContent: 'flex-start',
        margin: { left: 20, top: 20 },
        padding: { left: 10, top: 10, right: 10 },
        alignSelf: 'center',
      }}
      uiBackground={{ color: Color4.Gray() }}
    >
      <Input
        onChange={(e) => {
          currentTextString = 'você escreveu: ' + e
        }}
        fontSize={35}
        placeholder={'digite algo'}
        placeholderColor={Color4.Gray()}
      />
      <Label value={currentTextString} fontSize={40} />
    </UiEntity>
)