UXML 요소 ListView

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

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

ListView와 ScrollView 비교

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

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

항목 높이 설정

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

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

예제

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

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

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

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

Inherited attributes

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

Name	타입	설명
`binding-path`	`string`	바인드될 타겟 프로퍼티의 경로입니다.
`fixed-item-height`	`int`	The height of a single item in the list, in pixels. This property must be set when using the `virtualizationMethod` is set to `FixedHeight`, for the collection view to function.
`focusable`	`boolean`	요소에 포커스를 맞출 수 있으면 true입니다.
`header-title`	`string`	이 프로퍼티는 `showFoldoutHeader`를 사용할 때 폴드아웃 헤더의 텍스트를 컨트롤합니다.
`reorder-mode`	`UIElements.ListViewReorderMode`	This property controls the drag and drop mode for the list view. The default values if `Simple`. When this property is set to `Animated`, Unity adds drag handles in front of every item and the drag and drop manipulation will push items with an animation as the reordering happens. Multiple item reordering is only supported with the `Simple` drag mode.
`reorderable`	`boolean`	Gets or sets a value that indicates whether the user can drag list items to reorder them. The default values is `false`. Set this value to `true` to allow the user to drag and drop the items in the list. The collection view provides a default controller to allow standard behavior. It also automatically handles reordering the items in the data source.
`selection-type`	`UIElements.SelectionType`	선택 타입을 컨트롤합니다. 기본값은 `SelectionType.Single`입니다.컬렉션 뷰를 설정하여 선택을 비활성화하면 모든 현재 선택이 해제됩니다.
`show-add-remove-footer`	`boolean`	This property controls whether a footer will be added to the list view. The default values if `false`. When this property is set to `true`, Unity adds a footer under the scroll view. This footer contains two buttons: A “+” button. When clicked, adds a single item at the end of the list view. A “-” button. When clicked, removes all selected items, or the last item if none are selected.
`show-alternating-row-backgrounds`	`UIElements.AlternatingRowBackground`	이 프로퍼티는 컬렉션 뷰 행의 배경 컬러를 번갈아 바꿀지를 컨트롤합니다.`AlternatingRowBackground` 열거형에서 값을 가져옵니다.
`show-border`	`boolean`	컬렉션 뷰의 테두리를 표시하려면 이 프로퍼티를 활성화합니다. true로 설정하면 컬렉션 뷰가 내부적으로 사용하는 ScrollView 주위에 테두리가 표시됩니다.
`show-bound-collection-size`	`boolean`	This property controls whether the list view displays the collection size (number of items). The default values if `true`. When this property is set to `true`, Unity displays the collection size as the first item in the list, but does not make it an actual list item that is part of the list index. If you query for list index 0, Unity returns the first real list item, and not the collection size. If `showFoldoutHeader` is set to `true`, the collection size field will be included in the header instead. This property is usually used to debug a ListView, because it indicates whether the data source is linked correctly. In production, the collection size is rarely displayed as a line item in a ListView. SA: `UnityEditor.UIElements.BindingExtensions.Bind`
`show-foldout-header`	`boolean`	This property controls whether the list view will display a header, in the form of a foldout that can be expanded or collapsed. The default values if `false`. When this property is set to `true`, Unity adds a foldout in the hierarchy of the list view and moves the scroll view inside that newly created foldout. The text of this foldout can be changed with `headerTitle` property on the ListView. If `showBoundCollectionSize` is set to `true`, the header will include a TextField to control the array size, instead of using the field as part of the list.
`tabindex`	`int`	포커스 링에서 포커스를 맞출 수 있는 항목을 정렬하는 데 사용되는 정수입니다.0보다 크거나 같아야 합니다.
`virtualization-method`	`UIElements.CollectionVirtualizationMethod`	The virtualization method to use for this collection when a scroll bar is visible. Takes a value from the `CollectionVirtualizationMethod` enum. The default values is `FixedHeight`. When using fixed height, you need to specify the `fixedItemHeight` property. Fixed height is more performant but offers less flexibility on content. When using `DynamicHeight`, the collection will wait for the actual height to be computed. Dynamic height is more flexible but less performant.

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

Name	타입	설명
`content-container`	`string`	child elements are added to this element, usually this
`name`	`string`	이 VisualElement의 이름입니다. 이 프로퍼티를 사용하면 특정 요소를 타게팅하는 USS 선택자를 작성할 수 있습니다.요소에 고유한 이름을 부여하는 것이 표준 관행입니다.
`picking-mode`	`UIElements.PickingMode`	mouseEvents 또는 `IPanel.Pick` 쿼리 중에 이 요소를 선택할 수 있는지를 결정합니다.
`style`	`string`	이 요소의 스타일 오브젝트에 대한 레퍼런스입니다. USS 파일에서 계산된 데이터 또는 C#에서 이 오브젝트에 작성된 인라인 스타일을 포함합니다.
`tooltip`	`string`	Text to display inside an information box after the user hovers the element for a small amount of time.
`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는 `reorderMode`가 `Animated`로 설정된 경우 ListView 요소의 모든 인스턴스에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 ListView에 영향을 줍니다.
`reorderableItemUssClassName`	`.unity-list-view__reorderable-item`	순서 재지정 가능한 애니메이션화 ListView에 있는 항목 요소의 USS 클래스명입니다. Unity는 `reorderMode`가 `Animated`로 설정된 경우 ListView의 모든 요소에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 요소에 영향을 줍니다.
`reorderableItemContainerUssClassName`	`.unity-list-view__reorderable-item__container`	순서 재지정 가능한 애니메이션화 ListView에 있는 항목 컨테이너의 USS 클래스명입니다. Unity는 `reorderMode`가 `Animated`로 설정된 경우 ListView의 모든 항목 컨테이너에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 항목 컨테이너에 영향을 줍니다.
`reorderableItemHandleUssClassName`	`.unity-list-view__reorderable-handle`	순서 재지정 가능한 애니메이션화 ListView에 있는 드래그 핸들의 USS 클래스명입니다. Unity는 `reorderMode`가 `Animated`로 설정된 경우 ListView의 드래그 핸들에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 드래그 핸들에 영향을 줍니다.
`reorderableItemHandleBarUssClassName`	`.unity-list-view__reorderable-handle-bar`	순서 재지정 가능한 애니메이션화 ListView에 있는 드래그 핸들 바의 USS 클래스명입니다. Unity는 `reorderMode`가 `Animated`로 설정된 경우 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는 `showFoldoutHeader`가 `true`로 설정된 경우 ListView의 크기 필드 요소에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 크기 필드에 영향을 줍니다.
`listViewWithHeaderUssClassName`	`.unity-list-view--with-header`	폴드아웃 헤더가 활성화된 경우 ListView의 USS 클래스명입니다. Unity는 `showFoldoutHeader`가 `true`로 설정된 경우 ListView에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 리스트에 영향을 줍니다.
`listViewWithFooterUssClassName`	`.unity-list-view--with-footer`	추가/제거 바닥글이 활성화된 경우 ListView의 USS 클래스명입니다. Unity는 `showAddRemoveFooter`가 `true`로 설정된 경우 ListView에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 리스트에 영향을 줍니다.
`scrollViewWithFooterUssClassName`	`.unity-list-view__scroll-view--with-footer`	The USS class name for scroll view when add/remove footer is enabled. Unity adds this USS class to ListView’s scroll view when `showAddRemoveFooter` is set to `true`. Any styling applied to this class affects every list located beside, or below the stylesheet in the visual tree.
`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`	The USS class name of the drag hover bar. Unity adds this USS class to the bar that appears when an item element is dragged. The `BaseVerticalCollectionView.reorderable` property must be true in order for items to be dragged. Any styling applied to this class affects every BaseVerticalCollectionView located beside, or below the stylesheet in the visual tree.
`itemDragHoverUssClassName`	`.unity-collection-view__item--drag-hover`	The USS class name applied to an item element on drag hover. Unity adds this USS class to the list element that is dragged. The `BaseVerticalCollectionView.reorderable` property must be set to true for items to be draggable. Any styling applied to this class affects every BaseVerticalCollectionView item located beside, or below the stylesheet in the visual tree.
`itemSelectedVariantUssClassName`	`.unity-collection-view__item--selected`	BaseVerticalCollectionView에 있는 선택한 항목 요소의 USS 클래스명입니다. Unity는 BaseVerticalCollectionView에 있는 선택한 모든 요소에 이 USS 클래스를 추가합니다.`BaseVerticalCollectionView.selectionType` 프로퍼티는 요소를 0개, 1개 또는 그 이상 선택할 수 있는지를 결정합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 BaseVerticalCollectionView 항목에 영향을 줍니다.
`itemAlternativeBackgroundUssClassName`	`.unity-collection-view__item--alternative-background`	The USS class name for odd rows in the BaseVerticalCollectionView. Unity adds this USS class to every odd-numbered item in the BaseVerticalCollectionView when the `BaseVerticalCollectionView.showAlternatingRowBackground` property is set to `ContentOnly` or `All`. When the `showAlternatingRowBackground` property is set to either of those values, odd-numbered items are displayed with a different background color than even-numbered items. This USS class is used to differentiate odd-numbered items from even-numbered items. When the `showAlternatingRowBackground` property is set to `None`, the USS class is not added, and any styling or behavior that relies on it’s invalidated.
`listScrollViewUssClassName`	`.unity-collection-view__scroll-view`	BaseVerticalCollectionView에 있는 스크롤 뷰의 USS 클래스명입니다. Unity는 BaseVerticalCollectionView의 스크롤 뷰에 이 USS 클래스를 추가합니다.이 클래스에 적용된 모든 스타일링은 시각적 트리의 스타일시트 옆이나 아래에 있는 모든 BaseVerticalCollectionView 스크롤 뷰에 영향을 줍니다.
`disabledUssClassName`	`.unity-disabled`	비활성화된 로컬 요소의 USS 클래스명입니다.

You can also use the Matching Selectors section in the Inspector or the UI Toolkit Debugger to see which USS selectors affect the components of the visual element at every level of its hierarchy.

추가 리소스

ScrollView

UXML 요소 LongField

UXML 요소 MaskField