UI 특수 유형

드롭다운과 입력 상자를 포함한 UI용 특수 엔티티 유형입니다.

특정한 특별한 엔터티 유형은 일부 특별한 종류의 상호작용을 허용합니다.

드롭다운

생성하세요 드롭다운 사용자가 목록에서 항목을 펼쳐 선택할 수 있도록 하는 엔터티.

하나의 드롭다운 엔터티는 최소한 다음 속성을 가져야 합니다:

• 옵션: 드롭다운이 펼쳐졌을 때 표시할 값입니다. 각 옵션에 대해 문자열 값을 가진 배열을 제공하세요. 배열의 첫 번째 값이 기본 옵션으로 표시됩니다.

• onChange: 드롭다운에서 값이 선택될 때마다 실행되는 함수이며,

다음과 같은 다른 구성 요소도 설정할 수 있습니다. 드롭다운 엔터티의 uiTransform처럼, 다른 UI 엔터티에서와 같이.

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="색상 선택"
        fontSize={18}
        color={textColor}
        uiTransform={{
          width: '140px',
          height: '40px',
        }}
      />
      <Dropdown
        options={[`Red`, `Blue`, `Green`]}
        onChange={selectOption}
        uiTransform={{
          width: '100px',
          height: '40px',
        }}
      />
    </UiEntity>
)

index.ts 파일:

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

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

📔 참고: 이 페이지의 다음 모든 스니펫은 여러분이 .ts 와 유사한 ReactEcsRenderer.setUiRenderer() 함수를 실행 중이라고 가정합니다.

입력 텍스트

하나의 Input 엔터티를 만들어 사용자가 텍스트를 입력할 수 있게 합니다. 플레이어는 이 상자를 먼저 클릭해야만 여기에 글을 쓸 수 있습니다.

다음은 Input 엔터티의 동작이 다음 속성들을 통해 관리됩니다:

• onSubmit: 플레이어가 Return/Enter 키를 누를 때 제공된 텍스트를 입력값으로 사용하여 실행되는 함수입니다. 텍스트 필드는 아닙니다 이때 자동으로 지워지지 않으므로, 직접 지워야 합니다(아래 예시를 참조하세요).

• onChange: 입력 텍스트의 값이 변경될 때마다 실행되는 함수입니다. 플레이어가 상자에 입력하는 동안 이 함수는 추가되거나 삭제된 각 문자마다 한 번씩 실행됩니다.

• disabled: 만약 true이면 플레이어는 입력 엔터티와 상호작용할 수 없습니다.

다음 예시는 onSubmit 를 사용해 제공된 텍스트를 콘솔에 기록합니다.

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={'무언가를 입력하세요'}
      placeholderColor={Color4.Black()}
      uiTransform={{
        width: '400px',
        height: '80px',
      }}
    </Input>
  </UiEntity>
)

제출용 버튼과 함께, 플레이어가 Enter/Return 키를 눌렀을 때의 onSubmit 이벤트도 처리하도록 제공하는 것이 좋은 방법입니다. 다음 예시는 이를 어떻게 할 수 있는지 보여줍니다.

📔 참고: 하지 아닙니다 바인딩하지 값 속성을 Input 플레이어가 입력하는 내용에 onChange를 직접 연결하지 마세요. 그러면 씬과 Explorer 사이에 왕복이 발생하여 빠르게 입력할 때 문자가 누락될 수 있습니다. 대신 값 을 빈 문자열로 유지하고, 입력 필드를 지우고 싶을 때만 변경하세요.

입력 필드를 지우려면 값 를 ' ' (공백 한 칸)으로 설정하세요. Explorer는 이를 비어 있는 것으로 처리하고 자리표시자 텍스트를 다시 활성화합니다. UI 함수는 매 프레임 실행되므로, 한 프레임 동안만 지우도록 플래그를 사용하세요.

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={'무언가를 입력하세요'}
        placeholderColor={Color4.Black()}
        value={inputValue}
        onChange={(value) => { inputText = value }}
        uiTransform={{
          height: '80px',
          margin: '15px',
        }}
      />
      <Button
        value="텍스트 제출"
        variant="primary"
        uiTransform={{ alignSelf: 'center', padding: '25px' }}
        onMouseDown={() => {
          console.log('submitted value: ' + inputText)
          inputText = ''
          clearInput = true
        }}
      />
    </UiEntity>
  )
}

다음 속성들도 텍스트 필드의 외형을 사용자 지정하는 데 사용할 수 있으며, 대부분은 Label 엔터티에 있는 것과 비슷합니다:

• placeholder: 플레이어가 아무것도 입력하기 전에 표시할 문자열입니다. 무엇을 써야 하는지에 대한 힌트로 이 텍스트를 사용하는 것이 유용합니다.

• placeholderColor: 자리표시자 텍스트에 사용할 색상으로, Color4.

💡 팁: 플레이어가 쓰는 텍스트 색보다 더 옅은 색조를 사용하세요.

• fontSize: 텍스트의 크기를 숫자로 나타낸 값입니다.

  참고: fontSize 는 자신의 엔터티나 부모 엔터티의 크기에 영향을 받지 않습니다.

• color: 플레이어가 쓰는 텍스트의 색상으로, Color4.

📔 참고: 반드시 placeholderColor.

• font: 사용할 글꼴입니다. 지원되는 값은 다음과 같습니다. - 'sans-serif' (기본값) - 'serif' - 'monospace'

• textAlign: 텍스트가 부모와 어떻게 정렬될지 지정합니다. `TextAlignType`의 값을 사용합니다. TextAlignType = 'top-left' | 'top-center' | 'top-right' | 'middle-left' | 'middle-center' | 'middle-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';

다음과 같은 다른 구성 요소도 설정할 수 있습니다. Input 엔터티의 uiTransform, OnMouseDown 처럼, 다른 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 = '작성한 내용: ' + e
        }}
        fontSize={35}
        placeholder={'무언가를 입력하세요'}
        placeholderColor={Color4.Gray()}
      />
      <Label value={currentTextString} fontSize={40} />
    </UiEntity>
)