Tipos Especiais de UI

Tipos especiais de entidade para a UI, incluindo dropdowns e caixas de input.

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

Dropdown

Criar um 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 estiver expandido. Forneça um objeto contendo um array com um valor string para cada opção. 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, 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',
        height: '100px',
        alignContent: 'auto',
        flexDirection: 'column',
        alignSelf: 'center',
      }}
    >
      <Label
        value="Select a color"
        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 trechos a seguir nesta página presumem que você tem um .ts similar ao acima, executando a ReactEcsRenderer.setUiRenderer() função.

Input text

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

O comportamento da Input entidade é gerenciado por meio das 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 input text é alterado. À medida que o jogador digita na caixa, essa função é executada uma vez para cada caractere que é adicionado ou removido. 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 input.

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={'type something'}
      placeholderColor={Color4.Black()}
      uiTransform={{
        width: '400px',
        height: '80px',
      }}
    ></Input>
  </UiEntity>
)

É uma boa prática fornecer tanto um botão para submissão quanto tratar o evento "onSubmit" quando o jogador pressiona a tecla Enter/Return. O exemplo a seguir mostra como você pode fazer isso. Note que, por consistência, a função executada pelo botão limpa manualmente o texto no campo de input.

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


let currentValue: string = ''

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 400,
      height: 300,
      positionType: 'absolute',
      position: {
        left: '35%',
        top: '40%',
      },
      flexDirection: 'column',
    }}
    uiBackground={{
      color: Color4.Gray(),
    }}
  >
    <Input
      onSubmit={(value) => {
        handleSubmitText(value)
      }}
      fontSize={35}
      placeholder={'type something'}
      placeholderColor={Color4.Black()}
      value={currentValue}
      onChange={($) => (currentValue = $)}
      uiTransform={{
        height: '80px',
        margin: '15px',
      }}
    ></Input>
    <Button
      value="Submit text"
      variant="primary"
      uiTransform={{ alignSelf: 'center', padding: '25px' }}
      onMouseDown={() => {
        handleSubmitText(currentValue)
        currentValue = ''
      }}
    />
  </UiEntity>
)

function handleSubmitText(value: string) {
  console.log('submitted value: ' + value)
  // fazer algo com o texto
}

💡 Tip: O exemplo acima define a valor propriedade do input text para uma variável. Com isso, você pode alterar o texto exibido simplesmente mudando a variável. Isso permite que você faça coisas como limpar o texto, alterar valores de placeholder ou até implementar funcionalidades de autocorreção.

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

• placeHolder: String para exibir antes do jogador começar a digitar. É útil fazer esse texto ser uma dica sobre o que ele deve escrever.

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

💡 Tip: Use um tom mais pálido da cor do texto que o jogador escreve.

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

  NOTE: The fontSize não é afetado pelo tamanho de sua entidade ou entidades pai.

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

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

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

• textAlign: Como o texto será alinhado com seu pai. Ele recebe um valor do `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 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 = 'you wrote: ' + e
        }}
        fontSize={35}
        placeholder={'type something'}
        placeholderColor={Color4.Gray()}
      />
      <Label value={currentTextString} fontSize={40} />
    </UiEntity>
)