Tipos especiales de UI

Tipos especiales de Entities para la UI, incluidos dropdowns y cuadros de entrada.

Hay ciertos tipos especiales de entity que permiten algunos tipos especiales de interacciones.

Desplegable

Crea una Desplegable entity para permitir a los usuarios expandir y seleccionar un elemento de una lista.

Una Desplegable entity debe tener al menos las siguientes propiedades:

• options: Qué valores mostrar cuando se expande el desplegable. Proporciona un array con un valor de cadena para cada opción. El primer valor del array se muestra como la opción predeterminada.

• onChange: Una función que se ejecuta cada vez que se selecciona un valor en el desplegable, usando

También puedes configurar otros componentes de la Desplegable entity, como un uiTransform, como en otras entidades de UI.

archivo 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="Selecciona un color"
        fontSize={18}
        color={textColor}
        uiTransform={{
          width: '140px',
          height: '40px',
        }}
      />
      <Dropdown
        options={[`Rojo`, `Azul`, `Verde`]}
        onChange={selectOption}
        uiTransform={{
          width: '100px',
          height: '40px',
        }}
      />
    </UiEntity>
)

archivo index.ts:

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

export function main() {
    ReactEcsRenderer.setUiRenderer(uiMenu)
}

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

Texto de entrada

Crea un Input entity Input para permitir a los usuarios escribir texto. Los jugadores primero deben hacer clic en este cuadro antes de poder escribir en él.

El comportamiento de la Input entity se gestiona mediante las siguientes propiedades:

• onSubmit: Una función que se ejecuta cuando el jugador pulsa Return/Enter, usando el texto proporcionado como entrada. El campo de texto no se borra automáticamente cuando esto sucede; debes borrarlo tú mismo (consulta el ejemplo de abajo).

• onChange: Una función que se ejecuta cada vez que cambia un valor en el texto de entrada. A medida que el jugador escribe en el cuadro, esta función se ejecuta una vez por cada carácter que se añade o se elimina.

• disabled: Si true, el jugador no podrá interactuar con la entidad Input.

El siguiente ejemplo usa onSubmit para registrar el texto proporcionado en la consola.

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('valor enviado: ' + value)
      }}
      fontSize={35}
      placeholder={'escribe algo'}
      placeholderColor={Color4.Black()}
      uiTransform={{
        width: '400px',
        height: '80px',
      }}
    ></Input>
  </UiEntity>
)

Es una buena práctica proporcionar tanto un botón para enviar como para manejar el onSubmit evento cuando el jugador pulsa la tecla Enter/Return. El siguiente ejemplo muestra cómo puedes hacerlo.

📔 Nota: Haz no vincula el value propiedad de la Input directamente a lo que el jugador escribe mediante onChange. Esto crea un ida y vuelta entre la escena y el Explorer que provoca que se pierdan caracteres al escribir rápido. En su lugar, mantén value como una cadena vacía y cámbialo solo cuando quieras limpiar el campo de entrada.

Para limpiar el campo de entrada, establece value en ' ' (un solo espacio). El Explorer lo trata como vacío y reactiva el texto del marcador de posición. Como la función de UI se ejecuta en cada frame, usa una bandera para aplicar la limpieza solo durante un 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('valor enviado: ' + inputText)
          inputText = ''
          clearInput = true
        }}
        fontSize={35}
        placeholder={'escribe 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('valor enviado: ' + inputText)
          inputText = ''
          clearInput = true
        }}
      />
    </UiEntity>
  )
}

Las siguientes propiedades también están disponibles para personalizar el aspecto del campo de texto, la mayoría similares a las presentes en Label entidades:

• placeholder: Cadena que se muestra antes de que el jugador empiece a introducir algo. Es útil hacer de este texto una pista sobre lo que debe escribir.

• placeholderColor: El color que se usará para el texto del marcador de posición, como un Color4.

💡 Consejo: Usa un tono más claro del color del texto que escribe el jugador.

• fontSize: El tamaño del texto, como un número.

  NOTA: El fontSize no se ve afectado por el tamaño de su entity o de sus entity padre.

• color: El color del texto que escribe el jugador, como un Color4.

📔 Nota: Asegúrate de usar un color diferente al placeholderColor.

• font: La fuente a usar. Los valores admitidos son: - 'sans-serif' (predeterminado) - 'serif' - 'monospace'

• textAlign: Cómo se alineará el texto con su padre. Toma un valor de `TextAlignType`. TextAlignType = 'top-left' | 'top-center' | 'top-right' | 'middle-left' | 'middle-center' | 'middle-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';

También puedes configurar otros componentes de la Input entity, como un uiTransform, OnMouseDown como en otras 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 = 'has escrito: ' + e
        }}
        fontSize={35}
        placeholder={'escribe algo'}
        placeholderColor={Color4.Gray()}
      />
      <Label value={currentTextString} fontSize={40} />
    </UiEntity>
)