Using Events

The Components and Classes of Ext JS fire a broad range of events at various points in their lifecycle. Events allow your code to react to changes around your application. They are a key concept within Ext JS.

在ExtJS组件和类的生命周期中，会触发许多类型的事件，在各种情况下。事件允许你的代码对app中的改变做出响应。这是ExtJS中的核心概念。

What Are Events?

Events fire whenever something interesting happens to one of your Classes. For example, whenExt.Component renders to the screen, Ext JS fires an event after the render completes. We can listen for that event by configuring a simple listeners object:

无论什么时候，你的类发生了有趣的改变，事件会触发。例如，当Ext.Component 渲染到屏幕，Ext JS触发在渲染完成后触发一个事件。我们可以通过配置一个简单的监听对象来监听事件。

Ext.create(‘Ext.Panel‘, {
    html: ‘My Panel‘,
    renderTo: Ext.getBody(),
    listeners: {
        afterrender: function() {
            Ext.Msg.alert(‘We have been rendered‘);
        }
    }
});

In this example, when you click the Preview button, the Panel renders to the screen, followed by the defined alert message. All events fired by a class are listed in the class’s API page - for example,Ext.panel.Panel currently has 45 events.

在这个例子中，当你单击Preview按，panel渲染到屏幕，紧接着是已经定义的alert消息。类的所有事件从API文档可查到，例如，现在

Ext.panel.Panel 具有45个事件。

Listening to Events

While Ext.Component-event-afterrender is useful in some cases, you may use other events more frequently. For instance, Ext.button.Button fires click events when clicked:

正如Ext.Component-event-afterrender 在特定情况下有用一样，你也会频繁用到其它事件。例如Ext.button.Button 触发单击事件，当被点击时：

Ext.create(‘Ext.Button‘, {
    text: ‘Click Me‘,
    renderTo: Ext.getBody(),
    listeners: {
        click: function() {
            Ext.Msg.alert(‘I was clicked!‘);
        }
    }
});
 

A component may contain as many event listeners as needed. In the following example, we confound users by calling this.hide() inside our mouseover listener to hide a Button. We then display the button again a second later. When this.hide() is called, the Button is hidden and the hide event fires. The hide event triggers our hide listener, which waits one second and displays the Button again:

组件会根据需要包含尽量多的事件监听器。在下面的例子中，我们通过在 mouseover监听器中调用this.hide()隐藏按钮来来迷惑用户。

Ext.create(‘Ext.Button‘, {
    renderTo: Ext.getBody(),
    text: ‘My Button‘,
    listeners: {
        mouseover: function() {
            this.hide();
        },
        hide: function() {
            // Waits 1 second (1000ms), then shows the button again
            Ext.defer(function() {
                this.show();
            }, 1000, this);
        }
    }
 });
 

Event listeners are called every time an event is fired, so you can continue hiding and showing the button for as long as you desire.

每次事件触发的时候事件监听器都会被调用，因此，隐藏和显示按钮的把戏，你想玩多久就玩多久。

Adding Listeners Later

In previous examples, we passed listeners to the component when the class was instantiated. However, If we already have an instance, we can add listeners using the on function:

在前面的例子中，我们传递监听器给组件，当类被实例化的时候。然而，如果已经有了一个实例，我们可以用下面的函数来添加监听器：

var button = Ext.create(‘Ext.Button‘, {
    renderTo: Ext.getBody(),
    text: ‘My Button‘
});

button.on(‘click‘, function() {
    Ext.Msg.alert(‘Event listener attached by .on‘);
});

You can also specify multiple listeners by using the .on method, similar to using a listener configuration. The following revisits the previous example that set the button’s visibility with a mouseover event:

你也可以用.on方法来指定多个监听器，就像使用listener 配置项一样。下面用.on的方法来重新看看前面的例子：

var button = Ext.create(‘Ext.Button‘, {
    renderTo: Ext.getBody(),
    text: ‘My Button‘
});

button.on({
    mouseover: function() {
        this.hide();
    },
    hide: function() {
        Ext.defer(function() {
            this.show();
        }, 1000, this);
    }
});
 

Removing Listeners

Just as we can add listeners at any time, we can also remove them. This time we use the un function. To remove a listener, we need a reference to its function. In the previous examples, we passed a function into the listener’s object or the on call. This time, we create the function earlier and link it into a variable called doSomething, which contains our custom function. Since we initially pass the new doSomethingfunction into our listeners object, the code begins as before. With the eventual addition of an Ext-method-defer function, clicking the button in the first 3 seconds yields an alert message. However, after 3 seconds the listener is removed so nothing happens:

就像我们可以在任何时候添加监听器一样，我们也可以移除它们。这时，我们使用un函数。要移除一个监听器，我们需要参考它的函数。在前面的例子中，我们传递一个函数给监听器对象或on函数。现在，我们先创建函数，赋值给doSomething变量。由于在监听器对象中我们做了配置，程序开始会像之前一样运行。但是，通过 额外的Ext-method-defer 函数，3秒内单击按钮可以看到alert消息，3秒之后监听器被移除，因此什么也不会发生了。

var doSomething = function() {
    Ext.Msg.alert(‘listener called‘);
};

var button = Ext.create(‘Ext.Button‘, {
    renderTo: Ext.getBody(),
    text: ‘My Button‘,
    listeners: {
        click: doSomething,
    }
});

Ext.defer(function() {
    button.un(‘click‘, doSomething);
}, 3000);
 

Scope Listener Option  监听器作用域选项

Scope sets the value of this inside your handler function. By default, this is set to the instance of the class firing the event. This is often, but not always, the functionality that you want. This functionality allows us to call this.hide() to hide the button in the second example earlier in this guide. In the following example, we create a Button and a Panel. We then listen to the Button’s click event with the handler running in Panel’s scope. In order to do this, we need to pass in an object instead of a handler function. This object contains the function AND the scope:

作用域在你的处理函数中设置了this的值。缺省的，this指向触发事件的类。这是通常，但不总是，你期望的行为。在前面的例子中，这种方式允许我们调用this.hide()来隐藏按钮。在下面的例子中，我们创建button和panel。然后我们设置监听按钮的单击事件，其处理函数的作用域是panel。为了达到这个目的，我们需要传递一个对象而不是处理函数。这个对象包含了函数和作用域。

var panel = Ext.create(‘Ext.Panel‘, {
    html: ‘Panel HTML‘
});

var button = Ext.create(‘Ext.Button‘, {
    renderTo: Ext.getBody(),
    text: ‘Click Me‘
});

button.on({
    click: {
        scope: panel,
        fn: function() {
            Ext.Msg.alert(this.getXType());
        }
    }
});

When you run this example, the value of the click handler’s this is a reference to the Panel. To see this illustrated, we alert the xtype of the scoped component. When the button is clicked, we should see the Panel xtype being alerted.

当你运行这个例子，this的值指向了panel。

Listening to an Event Once   只监听事件一次

You may want to listen to one event only once. The event itself might fire any number of times, but we only want to listen to it once. The following codes illustrates this situation:

你可能希望只监听某个事件一次。事件本身会触发很多次，但是我们只希望监听到一次。下面的代码演示了这种情形：

var button = Ext.create(‘Ext.Button‘, {
    renderTo: Ext.getBody(),
    text: ‘Click Me‘,
    listeners: {
        click: {
            single: true,
            fn: function() {
                Ext.Msg.alert(‘I will say this only once‘);
            }
        }
    }
});

Using a Buffer Configuration  使用缓存配置

For events that fire many times in short succession, we can reduce the number of times our listener is called by using a buffer configuration. In this case our button’s click listener is only invoked once every 2 seconds, regardless of how many times you click it:

短时间会触发多次的事件，我们通过buffer配置可以减少监听器被调用的次数。在这个例子中，按钮的单击事件只会隔两秒调用一次，无论被点了多少次。

var button = Ext.create(‘Ext.Button‘, {
    renderTo: Ext.getBody(),
    text: ‘Click Me‘,
    listeners: {
        click: {
            buffer: 2000,
            fn: function() {
                Ext.Msg.alert(‘I say this only once every 2 seconds‘);
            }
        }
    }
});
 

Firing Custom Events  触发自定义事件

Firing your own events is done by calling fireEvent with an event name. In the following example we fire an event called myEvent that passes two arguments - the button itself and a random number between 1 and 100:

通过调用fireEvent可以触发你自己的事件，通过事件名称。在下面的例子中，我们触发一个myEvent事件，传递两个参数-button和一个1-100的随机数：

var button = Ext.create(‘Ext.Button‘, {
    renderTo: Ext.getBody(),
    text: "Just wait 2 seconds",
    listeners: {
        myEvent: function(button, points) {
            Ext.Msg.alert(‘myEvent fired! You score ‘ + points + ‘ points‘);
        }
    }
});

Ext.defer(function() {
    var number = Math.ceil(Math.random() * 100);

    button.fireEvent(‘myEvent‘, button, number);
}, 2000);
 

Once again we used Ext.defer to delay the function that fires our custom event, this time by 2 seconds. When the event fires, the myEvent listener picks up on it and displays the arguments we passed in.

Listening for DOM Events   监听DOM事件

Not every ExtJS component raises every event. However, by targeting the container’s element, we can attach many native events to which the component can then listen. In this example, we targetExt.container.Container. Containers do not have a click event. Let’s give it one!

不是每个ExtJS组件都能触发每一个事件。然而，通过为容器元素设置目标，我们可以为组件设置许多原生的事件。在这个例子中，我们设置Ext.container.Container的目标。容器没有单击事件，我们来给它加一个！

var container = Ext.create(‘Ext.Container‘, {
    renderTo: Ext.getBody(),
    html: ‘Click Me!‘,
    listeners: {
        click: function(){
            Ext.Msg.alert(‘I have been clicked!‘)
        }
    }
});

container.getEl().on(‘click‘, function(){
    this.fireEvent(‘click‘, container);
}, container);

Without the second block of code, the container’s click listener would not fire. Since we have targeted the container’s element and attached a click listener, we have extended the container’s event capabilities.

如果没有第二段代码，容器的单击事件不会触发。由于我们将容器元素设为目标，并绑定了单击监听器，我们扩展了容器的事件处理能力。

Event Normalization  事件标准化

Event normalization is the key to allowing Ext JS 5 applications to run on touch-screen devices. This normalization occurs behind the scenes and is a simple translation from standard mouse events to their equivalent touch and pointer events.

事件标准化是让Ext JS5可运行在触屏设备的关键。标准化在背后发生，它是从鼠标事件到等价的触摸和pointer events转换。

Pointer events are a w3c standard for dealing with events that target a specific set of coordinates on the screen, regardless of input device (mouse, touch, stylus, etc.)

Pointer events 是一个w3c标准化，用来处理不同屏幕设备的事件，无论输入设备方式（鼠标，触摸，触笔）

When your code requests a listener for a mouse event, the framework attaches a similar touch or pointer event as needed. For example, if the application attempts to attach a mousedown listener:

当你的代码要求一个鼠标事件的监听器，框架根据需要附加一个touch或pointer event事件。例如，如果应用程序视图附加一个mousedown listener:

myElement.on(‘mousedown‘, someFunction);

The event system translates this to touchstart in the case of a device that supports touch events:

事件系统翻译这个事件为touchstart ，如果设备支持 touch events：

myElement.on(‘touchstart‘, someFunction);

Or, pointerdown in the case of a device that supports pointer events:

或者，翻译为pointerdown事件，如果设备支持pointer events：

myElement.on(‘pointerdown‘, someFunction);

This translation is in place so that you may achieve tablet and touch-screen support without any additional coding.

这个转换使得你可以得到平板和触屏设备支持，而不需要写额外的代码。

In most cases the framework can transition seamlessly between mouse, touch, and pointer input. However, there are a few mouse interactions (such as mouseover) that do not translate easily into touch interactions. Such events will need to be handled on an individual basis and are addressed in a following section.

在大多情况下，框架可以在鼠标、触摸、触笔设备间无缝转换。然而，有一些鼠标交互（例如mouseover）不能简单的转换到触摸交互。这些事件需要单独处理。

Gestures  手势

In addition to standard DOM events, Elements also fire synthesized “gesture” events. Since the Sencha Touch event system forms the basis for the new event system in Ext JS 5, Sencha Touch users may already be familiar with this concept.

除了标准的DOM事件，事件还激发人工合成的“gesture” 事件.由于 Sencha Touch 事件系统在ExtJS 5中构成了新事件系统的基础， Sencha Touch 用户会感到很熟悉。

From a browser’s perspective, there are 3 primary types of pointer, touch, and mouse events - start, move, and end:

从浏览器的观点，有三种主要事件类型，pointer，touch，mouse event  start, move, and end:

Upon interpreting the sequence and timing of these events, the framework can synthesize more complex events such as drag, swipe, longpress, pinch, rotate, and tap. Ext JS applications can listen for gesture events just like any other event, for example:

在解释这些事件的序列和时机的基础上，框架可以人工合成更复杂的事件，例如drag, swipe, longpress, pinch, rotate, and tap. Ext JS app可以监听手势事件，就像监听其它事件一样。

Ext.get(‘myElement‘).on(‘longpress‘, handlerFunction);

The original Sencha Touch gesture system was designed primarily with touch events in mind. By adding full support for pointer and mouse events to the Gesture system, Ext JS 5 allows any gesture to respond to any type of input. This means not only that all gestures can be triggered using touch input, but all single-point gestures (tap, swipe, etc.) can be triggered using a mouse as well. This results in a gesture system that works seamlessly across devices regardless of input type.

最初的Sencha Touch手势系统主要设计用于touch事件。通过添加pointer，鼠标设备的完全支持，Ext JS 5 允许任何手势来响应任何类型的输入。这意味着不但所有的手势可以使用touch被触发，所有的单点手势也可以用鼠标来触发。结果就是手势系统可无缝的跨不同设备，不同输入类型的运行。