MultiColumnListView
Contains descriptions of columns. Must be a child of a parent that supports it, such as MultiColumnListView or MultiColumnTreeView.
読み終わるまでの所要時間 5 分最終更新 1ヶ月前
A MultiColumnListView is a UI control commonly used to display tabular or grid-like data with multiple columns. It allows you to present data in a structured format, where each row represents an item or entry, and each column represents a specific attribute or property of that item.
MultiColumnListView example
Create a MultiColumnListView
You can create a MultiColumnListView with UXML and C#. The following C# example creates a MultiColumnListView with two columns:
var multiColumnListView = new MultiColumnListView();multiColumnListView.columns.Add(new Column { title = "Name", width = 20 });multiColumnListView.columns.Add(new Column { title = "Power", width = 80 });
Refresh the collection view
In general, call the or method—these methods only refresh the collection view and are less expensive. If you call , the collection view is completely rebuilt, which can be expensive.
RefreshItemsRefreshItemRebuildHowever, you must call in the following cases:
Rebuild- You change the type of the data source, such as changing from a to a
List<float>.List<Vector3>
- You make changes to or
Column.makeCell.Column.destroyCell
Bind the MultiColumnListView to data
You can bind the MultiColumnListView to a data source, and automatically populate the rows and columns based on the provided data.
The following example demonstrates how to bind a MultiColumnListView to a SerializedObject. For an example of runtime binding, refer to Bind ListView to a list with runtime binding.
If you have a ScriptableObject with the following structure:
[Serializable]public class Move{ public string name; public int power;}[Serializable]public class Monster{ public string name; public List<Move> moves;}public class MonstersTeam : ScriptableObject{ public List<Monster> monstersList;}
You can bind a MultiColumnListView to the ScriptableObject with the following code:
var multiColumnListView = new MultiColumnListView{ bindingPath = "monstersList", showBoundCollectionSize = false, virtualizationMethod = CollectionVirtualizationMethod.DynamicHeight};multiColumnListView.columns.Add(new Column { bindingPath = "name", title = "Name", stretchable = true });multiColumnListView.columns.Add(new Column { bindingPath = "moves", title = "Moves", stretchable = true });var so = new SerializedObject(monstersTeam);multiColumnListView.Bind(so);
This outputs the following view:
The MultiColumnListView with the Name and Moves columns
To make the nested list a MultiColumnListView, change in the Moves column:
makeCellvar multiColumnListView = new MultiColumnListView{ bindingPath = "monstersList", showBoundCollectionSize = false, virtualizationMethod = CollectionVirtualizationMethod.DynamicHeight};multiColumnListView.columns.Add(new Column { bindingPath = "name", title = "Name", stretchable = true });multiColumnListView.columns.Add(new Column { bindingPath = "moves", title = "Moves", stretchable = true, makeCell = () => { var movesMultiColumnListView = new MultiColumnListView { showBoundCollectionSize = false, virtualizationMethod = CollectionVirtualizationMethod.DynamicHeight, }; movesMultiColumnListView.columns.Add(new Column { bindingPath = "name", title = "Name", stretchable = true }); movesMultiColumnListView.columns.Add(new Column { bindingPath = "power", title = "Power", stretchable = true }); return movesMultiColumnListView; }}); var so = new SerializedObject(monstersTeam);multiColumnListView.Bind(so);
This outputs the following view:
The MultiColumnListView with the updated Moves Column
Sort the MultiColumnListView
You can enable sorting for MultiColumnListView using a default algorithm, or implementing custom algorithm if the default sorting operation isn't fast enough to meet your needs.
Once the sorting is enabled, to sort by a single column, click the column headers. To sort multiple columns, hold down the Ctrl key (macOS: Cmd) and click. To disable sorting, hold down the Shift key and click.
Default sorting
To enable sorting using the default algorithm, set the attribute to , and implement the to compare two items by their index in the source.
sortingModeColumnSortingMode.DefaultColumn.comparisonFor an example, refer to a MultiColumnListView default sorting example.
Custom sorting
To implement custom sorting, set the attribute to , and implement the callback. In the callback, use to reorder your list accordingly and trigger a once the items' source has been updated.
sortingModeColumnSortingMode.CustomcolumnSortingChangedsortColumnsRefreshItems()The attribute is the current state of sorted columns: it lists the columns in the order in which they're sorted. If you sort by column 1, then column 2, then column 3, the list is [1, 2, 3]. If you sort by column 3, then column 2, then column 1, the list is [3, 2, 1].
sortColumnssortedColumnssortedColumnsImplement drag-and-drop operations for MultiColumnListView
Drag-and-drop is a common feature in UI design. To implement the drag-and-drop operations, override the following methods:
- To enable dragging items, override .
canStartDrag - To set which items are dragged, override .
setupDragAndDrop - To get item status changes, override . You can perform certain actions based on the drag position or other conditions.
dragAndDropUpdate - To control the drag-and-drop behavior, override .
handleDrop
During the drag-and-drop operation, you can enable the reordering of items by dragging. To enable, set the attribute to in UI Builder, UXML, and C#.
reorderabletrueRefer to Create a drag-and-drop list and tree views between windows for an example.
MultiColumnListView FAQs
The following are some frequently asked questions about the MultiColumnListView control.
Can I get the list of rows that are visible in the view?
There are no dedicated APIs for this. You can use UQuery to retrieve the elements of interest.
Is it mandatory for any of the overridden functions of a view controller to call ?
base.MethodCall this method only if you want to extend its default behavior.
I’ve added a Toggle to my row. Why doesn’t the selection jump to that row when the user selects it?
By default, the row is selected only if the mouse down event is not consumed by the row's contents. In this case, your Toggle stops the event propagation. To fix this, register a callback with on the Toggle to call .
PointerDownEventTrickleDownSetSelectionHow do I receive a callback when a user changes their selection in the view?
It is recommended to use the callback to retrieve data by index when needed. While you can also use , be aware that it returns a list of objects, which can cause boxing allocations when used with value types.
selectedIndicesChangedselectionChangedCan I get the indices of the rows that are visible on the screen?
There are no dedicated APIs for this. You can use and to track the indices on one of the columns.
column.bindCellcolumn.unbindCellCan I have a horizontal MultiColumnListView?
The MultiColumnListView control doesn't support horizontal layout and virtualization. It's recommended to use a ScrollView with to layout elements horizontally. However, applying this to a MultiColumnListView breaks virtualization.
flex-direction: rowExamples
The following UXML example creates a MultiColumnListView:
<UXML xmlns="UnityEngine.UIElements"> <MultiColumnListView class="the-uxml-multi-column-listview" fixed-item-height="20"> <!-- Columns and Column aren't Visual Elements or controls; they are considered attributes of MultiColumnListView. --> <Columns> <Column name="index" title="Index" width="120" /> <Column name="active" title="Active?" width="80" /> </Columns> </MultiColumnListView></UXML>
The following USS example styles the MultiColumnListView:
.the-uxml-multi-column-listview { height: 200px;}.unity-multi-column-view__cell > .unity-label,.unity-multi-column-view__cell > .unity-toggle { flex-grow: 1; margin-top: 2px;}
The following C# example illustrates some of the customizable functionalities of the MultiColumnListView:
// Create some list of data, here simply numbers in interval [1, 20] const int itemCount = 20; var items = new List<string>(itemCount); for (var i = 0; i < itemCount; i++) items.Add(i.ToString()); // The columns were created in the UXML but they can also be set using MultiColumnTreeView.columns here. var multiColumnListView = container.Q<MultiColumnListView>(); multiColumnListView.showBoundCollectionSize = false; multiColumnListView.virtualizationMethod = CollectionVirtualizationMethod.DynamicHeight; multiColumnListView.selectionType = SelectionType.Multiple; // Set MultiColumnListView.itemsSource to populate the data in the list. multiColumnListView.itemsSource = items; // For each column, set Column.makeCell to initialize each cell in the column. // You can index the columns array with names or numerical indices. multiColumnListView.columns["index"].makeCell = () => new Label(); multiColumnListView.columns["active"].makeCell = () => { var toggle = new Toggle(); toggle.SetEnabled(false); return toggle; }; // For each column, set Column.bindCell to bind an initialized cell to a data item. multiColumnListView.columns["index"].bindCell = (element, index) => ((Label)element).text = items[index]; multiColumnListView.columns["active"].bindCell = (element, index) => ((Toggle)element).value = index % 2 == 0; // Callback invoked when the user double clicks an item multiColumnListView.itemsChosen += (selectedItems) => { Debug.Log("Items chosen: " + string.Join(", ", selectedItems)); }; // Callback invoked when the user changes the selection inside the MultiColumnListView multiColumnListView.selectedIndicesChanged += (selectedIndices) => { Debug.Log("Index selected: " + string.Join(", ", selectedIndices)); // Note: selectedIndices can also be used to get the selected items from the itemsSource directly or // by using multiColumnListView.viewController.GetItemForIndex(index). };
C# base class and namespace
C# class:
MultiColumnListViewNamespace:
UnityEngine.UIElementsBase class:
BaseListViewMember UXML attributes
This element has the following member attributes:
Name | Type | Description |
|---|---|---|
| | The collection of columns for the multi-column header. |
| | The collection of sorted columns by default. |
| | Whether or not sorting is enabled in the multi-column header. This is deprecated. Use |
| | Indicates how to sort columns. To enable sorting, set it to Note: If there is at least one sorted column, reordering is temporarily disabled. |
Inherited UXML attributes
This element inherits the following attributes from its base class:
Name | Type | Description |
|---|---|---|
| | This property allows the user to allow or block the addition of an item when clicking on the Add Button. It must return If the callback is not set to |
| | This property allows the user to allow or block the removal of an item when clicking on the Remove Button. It must return If the property is not set to |
| | Path of the target property to be bound. |
| | This property controls whether every element in the list will get its data source setup automatically to the correct item in the collection's source. When set to |
| | The height of a single item in the list, in pixels. This property must be set when using the |
| | Whether an element can potentially receive focus. If false, the element can't receive focus. If true, the element receives focus only when its |
| | This property controls the text of the foldout header when using If the |
| | This property controls whether the collection view shows a horizontal scroll bar when its content does not fit in the visible area. |
| | This property controls the drag and drop mode for the list view. The default value is |
| | Gets or sets a value that indicates whether the user can drag list items to reorder them. The default value is |
| | Controls the selection type. The default value is |
| | This property controls whether a footer will be added to the list view. The default value is |
| | This property controls whether the background colors of collection view rows alternate. Takes a value from the |
| | Enable this property to display a border around the collection view. If set to true, a border appears around the ScrollView that the collection view uses internally. |
| | This property controls whether the list view displays the collection size (number of items). The default value is |
| | This property controls whether the list view displays a header, in the form of a foldout that can be expanded or collapsed. The default value is |
| | An integer used to sort focusable elements in the focus ring. Must be greater than or equal to zero. Setting the |
| | The virtualization method to use for this collection when a scroll bar is visible. Takes a value from the The default value is |
This element also inherits the following attributes from :
VisualElementName | Type | Description |
|---|---|---|
| | Logical container where child elements are added. If a child is added to this element, the child is added to this element's content container instead. When iterating over the If the content container is the same as the element itself, child elements are added directly to the element. This is true for most elements but can be overridden by more complex types. The |
| | Assigns a data source to this VisualElement which overrides any inherited data source. This data source is inherited by all children. |
| | Path from the data source to the value. |
| | The possible type of data source assignable to this VisualElement. This information is only used by the UI Builder as a hint to provide some completion to the data source path field when the effective data source cannot be specified at design time. |
| | Returns true if the This flag isn't changed if the VisualElement is disabled implicitly by one of its parents. To verify this, use |
| | Indicates the directionality of the element's text. The value will propagate to the element's children. |
| | The name of this VisualElement. Use this property to write USS selectors that target a specific element. The standard practice is to give an element a unique name. |
| | Determines if this element can be the target of pointer events or picked by Elements can not be picked if: - They are invisible- Their Elements with a picking mode of |
| | Sets the style values on a The returned style data, computed from USS files or inline styles written to this object in C#, doesn't represent the fully resolved styles, such as the final height and width of a VisualElement. To access these fully resolved styles, use For information about how to use this property and all the supported USS properties, refer to the Apply styles in C# scripts and USS properties reference manual pages. |
| | Text to display inside an information box after the user hovers the element for a small amount of time. This is only supported in the Editor UI. |
| | A combination of hint values that specify high-level intended usage patterns for the |
| | Used for view data persistence, such as tree expanded states, scroll position, or zoom level. This key is used to save and load the view data from the view data store. If you don't set this key, the persistence is disabled for the associated |
USS classes
The following table lists all the C# public property names and their related USS selector.
C# property | USS selector | Description |
|---|---|---|
| | The USS class name for ListView elements. Unity adds this USS class to every instance of the ListView element. Any styling applied to this class affects every ListView located beside, or below the stylesheet in the visual tree. |
| | The USS class name of item elements in ListView elements. Unity adds this USS class to every item element the ListView contains. Any styling applied to this class affects every item element located beside, or below the stylesheet in the visual tree. |
| | The USS class name for label displayed when ListView is empty. Unity adds this USS class to the label displayed if the ListView is empty. Any styling applied to this class affects every empty label located beside, or below the stylesheet in the visual tree. |
| | The USS class name for reorderable animated ListView elements. Unity adds this USS class to every instance of the ListView element when |
| | The USS class name for item elements in reorderable animated ListView. Unity adds this USS class to every element in the ListView when |
| | The USS class name for item container in reorderable animated ListView. Unity adds this USS class to every item container in the ListView when |
| | The USS class name for drag handle in reorderable animated ListView. Unity adds this USS class to drag handles in the ListView when |
| | The USS class name for drag handle bar in reorderable animated ListView. Unity adds this USS class to every drag handle bar in the ListView when |
| | The USS class name for the footer of the ListView. Unity adds this USS class to the footer element in the ListView. Any styling applied to this class affects every ListView located beside, or below the stylesheet in the visual tree. |
| | The USS class name for the foldout header of the ListView. Unity adds this USS class to the foldout element in the ListView. Any styling applied to this class affects every foldout located beside, or below the stylesheet in the visual tree. |
| | The USS class name for the size field of the ListView when show bound collection size is enabled Unity adds this USS class to the size field element in the ListView when |
| | The USS class name for the size field of the ListView when foldout header is enabled. Unity adds this USS class to the size field element in the ListView when |
| | The USS class name for the size field of the ListView when the footer is enabled. Unity adds this USS class to the size field element in the ListView when |
| | The USS class name for ListView when foldout header is enabled. Unity adds this USS class to ListView when |
| | The USS class name for ListView when add/remove footer is enabled. Unity adds this USS class to ListView when |
| | The USS class name for scroll view when add/remove footer is enabled. Unity adds this USS class scroll view of |
| | The USS class name for BaseVerticalCollectionView elements. Unity adds this USS class to every instance of the BaseVerticalCollectionView element. Any styling applied to this class affects every BaseVerticalCollectionView located beside, or below the stylesheet in the visual tree. |
| | The USS class name for BaseVerticalCollectionView elements with a border. Unity adds this USS class to an instance of the BaseVerticalCollectionView element if the instance's |
| | The USS class name of item elements in BaseVerticalCollectionView elements. Unity adds this USS class to every item element the BaseVerticalCollectionView contains. Any styling applied to this class affects every item element located beside, or below the stylesheet in the visual tree. |
| | The USS class name of the drag hover bar. Unity adds this USS class to the bar that appears when the user drags an item in the list. Any styling applied to this class affects every BaseVerticalCollectionView located beside, or below the stylesheet in the visual tree. |
| | The USS class name of the drag hover circular marker used to indicate depth. Unity adds this USS class to the bar that appears when the user drags an item in the list. Any styling applied to this class affects every BaseVerticalCollectionView located beside, or below the stylesheet in the visual tree. |
| | The USS class name applied to an item element on drag hover. Unity adds this USS class to the item element when it's being dragged. Any styling applied to this class affects every BaseVerticalCollectionView item located beside, or below the stylesheet in the visual tree. |
| | The USS class name of selected item elements in the BaseVerticalCollectionView. Unity adds this USS class to every selected element in the BaseVerticalCollectionView. The |
| | 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 |
| | The USS class name of the scroll view in the BaseVerticalCollectionView. Unity adds this USS class to the BaseVerticalCollectionView's scroll view. Any styling applied to this class affects every BaseVerticalCollectionView scroll view located beside, or below the stylesheet in the visual tree. |
| | USS class name of local disabled elements. |
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 at every level of its hierarchy.
VisualElement