WinJS.UI.AppBar object

Artikel
01/26/2017

The application toolbar used to display commands (AppBarCommand) that are relevant to the user's context, typically the current page or the current selection.

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

<div data-win-control="WinJS.UI.AppBar"></div>

var object = new WinJS.UI.AppBar(element, options);

Members

The AppBar object has these types of members:

Constructors
Events
Methods
Properties

Constructors

The AppBar object has these constructors.

Constructor	Description
AppBar	Creates a new AppBar object.

Events

The AppBar object has these events.

Event	Description
onafterclose	Occurs immediately after the AppBar is hidden.
onafteropen	Occurs immediately after the AppBar is displayed.
onbeforeclose	Occurs immediately before the AppBar is hidden
onbeforeopen	Occurs immediately before a closed AppBar is displayed.

Methods

The AppBar object has these methods.

Method	Description
addEventListener	Registers an event handler for the specified event.
close	Closes the app bar on Windows and the secondary command menu on Windows Phone.
dispatchEvent	Raises an event of the specified type and with additional properties.
dispose	Releases resources held by this AppBar. Call this method when the AppBar is no longer needed. After calling this method, the AppBar becomes unusable.
getCommandById	Returns the AppBarCommand object identified by id.
open	If the app bar is not disabled, opens the app bar on Windows and opens the secondary command menu on Windows Phone
removeEventListener	Removes an event handler that the addEventListener method registered.
showOnlyCommands	Shows the specified commands in the AppBar while hiding all other commands.

Properties

The AppBar object has these properties.

Property	Access type	Description
closedDisplayMode	Read/write	Gets or sets how the AppBar is displayed while hidden.
commands	Write-only	Gets and sets the AppBarCommand objects that appear in the app bar.
data	Read/write	Gets or sets a List of Command objects to display.
element	Read-only	Gets the DOM element that hosts the AppBar.
opened	Read-only	Gets a value that indicates whether the AppBar is opened or in the process of becoming opened.
placement	Read/write	Gets or sets a value that specifies whether the AppBar appears at the top or bottom of the main display view.

Remarks

Known Issues

AppBars should be direct children of document.body. Otherwise, it is possible to mask event detection on the AppBar due to stacking context effects. This is because event detection for other elements is blocked while the AppBar is open. So, if the AppBar is a child of one of those blocked elements, it too will be blocked. This behavior is typical for all overlaying controls.

Styling the AppBar

CSS classes

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

CSS class	Description
win-appbar	Styles an AppBar that uses a custom layout.
win-appbar-closed	Styles the AppBar when it is closed.
win-command	Styles commands within the AppBar.
win-commandicon	Styles the icon box for AppBar commands.
win-commandimage	Styles the images for AppBar commands.
win-commandring	Styles the icon rings for AppBar commands.
win-label	Styles labels for AppBar commands.
win-reduced	Styles commands to shrink (or drop labels) based on the window size and the number of visible AppBar buttons.

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 in an AppBar, see AppBarIcon.

The AppBar control observes the following conventions when interacting with the AppBarCommand.section property:

"primary" is for primary commands that should appear in the AppBar’s action area.

Depending on the AppBar.closedDisplayMode property, primary commands in the action area can remain visible even when the AppBar is closed.

If there is not enough room in the action area to fit all primary commands, the commands with the weakest priority order, (as determined by the AppBarCommand.priority property) will move into the overflow area and appear as secondary commands.
"secondary" is for commands that always appear in the overflow area.

Examples

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

<!-- 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

Dela via