ScrollView Component Reference

ScrollView is a container with a scroll function. It provides a way to browse more contents within a limited display area. Generally, ScrollView will be used along with the Mask component and the ScrollBar component can also be added to show the current offset location within the browsing content.

scrollview-content

scrollview-inspector

Click the Add Component button at the bottom of the Inspector panel and select UI/ScrollView to add the ScrollView component to the node.

To use ScrollView, please refer to the ScrollView API documentation and the ScrollView scene of the test-cases-3d project.

ScrollView Properties

PropertyFunction Explanation
BounceDurationFloating point number, the time duration for bounce back. The value range is 0-10
BrakeFloating point number, the deceleration coefficient after scrolling. The value range is 0-1. If set to 1, then the scrolling will stop immediately, if set to 0, then the scrolling will continue until the content border
CancelInnerEventsIf it is set to true, then the scroll behavior will cancel the touch events registered on the child node. The default setting is true
ContentA reference node for the inner content of the ScrollView. It could be a node containing a very large image or long texts.
ElasticBoolean value, whether to bounce back or not while scroll to the border.
HorizontalBoolean value, whether horizontal scroll is allowed or not
HorizontalScrollBarA reference node for creating a scroll bar showing the horizontal position of the content
InertiaIs there an accelerating velocity when scrolling
ScrollEventsDefault list type is null. Each event added by the user is composed of the node reference, component name and a response function. Please see the ScrollView Event section below for details
VerticalBoolean value, whether vertical scroll is allowed or not
VerticalScrollBarA reference node for creating a scroll bar showing vertical position of the contents

ScrollView Event

scrollview-event

For event structure you can refer to the Button documentation.

The ScrollView event callback will have two parameters, the first one is the ScrollView itself and the second one is the event type of ScrollView.

ScrollBar Setting

ScrollBar is optional. You can choose to set either a Horizontal ScrollBar or a Vertical ScrollBar or of course set them both.

To build a connection, you can drag a node with the ScrollBar component in the Hierarchy over to the corresponding field in ScrollView.

Detailed Explanation

The ScrollView component can only work with the specified content node. It calculates location information during scrolling using both the designated scroll direction and the length of the content node in this direction.

The Content node can also set up the auto resize by adding a Widget, or it can arrange the layout of child nodes by adding a Layout, but these two components should not be added to a node at the same time to avoid unintentional consequences.

Normally a ScrollView node tree resembles the following:

scrollview-hierarchy

The view here is used to define a scroll area that can be displayed. As a result, the Mask will normally be added to the view. Contents that can scroll can be put in the content node or added to its child node.

Add a callback through the script code

Method one

The event callback added by this method is the same as the event callback added by the editor, all added by code. First you need to construct a EventHandler object, and then set the corresponding target, component, handler and customEventData parameters.

  1. import { _decorator, Component, ScrollView, EventHandler } from 'cc';
  2. const { ccclass, property } = _decorator;
  3. @ccclass("example")
  4. export class example extends Component {
  5. onLoad() {
  6. const scrollViewEventHandler = new EventHandler();
  7. // This node is the node to which your event handler code component belongs
  8. scrollViewEventHandler.target = this.node;
  9. // This is the script class name
  10. scrollViewEventHandler.component = 'example';
  11. scrollViewEventHandler.handler = 'callback';
  12. scrollViewEventHandler.customEventData = 'foobar';
  13. const scrollview = this.node.getComponent(ScrollView);
  14. scrollview.scrollEvents.push(scrollViewEventHandler);
  15. }
  16. callback(scrollview, eventType, customEventData){
  17. // here scrollview is a ScrollView component object instance
  18. // here the eventType === ScrollView.EventType enum
  19. // here the customEventData parameter is equal to the "foobar" you set before
  20. }
  21. }

Method two

By scrollview.node.on('scroll-to-top', ...) way to add.

  1. // Suppose we add an event handler callback to the onLoad method of a component and handle the event in the callback function:
  2. import { _decorator, Component, ScrollView } from 'cc';
  3. const { ccclass, property } = _decorator;
  4. @ccclass("example")
  5. export class example extends Component {
  6. @property(ScrollView)
  7. scrollview: ScrollView | null = null;
  8. onLoad(){
  9. this.scrollview.node.on('scroll-to-top', this.callback, this);
  10. }
  11. callback(scrollView: ScrollView) {
  12. // The callback parameter is the ScrollView component, note that events registered this way cannot pass customEventData.
  13. }
  14. }

Similarly, you can register events such as scrolling, touch-up, scroll-began, etc. The parameters of the callback function for these events are consistent with the parameters of scroll-to-top.