Tipos Especiais de UI

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

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

Dropdown

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

Um Dropdown Entity deve ter pelo menos as seguintes propriedades:

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

• onChange: Uma função que é executada sempre que um valor é selecionado no Dropdown, usando

Você também pode configurar outros componentes do Dropdown Entity, como um uiTransform, como em outras entities de UI.

ficheiro 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',
        height: '100px',
        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>
)

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

Texto de entrada

Criar um Input Entity para permitir que os usuários digitem texto. Os jogadores devem primeiro clicar nesta caixa antes de poderem escrever nela.

O comportamento do Input Entity é 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 é não limpo automaticamente quando isso acontece; você precisa limpá-lo manualmente (veja o exemplo abaixo).

• onChange: Uma função que é executada sempre que um valor no texto de entrada é alterado. À medida que o jogador digita na caixa, esta função é executada uma vez para cada caractere que é adicionado ou removido.

• disabled: Se true, o jogador não poderá interagir com a Entity 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 tratar o onSubmit evento quando o jogador pressiona a tecla Enter/Return. O exemplo a seguir mostra como você pode fazer isso.

📔 Nota: Faça não vincular a value propriedade do Input diretamente ao que o jogador digita via onChange. Isso cria um ciclo 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 altere-o apenas quando quiser limpar o campo de entrada.

Para limpar o campo de entrada, defina value para ' ' (um único espaço). O Explorer trata isso como vazio e reativa o texto de placeholder. Como a função de UI é executada a cada frame, use uma flag para aplicar a limpeza por apenas 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 àquelas presentes em Label entities:

• placeholder: String a ser exibida antes de o jogador começar a digitar qualquer coisa. É útil fazer deste texto uma dica sobre o que ele deve escrever.

• placeholderColor: A cor a ser usada para o texto de 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.

  OBS.: O fontSize não é afetado pelo tamanho de sua Entity ou das entities 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. Os valores suportados são: - 'sans-serif' (padrão) - 'serif' - '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 do Input Entity, como um uiTransform, OnMouseDown 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>
)