UXML element ListView

C# class: ListView
Namespace: UnityEngine.UIElements
Base class: BaseListView

属性

The following table lists all the supported attributes.

ListView versus ScrollView

You can use a ScrollView control to create the same functionalities as using a ListView. However, a ListView is more efficient than a ScrollView when you do the following:

• Populate list items
• Manage item height
• Bind and unbind to objects
• Instantiate the number of visual elements required to fill a page
• Recycle visual elements to optimize memory handling

Set item height

To change how item height is used to drive content, use the VirtualizationMethod:

• VirtualizationMethod.FixedHeight sets all items to the same height.
• VirtualizationMethod.DynamicHeight allows items to have varying heights.

Style the ListView

To see which USS selectors affect the component of a ListView at every level of its hierarchy, use the UI Toolkit Debugger:

1. In Unity, select Window > UI Toolkit > Debugger.
2. In the UI Toolkit Debugger window, select Pick Element and then select the visual element that you want to debug.

The UI Toolkit Debugger window displays the following:

• All child elements of the visual element
• All the USS selectors for each component of the visual element
• Detailed information of each USS selector

Note: The horizontal and vertical Scroller elements are standard UI Toolkit Scrollers.

示例

​ The best way to learn how to use ListView is to try an example. To see a simple ListView example, in Unity, select Window > UI Toolkit > Samples > List View.

If you want to create a ListView with complex data and bind the ListView to visual elements, do the following:

• Use makeItem and bindItem to bind the elements to data, register the appropriate callbacks, and modify the linked data source as needed.
• Use unbindItem to recycle an element for the ListView and unbind the data.
• Use destroyItem to clear the registered callbacks.

The following example shows a complex ListView. The example creates a custom Editor window with a list of Characters. Each Character has a slider and a color palette. Moving the slider changes the color of the palette.

This example builds the visual elements in the list from a C# script. It uses a custom CharacterInfoVisualElement class that inherits from VisualElement, and binds the custom elements to CharacterInfo objects.

You can find the completed files that this example creates in this GitHub repository.

To create the example by yourself:

1. Create a Unity project with any template.

2. In the Project window, create a folder named Editor.

3. In the Editor folder, create a C# script file named ListViewExample with the following content:

   using System;
   using System.Collections.Generic;
   using UnityEditor;
   using UnityEngine;
   using UnityEngine.UIElements;
       
   public class ListViewExample : EditorWindow
   {
       // Gradient used for the HP color indicator.
       private Gradient hpGradient;
       private GradientColorKey[] hpColorKey;
       private GradientAlphaKey[] hpAlphaKey;
           
       // ListView is kept for easy reference.
       private ListView listView;
           
       // List of CharacterInfo items, bound to the ListView.
       private List<CharacterInfo> items;
       [MenuItem("Window/ListView Custom Item")]
          
       public static void OpenWindow()
       {
           GetWindow<ListViewExample>().Show();
       }
           
       private void OnEnable()
       {
           SetGradient();
               
           // Create and populate the list of CharacterInfo objects.
           const int itemCount = 50;
           items = new List<CharacterInfo>(itemCount);
           for(int i = 1; i <= itemCount; i++)
           {
               CharacterInfo character = new CharacterInfo {name = $"Character {i}", maxHp = 100};
               character.currentHp = character.maxHp;
               items.Add(character);
           }
               
           // The ListView calls this to add visible items to the scroller.
           Func<VisualElement> makeItem = () =>
           {
               var characterInfoVisualElement = new CharacterInfoVisualElement();
               var slider = characterInfoVisualElement.Q<SliderInt>(name: "hp");
               slider.RegisterValueChangedCallback(evt =>
               {
                   var hpColor = characterInfoVisualElement.Q<VisualElement>("hpColor");
                   var i = (int)slider.userData;
                   var characterInfo = items[i];
                   characterInfo.currentHp = evt.newValue;
                   SetHp(slider, hpColor, characterInfo);
               });
               return characterInfoVisualElement;
           };
               
           // The ListView calls this if a new item becomes visible when the item first appears on the screen, 
           // when a user scrolls, or when the dimensions of the scroller are changed.
           Action<VisualElement, int> bindItem = (e, i) => BindItem(e as CharacterInfoVisualElement, i);
               
           // Height used by the ListView to determine the total height of items in the list.
           int itemHeight = 55;
               
           // Use the constructor with initial values to create the ListView.
           listView = new ListView(items, itemHeight, makeItem, bindItem);
           listView.reorderable = false;
           listView.style.flexGrow = 1f; // Fills the window, at least until the toggle below.
           listView.showBorder = true;
           rootVisualElement.Add(listView);
               
           // Add a toggle to switch the reorderable property of the ListView.
           var reorderToggle = new Toggle("Reorderable");
           reorderToggle.style.marginTop = 10f;
           reorderToggle.value = false;
           reorderToggle.RegisterValueChangedCallback(evt => listView.reorderable = evt.newValue);
           rootVisualElement.Add(reorderToggle);
       }
           
       // Sets up the gradient.
       private void SetGradient()
       {
           hpGradient = new Gradient();
               
           // HP at 0%: Red. At 10%: Dark orange. At 40%: Yellow. At 100%: Green.
           hpColorKey = new GradientColorKey[4];
           hpColorKey[0] = new GradientColorKey(Color.red, 0f);
           hpColorKey[1] = new GradientColorKey(new Color(1f, 0.55f, 0f), 0.1f); // Dark orange
           hpColorKey[2] = new GradientColorKey(Color.yellow, 0.4f);
           hpColorKey[3] = new GradientColorKey(Color.green, 1f);
               
           // Alpha is always full.
           hpAlphaKey = new GradientAlphaKey[2];
           hpAlphaKey[0] = new GradientAlphaKey(1f, 0f);
           hpAlphaKey[1] = new GradientAlphaKey(1f, 1f);
           hpGradient.SetKeys(hpColorKey, hpAlphaKey);
       }
           
       // Bind the data (characterInfo) to the display (elem).
       private void BindItem(CharacterInfoVisualElement elem, int i)
       {
           var label = elem.Q<Label>(name: "nameLabel");
           var slider = elem.Q<SliderInt>(name: "hp");
           var hpColor = elem.Q<VisualElement>("hpColor");
           slider.userData = i;
           CharacterInfo characterInfo = items[i];
           label.text = characterInfo.name;
           SetHp(slider, hpColor, characterInfo);
       }
           
       private void SetHp(SliderInt slider, VisualElement colorIndicator, CharacterInfo characterInfo)
       {
           slider.highValue = characterInfo.maxHp;
           slider.SetValueWithoutNotify(characterInfo.currentHp);
           float ratio = (float)characterInfo.currentHp / characterInfo.maxHp;
           colorIndicator.style.backgroundColor = hpGradient.Evaluate(ratio);
       }
           
       // This class inherits from VisualElement to display and modify data to and from a CharacterInfo.
       public class CharacterInfoVisualElement : VisualElement
       {
           // Use Constructor when the ListView uses makeItem and returns a VisualElement to be 
           // bound to a CharacterInfo data class.
           public CharacterInfoVisualElement()
           {
               var root = new VisualElement();
                   
               // The code below to style the ListView is for demo purpose. It's better to use a USS file
               // to style a visual element. 
               root.style.paddingTop = 3f;
               root.style.paddingRight = 0f;
               root.style.paddingBottom = 15f;
               root.style.paddingLeft = 3f;
               root.style.borderBottomColor = Color.gray;
               root.style.borderBottomWidth = 1f;
               var nameLabel = new Label() {name = "nameLabel"};
               nameLabel.style.fontSize = 14f;
               var hpContainer = new VisualElement();
               hpContainer.style.flexDirection = FlexDirection.Row;
               hpContainer.style.paddingLeft = 15f;
               hpContainer.style.paddingRight = 15f;
               hpContainer.Add(new Label("HP:"));
               var hpSlider = new SliderInt {name = "hp", lowValue = 0, highValue = 100};
               hpSlider.style.flexGrow = 1f;
               hpContainer.Add(hpSlider);
               var hpColor = new VisualElement();
               hpColor.name = "hpColor";
               hpColor.style.height = 15f;
               hpColor.style.width = 15f;
               hpColor.style.marginRight = 5f;
               hpColor.style.marginBottom = 5f;
               hpColor.style.marginLeft = 5f;
               hpColor.style.backgroundColor = Color.black;
               hpContainer.Add(hpColor);
               root.Add(nameLabel);
               root.Add(hpContainer);
               Add(root);
           }
       }
   
       // Basic data class used for a character, with a name and HP data. Use a list of CharacterInfo as
       // a data source for the ListView. The CharacterInfo can be bound to CharacterInfoVisualElement when needed.    
       [Serializable]
       public class CharacterInfo
       {
           public string name;
           public int maxHp;
           public int currentHp;
       }
   }
   

4. To see the example live, from the menu, select Window > ListView Custom Item.

其他资源

• UXML elements reference
• Bind to a list with ListView