Partager via


WinJS.UI.AppBarCommand object

A command to be displayed in an app bar (AppBar).

Explore this functionality in more depth as part of our App features, start to finish series: Flat navigation, start to finish (HTML) and Hierarchical navigation, start to finish (HTML)

Syntax

<button data-win-control="WinJS.UI.AppBarCommand"></button>
var object = new WinJS.UI.AppBarCommand(element, options);

Members

The AppBarCommand object has these types of members:

  • Constructors
  • Methods
  • Properties

Constructors

The AppBarCommand object has these constructors.

Constructor Description
AppBarCommand

Creates a new AppBarCommand object.

 

Methods

The AppBarCommand object has these methods.

Method Description
addEventListener

Registers an event handler for the specified event.

dispose

Releases resources held by the AppBarCommand. Call this method when the AppBarCommand is no longer needed. After calling this method, the AppBarCommand becomes unusable.

removeEventListener

Removes an event handler registered with addEventListener.

 

Properties

The AppBarCommand object has these properties.

Property Access type Description

disabled

Read/write

Gets or sets a value that indicates whether the AppBarCommand is disabled.

element

Read-only

Gets the DOM element that hosts the AppBarCommand.

extraClass

Read/write

Gets or sets additional CSS classes to apply to the element that hosts the AppBarCommand.

firstElementFocus

Read/write

Gets or sets keyboard navigation behavior in the app bar for AppBarCommand elements of type "content". This property identifies the element that receives focus within the AppBarCommand host <div> (or container) when navigating from the left.

flyout

Read/write

Gets or sets a Flyout object that is displayed when the AppBarCommand is invoked.

hidden

Read-only

Gets or sets a value that indicates whether the AppBarCommand is hidden.

icon

Read/write

Gets or sets the AppBarCommand identifier.

id

Read-only

Gets or sets the AppBarCommand identifier.

label

Read/write

Gets or sets the AppBarCommand label.

lastElementFocus

Read/write

Gets or sets keyboard navigation behavior in the app bar for AppBarCommand elements of type "content". This property identifies the element that receives focus within the AppBarCommand host <div> (or container) when navigating from the right.

onclick

Read/write

Gets or sets the event handler function invoked when the AppBarCommand is clicked.

priority

Read/write

Gets or sets the priority of the command.

section

Read-only

Gets or sets the section of the AppBar that hosts this AppBarCommand.

selected

Read/write

Gets or sets the selected state of an AppBarCommand of type "toggle".

tooltip

Read/write

Gets or sets the tooltip of the AppBarCommand.

type

Read/write

Gets or sets the type of the command.

 

Remarks

Styling the AppBarCommand

CSS classes

To customize the AppBarCommand, you can define your own styles for these CSS classes (defined by the Windows Library for JavaScript style sheets):

CSS class Description

win-command

Styles the entire AppBarCommand.

win-commandicon

Styles the icon box for the AppBarCommand.

win-commandimage

Styles the image for the AppBarCommand.

win-commandring

Styles the icon ring for the AppBarCommand.

win-label

Styles the label for the AppBarCommand.

 

Note  There are several CSS classes that are shared between multiple WinJS controls. To limit your custom styles to a specific control, assign the control an ID or custom class name and use that as part of your style selector.

 

For a list of icons that you can use on an AppBar, see AppBarIcon.

Examples

Here we show how to declare an app bar that contains each of the supported AppBarCommand types.

AppBarCommand can be one of these types (see type):

  • "button"
  • "toggle"
  • "flyout"
  • "separator"
  • "content"
<!-- Standard app bar -->
<!-- Define the example flyout command for the app bar -->
<div id="exampleFlyout" 
     data-win-control="WinJS.UI.Flyout" aria-label="{Example flyout}">
     <div>This is an example AppBarCommand of type 'flyout'.</div>
     <button id="exampleFlyoutButton">Example flyout</button>
</div>
<!-- Define the app bar -->
<div id="appBar" 
     data-win-control="WinJS.UI.AppBar" 
     data-win-options="{placement:'bottom'}">
    <button data-win-control="WinJS.UI.AppBarCommand"
            data-win-options="{id:'secondary1',
            type:'button',
            label:'Secondary1',
            section:'secondary'}"></button>
    <div data-win-control="WinJS.UI.AppBarCommand"
         data-win-options="{ id: 'list',
         type: 'content',
         label:'List',
         section: 'secondary'}">
        <select class="options">
            <option>Option1</option>
            <option>Option2</option>
            <option>Option3</option>
            <option>Option4</option>
        </select>
    </div>
    <div data-win-control="WinJS.UI.AppBarCommand"
         data-win-options="{ id: 'textfield',
         type: 'content',
         label:'Text field',
         section: 'secondary' }">
        <input type="text" value="Text" />
    </div>
    <button data-win-control="WinJS.UI.AppBarCommand"
            data-win-options="{id:'flyoutButton',
            type:'flyout',
            label:'Flyout',
            icon:'openpane',
            section: 'secondary',
            flyout:select('#exampleFlyout')}"></button>
    <button data-win-control="WinJS.UI.AppBarCommand"
            data-win-options="{id:'cmdToggle',
            type:'toggle',
            label:'Toggle',
            icon:'audio',
            section:'primary',
            tooltip:'Toggle'}"></button>
    <hr data-win-control="WinJS.UI.AppBarCommand"
        data-win-options="{id:'separator',
        type:'separator',
        section:'primary'}" />
    <button data-win-control="WinJS.UI.AppBarCommand"
            data-win-options="{id:'helpButton',
            type: 'button',
            label:'Help',
            tooltip:'Help',
            icon:'help',
            section:'primary'
            }"></button>
</div>

Requirements

Minimum WinJS version

WinJS 1.0

Namespace

WinJS.UI

See also

WinJS.UI Namespace

AppBar

AppBarIcon

BackButton

NavBar

Your first app - Part 3: PageControl objects and navigation

Navigating between pages (HTML)

Adding app bars

Adding nav bars

HTML AppBar control sample

HTML NavBar control sample

Navigation and navigation history sample

Designers

Command patterns

Navigation patterns

Guidelines for app bars

Bottom app bar

Top app bar