> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-ko/sdk7/2d-ui/ui_text.md).

# UI 텍스트

UI 엔티티에 텍스트를 씁니다.

텍스트를 UI에 추가하려면 다음을 생성하세요 `Label` 엔티티를 사용해 플레이어 카메라 위치에서 앞으로 레이를 추적합니다.

하나의 `Label` 엔터티에는 다음과 같이 구성할 수 있는 필드가 있습니다:

* `value`: 표시할 문자열
* `fontSize`: 텍스트의 크기로, 숫자입니다.

  > 참고: `fontSize` 는 해당 엔터티나 상위 엔터티의 크기에 영향을 받지 않습니다.
* `color`: 텍스트의 색상, 다음 형식으로 [Color4](/creator/content-creator-ko/sdk7/3d/color-types.md).
* `font`: 사용할 글꼴. 지원되는 값은 다음과 같습니다:
  * `'serif'`
  * `'sans-serif'` *(기본값)*
  * `'monospace'`
* `textAlign`: 텍스트가 부모와 어떻게 정렬될지 설정합니다. 다음의 값 중 하나를 사용합니다. `TextAlignType` 형식. TextAlignType = 'top-left' | 'top-center' | 'top-right' | 'middle-left' | 'middle-center' | 'middle-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
* `textWrap`: 텍스트가 최대 너비를 초과하지 않도록 줄 바꿈을 사용할지 설정합니다. 기본값은 켜져 있습니다(`'wrap'`), 비활성화하려면 값을 전달하세요 `'nowrap'`.

{% hint style="warning" %}
**📔 참고**: `fontSize` 는 해당 엔터티나 상위 엔터티의 크기에 영향을 받지 않습니다.
{% endhint %}

하나의 `Label` 엔터티에는 다른 유형의 UI 엔터티에서 볼 수 있는 다른 공통 컴포넌트도 포함할 수 있습니다. 예: `uiTransform` 과 `uiBackground`.

***ui.tsx 파일:***

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

export const uiMenu = () => (
	<UiEntity uiTransform={{ width: 'auto', height: 'auto' }}>
		<Label
			value="이것은 레이블입니다"
			color={Color4.Red()}
			fontSize={29}
			font="sans-serif"
			textAlign="top-left"
		/>
	</UiEntity>
)
```

***index.ts 파일:***

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

export function main() {
    ReactEcsRenderer.setUiRenderer(uiMenu, { virtualWidth: 1920, virtualHeight: 1080 })
}
```

{% hint style="warning" %}
**📔 참고**: 이 페이지의 아래 모든 코드 조각은 다음이 있다고 가정합니다: `.ts` 위와 비슷한 `ReactEcsRenderer.setUiRenderer()` 함수.
{% endhint %}

한 줄의 텍스트가 할당된 너비나 컨테이너의 최대 너비에 맞기에는 너무 길면, 텍스트는 다음 줄로 이어집니다. 다음의 값을 변경하면 이를 비활성화할 수 있습니다. `textWrap` 속성을 `'nowrap'`.

또한 명시적으로 다음을 추가하여 줄 바꿈을 강제할 수도 있습니다. `\n` 를 문자열에.

```ts
import { UiEntity, Label, ReactEcs } from '@dcl/sdk/react-ecs'

export const uiMenu = () => (
	<UiEntity uiTransform={{ width: 700, height: 400 }}>
		<Label 
			value="안녕하세요 세계!\n이 다른 부분은 꽤 깁니다. 아마 한 줄에 들어가지 않을 것이므로, 어딘가에서 줄 바꿈이 포함될 것입니다.\n네 번째 줄"
			textWrap= {`nowrap`} 
		/>
	</UiEntity>
)
```

명시적인 `height` 또는 `width` 가 설정되지 않은 `uiTransform` 경우 컨테이너는 값 `auto`를 사용합니다. 이는 모든 텍스트에 맞게 조정됩니다. 다음을 설정할 수 있습니다. `maxWidth` 와 하나의 `maxHeight` 를 사용하여 특정 한도를 초과하지 않도록 할 수 있습니다. 또한 다음을 사용할 수도 있습니다. `minWidth` 과 `minHeight` 를 사용하여 텍스트가 더 짧더라도 컨테이너가 너무 작아지지 않도록 합니다.

{% hint style="warning" %}
**📔 참고**: 텍스트의 자동 맞춤에 의존하지 마세요. 다음이 차지하는 공간은 `Label` 크기를 지정하지 않았을 때 차지하는 공간은 탐색기마다 다릅니다. Bevy 기반 탐색기는 렌더링된 텍스트를 측정해 그에 맞게 배치합니다. Unity 탐색기는 높이를 거의 주지 않지만 글자는 여전히 그리므로, 쌓인 레이블이 서로 겹치고 텍스트 크기로 정해진 부모는 아무것도 없는 것처럼 축소됩니다.

모든 `Label` 에 명시적인 `width` **과** `height` 를 `uiTransform`에 지정하고, 레이블을 쌓는 모든 컨테이너에는 명시적인 높이를 지정하세요. 줄 바꿈 텍스트의 경우 줄 수에 맞게 높이를 정하세요. 예를 들어 `fontSize: 20` 에는 약 `height: 60`.

가 필요합니다.
{% endhint %}

## UI 텍스트에 이모지를 사용하지 마세요

어떤 `Label` 또는 `Button` `value`, `uiText.value`, `Input` `placeholder`, 그리고 `드롭다운` 옵션을 제공합니다.

SDK에는 이모지 글리프가 포함되어 있지 않습니다. 이모지가 표시되는지는 각 탐색기에 번들로 포함된 글꼴에 따라 달라지며, Unity 탐색기에는 아예 없으므로 문자는 빈 상자로 나오거나 완전히 사라집니다. 화살표나 박스 그리기 문자 같은 다른 장식용 유니코드에도 같은 주의가 적용됩니다.

그림이 있는 레이블은 대신 아트를 제공하세요: 작은 `UiEntity` 텍스트 옆에 이미지를 배치하고, 다음을 사용하세요. `uiBackground` 및 `텍스처`. 참고: [UI 배경](/creator/content-creator-ko/sdk7/2d-ui/ui_background.md).

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

export const uiMenu = () => (
	<UiEntity
		uiTransform={{
			minWidth: 100,
			maxWidth: 300,
			height: 'auto',
			alignSelf: 'center',
			padding: 10,
		}}
		uiBackground={{
			color: Color4.Red(),
		}}
		uiText={{
			value: 'Hello world!',
			fontSize: 18,
		}}
	/>
)
```

## 반응형 텍스트 크기

다음을 사용하세요 `scaleFontSize()` 함수는 플레이어의 화면 크기에 맞춰 조정되는 글꼴 값을 제공합니다. 다음을 설정할 때 `fontSize` 속성에는 단일 숫자 대신 이 함수를 전달하세요.

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

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 'auto',
      height: 'auto',
      alignSelf: 'center',
      padding: 10,
    }}
    uiText={{
      value: 'Hello world!',
      fontSize: scaleFontSize(15)
    }}
  />
)
```

이 `scaleFontSize()` 함수는 두 개의 매개변수를 필요로 합니다:

* `fontSize`: 사용할 기본 글꼴 크기.
* `scaleUnit` *(선택 사항)*: 스케일링 계수. 이는 텍스트를 화면 너비 또는 높이를 기준으로 조정할지와, 얼마나 조정할지를 결정합니다. 기본값: `0.39` (숫자이며, 따라서 다음에 대한 상대값으로 해석됩니다. *width*). 값은 다음과 같습니다:
  * *숫자*: 단순한 숫자. 이 경우 다음에 대한 상대값으로 해석됩니다. *width*
  * *다음으로 끝나는 문자열 **vw***: 이렇게 하면 숫자가 뷰 너비에 상대적이 됩니다. 예: `"0.8vw"`
  * *다음으로 끝나는 문자열 **vh***: 이렇게 하면 숫자가 뷰 높이에 상대적이 됩니다. 예: `"0.8vh"`

{% hint style="info" %}
**💡 팁**이 함수는 CSS의 `calc()` 함수.
{% endhint %}

의 값은 `scaleUnit` 창 너비 또는 높이의 백분율입니다. 따라서 `scaleUnit` 의 `"100vw"` 는 화면 너비의 100%이고, 값 `"0.5vw"` 는 화면 너비의 0.5%입니다.

다음 공식은 `scaleFontSize()` 이어지며, 화면 너비 또는 높이에 다음을 곱합니다. `scaleUnit`에, 그리고 여기에 `fontSize` 첫 번째 매개변수로 전달된 값을 더합니다.

```ts
final font = fontSize + (screen width * scaleUnit / 100)
```

예를 들어, 아래 스니펫은 `scaleUnit` 0.8의 값을 사용합니다. 화면 너비가 *1280px*이면, 이는 다음 크기의 텍스트를 생성합니다. **25.24**다음 식을 따른 결과입니다. `15 + (1280 * 0.8 / 100)`.

{% hint style="warning" %}
**📔 참고**: `scaleFontSize()` 는 다음을 반환합니다. **number**따라서 결과는 *가상* 픽셀 단위의 크기입니다 — 이는 여전히 [UI 스케일 팩터](/creator/content-creator-ko/sdk7/2d-ui/onscreen-ui.md#screen-virtual-scale) 에 곱해진 후 그려집니다. 위 예시에서는 기본 `1920x1080` 가상 화면과 너비 1280px의 캔버스를 사용하면 스케일 계수는 `1280 / 1920 = 0.667`이며, 따라서 텍스트는 약 16.8px로 렌더링됩니다. 가상 화면을 무시하고 캔버스를 기준으로 직접 측정되는 글꼴 크기를 원한다면, 다음을 `vw`/`vh` **문자열** 에 바로 `fontSize` 대신 전달하세요 — 예: `fontSize: '1.8vh'`.
{% endhint %}

```ts
import { scaleFontSize } from '@dcl/sdk/react-ecs'
import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 'auto',
      height: 'auto',
      alignSelf: 'center',
      padding: 10,
    }}
    uiText={{
      value: 'Hello world!',
      fontSize: scaleFontSize(15, 0.8)
    }}
  />
)
```

{% hint style="info" %}
**💡 팁**: 테스트할 다른 화면 크기가 없다면 Web Explorer를 사용하고 미리보기를 실행하는 창의 크기를 조정해 볼 수 있습니다. 창을 변경할 때마다 텍스트가 즉시 조정됩니다.
{% endhint %}

다음의 대안으로 `scaleFontSize()`, 다음을 전달하세요 `vw`/`vh` 문자열을 직접 다음으로 `fontSize` — 예: `fontSize: '1.8vh'` — 이는 캔버스를 기준으로 텍스트 크기를 정하고 UI 스케일 계수는 완전히 무시합니다. 하지 **아닙니다** 다음에서 직접 계산한 계수로 글꼴 크기를 곱하지 마세요 `UiCanvasInformation`: SDK가 이미 하나를 적용합니다. 다음을 보세요 [반응형 UI 크기](/creator/content-creator-ko/sdk7/2d-ui/ui-positioning.md#responsive-ui-size).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-ko/sdk7/2d-ui/ui_text.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.