OOUI/OOjs primer/ja

This page is a translated version of the page OOUI/OOjs primer and the translation is 5% complete.

OOUI ライブラリは、OOjs が提供するイベントモデルに基づいています。 OOjs に慣れていない場合は、例でよく使用される便利で強力なツールであるため、少し時間を取って EventEmitter に慣れることをお勧めします。

EventEmitter allows event handlers to be connected to an object, called when events occur, and disconnected when no longer needed. Events are tied to their context. For example, when a toggle button changes state, the event is not simply ‘change,’ but ‘change’ and the value of the toggle button’s state ( ‘on’ or ‘off’).

The most basic way to connect and disconnect an event handler is with the EventEmitter’s on() and off() methods. In the following example, the on() method is used to connect an onChange event handler to a toggle button, which is defined in the example as well.

// The following example uses the on() method to connect an event handler 
// to a toggle button widget. The off() method is later used to disconnect
// the event handler.

// Create a new toggle button
var button = new OO.ui.ToggleButtonWidget( { 
  label: 'I handle events' 
} );
// Set up the event handler. In this example, the event handler is a 
// function that will change the button label to 'All done!' when the 
// state of the button changes. The off() method is then used to 
// disconnect the event handler from the toggle button so that the 
// function will no longer be called.
button.onChange = function () {
  button.setLabel( 'All done!' );
  button.off( 'change', button.onChange );
} 
// Use the ButtonWidget's on() method to connect an event handler 
// ('button.onChange', defined above) to the button for the specified 
// type of event ('change'). 
button.on( 'change', button.onChange );
// Append the button to the DOM.
$( 'body' ).append( button.$element );

Often, the connect() and disconnect() methods are used to connect and disconnect multiple event handlers to objects. The following example illustrates these methods.

// This example illustrates the connect() and disconnect() methods.
// Here, the 'onChange' function, which changes the label of the toggle button
// labeled 'try me!' to match the button's state ('on' or 'off') will be
// executed whenever the state of the toggle button changes. The 'onToggleClick'
// function, which writes 'Click!' each time the toggle button is clicked, is
// also connected to the toggle button via the connect() method. The
// disconnect() method, connected to the 'Disconnect EventHandlers' button,
// is used to remove both event handlers from the toggle button.

// Create buttons and add them to a button group.
var toggle = new OO.ui.ToggleButtonWidget( {
  label: 'try me!'
} );

var button = new OO.ui.ButtonWidget( {
  label: 'Disconnect EventHandlers'
} );

var buttonGroup = new OO.ui.ButtonGroupWidget( {
  items: [ toggle, button ]
} );

// Define the functions to connect (toggle.onChange, toggle.onToggleClick, and
// button.onClick, in this example)

toggle.onChange = function () {
  if ( toggle.getValue() === false ) {
    toggle.setLabel( 'off' );
  } else {
    toggle.setLabel( 'on' );
  }
};

toggle.onToggleClick = function () {
  $( 'body' ).append( '<p>Click!</p>' );
};

button.onClick = function () {
  toggle.disconnect( toggle, {
    change: 'onChange',
    click: 'onToggleClick'
  } );
};

// Bind the functions to the widgets for the specified events.

toggle.connect( toggle, {
  change: 'onChange',
  click: 'onToggleClick'
} );

button.connect( button, {
  click: 'onClick'
} );

// Append the button group to the DOM.
$( 'body' ).append( buttonGroup.$element );

A convention of OOjs is that any method that begins with "on" (e.g., onClick() and onKeyPress()) is private, except for the on() method itself.

For more details about EventEmitter, please see OOjs/Events.