Version: 2022.2
언어: 한국어
UXML 요소 LongField
UXML 요소 MaskField

UXML 요소 ListView

ListView는 항목 리스트에 연결하고 표시하는 세로로 스크롤할 수 있는 영역입니다.

참고:가로 및 세로 스크롤러 요소는 표준 UI 툴킷 스크롤러입니다.

ListView 바인딩

복잡한 데이터로 ListView를 생성하고 ListView를 시각적 요소에 바인딩하려면 다음을 수행합니다.

  • makeItembindItem을 사용하여 ListView를 데이터에 바인딩하고 적절한 콜백을 등록하며 필요에 따라 연결된 데이터 소스를 수정합니다.
  • unbindItem을 사용하여 ListView의 요소를 재활용하고 데이터의 바인딩을 해제합니다.
  • destroyItem을 사용하여 등록된 콜백을 지웁니다.

ListView와 ScrollView 비교

ScrollView 컨트롤을 사용하여 ListView를 사용하는 것과 동일한 기능을 생성할 수 있습니다.그러나 다음을 수행할 경우에는 ListView가 ScrollView보다 더 효율적입니다.

  • 리스트 항목 채우기
  • 항목 높이 관리
  • 오브젝트 바인딩 및 바인딩 해제
  • 페이지 채우기에 필요한 시각적 요소의 수 인스턴스화
  • 시각적 요소를 재활용하여 메모리 처리 최적화

항목 높이 설정

항목 높이가 콘텐츠 구동에 사용되는 방식을 변경하려면 VirtualizationMethod를 사용합니다.

  • VirtualizationMethod.FixedHeight는 모든 항목을 동일한 높이로 설정합니다.
  • VirtualizationMethod.DynamicHeight는 항목을 다양한 높이로 설정합니다.

스크롤 속도 컨트롤

ListView의 스크롤 속도를 컨트롤하려면 USS 빌트인 변수 --unity-metrics-single_line-height를 오버라이드합니다.기본값은 18px입니다.예시:

:root {
--unity-metrics-single_line-height:500px;
}

중요:파라미터 없이 CloneTree()를 사용하거나 Instantiate()를 사용하면 줄 높이가 전파되지 않도록 하는 TemplateContainer가 추가됩니다.대신 CloneTree(root)를 사용하십시오.

예제

​ ListView 사용 방법을 배우는 가장 좋은 방법은 예시를 사용해 보는 것입니다.

  • ListView 예시를 확인하려면 Unity에서 Window > UI Toolkit > Samples > ListView를 선택합니다.
  • 복합 리스트 뷰 생성:복잡한 데이터로 ListView를 생성하고 ListView를 시각적 요소에 바인딩합니다.
  • ListView로 리스트에 바인딩:토글 리스트를 생성하고 리스트를 GameSwitch 오브젝트의 기본 리스트에 바인딩합니다.

C# 기본 클래스 및 네임스페이스

C# 클래스:ListView
네임스페이스:UnityEngine.UIElements
기본 클래스:BaseListView

상속 UXML 속성

이 요소는 다음 속성을 해당 기본 클래스에서 상속합니다.

Name 타입 설명
binding-path string 바인드될 타겟 프로퍼티의 경로입니다.
fixed-item-height int 리스트에 있는 단일 항목의 높이(픽셀)입니다.

컬렉션 뷰를 작동하려면 virtualizationMethodFixedHeight로 설정된 경우 이 프로퍼티를 설정해야 합니다.virtualizationMethodDynamicHeight일 때 설정하면 항목이 배치되기 전에 필요한 항목 수와 스크롤 가능한 영역을 계산하는 데 도움이 되는 기본 높이로 사용됩니다.항목의 예상 최소 높이로 설정해야 합니다.
focusable boolean 요소에 포커스를 맞출 수 있으면 true입니다.
header-title string 이 프로퍼티는 showFoldoutHeader를 사용할 때 폴드아웃 헤더의 텍스트를 컨트롤합니다.
reorder-mode UIElements.ListViewReorderMode 이 프로퍼티는 리스트 뷰의 드래그 앤 드롭 모드를 컨트롤합니다.

기본값은 Simple입니다.이 프로퍼티를 Animated로 설정하면 Unity는 모든 항목 앞에 드래그 핸들을 추가하고 재정렬이 발생할 때 드래그 앤 드롭 조작으로 애니메이션이 있는 항목을 푸시합니다.여러 항목 재정렬은 Simple 드래그 모드에서만 지원됩니다.
reorderable boolean 사용자가 리스트 항목을 드래그하여 재정렬할 수 있는지를 나타내는 값을 가져오거나 설정합니다.

기본값은 false로, canStartDrag, setupDragAndDrop, dragAndDropUpdate, handleDrop을 구현할 때 사용자가 다른 뷰로 드래그하거나 다른 뷰에서 드래그할 수 있습니다.이 값을 true로 설정하면 사용자가 리스트의 항목을 재정렬할 수 있습니다.
selection-type UIElements.SelectionType 선택 타입을 컨트롤합니다.

기본값은 SelectionType.Single입니다.컬렉션 뷰를 설정하여 선택을 비활성화하면 모든 현재 선택이 해제됩니다.
show-add-remove-footer boolean 이 프로퍼티는 리스트 뷰에 바닥글을 추가할지를 컨트롤합니다.

기본값은 false입니다.이 프로퍼티가 true로 설정되어 있는 경우 Unity는 바닥글을 스크롤 뷰 아래에 추가합니다.이 바닥글에는 두 개의 버튼이 있습니다.하나는 “+” 버튼입니다.클릭하면 리스트 뷰 끝에 항목 하나가 추가됩니다.또 다른 하나는 “-” 버튼입니다.클릭하면 선택한 모든 항목이 제거되거나 아무것도 선택하지 않은 경우에는 마지막 항목이 제거됩니다.
show-alternating-row-backgrounds UIElements.AlternatingRowBackground 이 프로퍼티는 컬렉션 뷰 행의 배경 컬러를 번갈아 바꿀지를 컨트롤합니다.AlternatingRowBackground 열거형에서 값을 가져옵니다.
show-border boolean 컬렉션 뷰의 테두리를 표시하려면 이 프로퍼티를 활성화합니다.

true로 설정하면 컬렉션 뷰가 내부적으로 사용하는 ScrollView 주위에 테두리가 표시됩니다.
show-bound-collection-size boolean 이 프로퍼티는 리스트 뷰에 컬렉션 크기(항목 수)를 표시할지를 컨트롤합니다.

기본값은 true입니다.이 프로퍼티가 true로 설정된 경우 Unity는 컬렉션 크기를 리스트의 첫 번째 항목으로 표시하지만, 리스트 인덱스에 포함된 실제 리스트 항목이 되지는 않습니다.리스트 인덱스 0을 쿼리하는 경우 Unity는 컬렉션 크기가 아닌 실제 첫 번째 리스트 항목을 반환합니다.showFoldoutHeadertrue로 설정된 경우 헤더에 컬렉션 크기 필드가 대신 포함됩니다.이 프로퍼티는 데이터 소스가 올바르게 연결되었는지를 나타내므로 이 프로퍼티를 사용하여 ListView를 디버깅할 수 있습니다.프로덕션에서는 컬렉션 크기가 ListView에서 줄 항목으로 표시되는 경우가 거의 없습니다.

SA:UnityEditor.UIElements.BindingExtensions.Bind
show-foldout-header boolean 이 프로퍼티는 리스트 뷰에 헤더를 확장하거나 축소할 수 있는 폴드아웃 형태로 표시할지를 컨트롤합니다.

기본값은 false입니다.이 프로퍼티가 true로 설정된 경우 Unity는 리스트 뷰의 계층 구조에 폴드아웃을 추가하고 스크롤 뷰를 새로 생성된 폴드아웃 내부로 이동합니다.이 폴드아웃의 텍스트를 ListView의 headerTitle 프로퍼티를 통해 변경할 수 있습니다.showBoundCollectionSizetrue로 설정된 경우 헤더에는 필드를 리스트의 일부로 사용하는 대신 배열 크기를 컨트롤하는 TextField가 포함됩니다.
tabindex int 포커스 링에서 포커스를 맞출 수 있는 항목을 정렬하는 데 사용되는 정수입니다.0보다 크거나 같아야 합니다.
virtualization-method UIElements.CollectionVirtualizationMethod 스크롤 바가 표시될 때 이 컬렉션에 사용할 가상화 메서드입니다.CollectionVirtualizationMethod 열거형에서 값을 가져옵니다.

기본값은 FixedHeight입니다.고정 높이를 사용하는 경우 fixedItemHeight 프로퍼티를 지정합니다.고정 높이는 성능이 더 좋지만, 콘텐츠에 대한 유연성이 떨어집니다.DynamicHeight를 사용하면 컬렉션은 실제 높이가 계산될 때까지 기다립니다.동적 높이는 더 유연하지만, 성능이 떨어집니다.

또한 이 요소는 다음 속성을 VisualElement에서 상속합니다.

Name 타입 설명
content-container string 자식 요소가 추가되며, 일반적으로 요소 자체와 동일합니다.
name string 이 VisualElement의 이름입니다.

이 프로퍼티를 사용하면 특정 요소를 타게팅하는 USS 선택자를 작성할 수 있습니다.요소에 고유한 이름을 부여하는 것이 표준 관행입니다.
picking-mode UIElements.PickingMode mouseEvents 또는 IPanel.Pick 쿼리 중에 이 요소를 선택할 수 있는지를 결정합니다.
style string 이 요소의 스타일 오브젝트에 대한 레퍼런스입니다.

USS 파일에서 계산된 데이터 또는 C#에서 이 오브젝트에 작성된 인라인 스타일을 포함합니다.
tooltip string 사용자가 마우스를 요소 위에 잠시 놓은 후 정보 박스 안에 표시할 텍스트입니다.이는 에디터 UI에서만 지원됩니다.
usage-hints UIElements.UsageHints VisualElement에 대한 고수준의 의도된 사용 패턴을 지정하는 힌트 값 조합입니다.이 프로퍼티는 VisualElement가 아직 Panel에 포함되어 있지 않을 때만 설정할 수 있습니다.Panel에 포함되면 이 프로퍼티는 사실상 읽기 전용이 되며, 변경을 시도하면 예외가 발생합니다.적절한 UsageHints를 지정하면 시스템에서 예상하는 사용 패턴에 따라 특정 작업을 처리하거나 가속하는 방법에 대해 더 나은 결정을 내릴 수 있습니다.이러한 힌트는 동작이나 시각적 결과에는 영향을 주지 않으며 패널과 그 안의 요소의 전반적인 성능에만 영향을 줍니다.항상 적절한 UsageHints를 지정하는 것이 좋지만, 일부 UsageHints는 특정 조건(예: 타겟 플랫폼의 하드웨어 제한으로 인해)에서 내부적으로 무시될 수 있다는 점에 유의하십시오.
view-data-key string 보기 데이터 지속성에 사용됩니다(예: 트리 확장 상태, 스크롤 포지션, 줌 레벨).

이는 보기 데이터 스토어의 보기 데이터를 저장/로드하는 데 사용되는 키입니다.이 키를 설정하지 않으면 이 VisualElement에 대한 지속성이 비활성화됩니다.

USS 클래스

다음 표는 모든 C# 공용 프로퍼티 이름과 관련 USS 선택자의 리스트입니다.

C# 프로퍼티 USS 선택자 설명
ussClassName .unity-list-view ListView 요소의 USS 클래스명입니다.

Unity는 이 USS 클래스를 ListView 요소의 모든 인스턴스에 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 ListView에 영향을 줍니다.
itemUssClassName .unity-list-view__item ListView 요소에 있는 항목 요소의 USS 클래스명입니다.

Unity는 이 USS 클래스를 ListView가 포함된 모든 항목 요소에 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 항목 요소에 영향을 줍니다.
emptyLabelUssClassName .unity-list-view__empty-label ListView가 비어 있는 경우 표시되는 레이블의 USS 클래스명입니다.

Unity는 ListView가 비어 있는 경우 표시되는 레이블에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 빈 레이블에 영향을 줍니다.
reorderableUssClassName .unity-list-view__reorderable 순서 재지정 가능한 애니메이션화 ListView 요소의 USS 클래스명입니다.

Unity는 reorderModeAnimated로 설정된 경우 ListView 요소의 모든 인스턴스에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 ListView에 영향을 줍니다.
reorderableItemUssClassName .unity-list-view__reorderable-item 순서 재지정 가능한 애니메이션화 ListView에 있는 항목 요소의 USS 클래스명입니다.

Unity는 reorderModeAnimated로 설정된 경우 ListView의 모든 요소에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 요소에 영향을 줍니다.
reorderableItemContainerUssClassName .unity-list-view__reorderable-item__container 순서 재지정 가능한 애니메이션화 ListView에 있는 항목 컨테이너의 USS 클래스명입니다.

Unity는 reorderModeAnimated로 설정된 경우 ListView의 모든 항목 컨테이너에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 항목 컨테이너에 영향을 줍니다.
reorderableItemHandleUssClassName .unity-list-view__reorderable-handle 순서 재지정 가능한 애니메이션화 ListView에 있는 드래그 핸들의 USS 클래스명입니다.

Unity는 reorderModeAnimated로 설정된 경우 ListView의 드래그 핸들에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 드래그 핸들에 영향을 줍니다.
reorderableItemHandleBarUssClassName .unity-list-view__reorderable-handle-bar 순서 재지정 가능한 애니메이션화 ListView에 있는 드래그 핸들 바의 USS 클래스명입니다.

Unity는 reorderModeAnimated로 설정된 경우 ListView의 모든 드래그 핸들 바에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 드래그 핸들 바에 영향을 줍니다.
footerUssClassName .unity-list-view__footer ListView 바닥글의 USS 클래스명입니다.

Unity는 ListView의 바닥글 요소에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 ListView에 영향을 줍니다.
foldoutHeaderUssClassName .unity-list-view__foldout-header ListView의 폴드아웃 헤더에 대한 USS 클래스명입니다.

Unity는 ListView의 폴드아웃 요소에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 폴드아웃에 영향을 줍니다.
arraySizeFieldUssClassName .unity-list-view__size-field 폴드아웃 헤더가 활성화된 경우 ListView의 크기 필드에 대한 USS 클래스명입니다.

Unity는 showFoldoutHeadertrue로 설정된 경우 ListView의 크기 필드 요소에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 크기 필드에 영향을 줍니다.
listViewWithHeaderUssClassName .unity-list-view--with-header 폴드아웃 헤더가 활성화된 경우 ListView의 USS 클래스명입니다.

Unity는 showFoldoutHeadertrue로 설정된 경우 ListView에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 리스트에 영향을 줍니다.
listViewWithFooterUssClassName .unity-list-view--with-footer 추가/제거 바닥글이 활성화된 경우 ListView의 USS 클래스명입니다.

Unity는 showAddRemoveFootertrue로 설정된 경우 ListView에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 리스트에 영향을 줍니다.
scrollViewWithFooterUssClassName .unity-list-view__scroll-view--with-footer 추가/제거 바닥글이 활성화된 경우 스크롤 뷰의 USS 클래스명입니다.

Unity는 showAddRemoveFootertrue로 설정된 경우 BaseListView의 스크롤 뷰에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 리스트에 영향을 줍니다.
ussClassName .unity-collection-view BaseVerticalCollectionView 요소의 USS 클래스명입니다.

Unity는 이 USS 클래스를 BaseVerticalCollectionView 요소의 모든 인스턴스에 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 BaseVerticalCollectionView에 영향을 줍니다.
borderUssClassName .unity-collection-view--with-border 테두리가 있는 BaseVerticalCollectionView 요소의 USS 클래스명입니다.

Unity는 인스턴스의 BaseVerticalCollectionView.showBorder 프로퍼티가 true로 설정된 경우 BaseVerticalCollectionView 요소의 인스턴스에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 이러한 모든 BaseVerticalCollectionView에 영향을 줍니다.
itemUssClassName .unity-collection-view__item BaseVerticalCollectionView 요소에 있는 항목 요소의 USS 클래스명입니다.

Unity는 이 USS 클래스를 BaseVerticalCollectionView가 포함된 모든 항목 요소에 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 항목 요소에 영향을 줍니다.
dragHoverBarUssClassName .unity-collection-view__drag-hover-bar 드래그 호버 바의 USS 클래스명입니다.

Unity는 사용자가 리스트의 항목을 드래그할 때 표시되는 바에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 BaseVerticalCollectionView에 영향을 줍니다.
dragHoverMarkerUssClassName .unity-collection-view__drag-hover-marker 뎁스를 나타내는 데 사용되는 드래그 호버 원형 마커의 USS 클래스명입니다.

Unity는 사용자가 리스트의 항목을 드래그할 때 표시되는 바에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 BaseVerticalCollectionView에 영향을 줍니다.
itemDragHoverUssClassName .unity-collection-view__item--drag-hover 드래그 호버의 항목 요소에 적용되는 USS 클래스명입니다.

Unity는 드래그할 때 이 USS 클래스를 항목 요소에 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 BaseVerticalCollectionView 항목에 영향을 줍니다.
itemSelectedVariantUssClassName .unity-collection-view__item--selected BaseVerticalCollectionView에 있는 선택한 항목 요소의 USS 클래스명입니다.

Unity는 BaseVerticalCollectionView에 있는 선택한 모든 요소에 이 USS 클래스를 추가합니다.BaseVerticalCollectionView.selectionType 프로퍼티는 요소를 0개, 1개 또는 그 이상 선택할 수 있는지를 결정합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 BaseVerticalCollectionView 항목에 영향을 줍니다.
itemAlternativeBackgroundUssClassName .unity-collection-view__item--alternative-background BaseVerticalCollectionView에 있는 홀수 행의 USS 클래스명입니다.

Unity는 BaseVerticalCollectionView.showAlternatingRowBackgrounds 프로퍼티가 ContentOnly 또는 All로 설정되면 BaseVerticalCollectionView의 모든 홀수 항목에 이 USS 클래스를 추가합니다.showAlternatingRowBackgrounds 프로퍼티를 이 값 중 하나로 설정하면 홀수 항목은 짝수 항목과 다른 배경 컬러로 표시됩니다.이 USS 클래스는 홀수 항목을 짝수 항목과 구분하는 데 사용됩니다.showAlternatingRowBackgrounds 프로퍼티가 None으로 설정되면 USS 클래스가 추가되지 않으며 이를 필요로 하는 모든 스타일링이나 동작이 무효화됩니다.
listScrollViewUssClassName .unity-collection-view__scroll-view BaseVerticalCollectionView에 있는 스크롤 뷰의 USS 클래스명입니다.

Unity는 BaseVerticalCollectionView의 스크롤 뷰에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 BaseVerticalCollectionView 스크롤 뷰에 영향을 줍니다.
disabledUssClassName .unity-disabled 비활성화된 로컬 요소의 USS 클래스명입니다.

또한 인스펙터 또는 UI 툴킷 디버거의 매칭 선택자 섹션을 사용하여 해당 계층 구조의 모든 레벨에서 VisualElement 컴포넌트에 영향을 주는 USS 선택자를 확인할 수도 있습니다.

추가 리소스

UXML 요소 LongField
UXML 요소 MaskField