WinJS API changes for Windows Phone 8.1(HTML)
[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]
This document lists API deprecations, functional changes, and optimizations introduced for Windows Library for JavaScript (WinJS) on Windows Phone 8.1. For other porting resources, see:
Noteworthy changes
These API changes have the highest impact in porting a Windows Runtime app using JavaScript from Windows to Windows Phone 8.1.
| Change | Type |
|---|---|
| AppBar and AppBarCommand controls | Some features not supported on phone. |
| Flyout control | Not supported on phone. |
| SettingsFlyout control | Not supported on phone. |
| DatePicker and TimePicker controls | Not supported on phone. |
| Hub control | Not supported on phone. |
| NavBar control | Not supported on phone. |
AppBar and AppBarCommand controls
Most of the features of the AppBar and AppBarCommand controls are supported on Windows Phone 8.1. However, some behaviors have changed. For example, setting the AppBarCommand.section to "global" makes the command visible in the AppBar at all times; setting it to "selection" will set the command to text-only.
Flyout control
The Flyout control is not available on Windows Phone 8.1. You can use the PopupMenu API in Windows Runtime to get the standard, full-fidelity context menu.
SettingsFlyout control
The SettingsFlyout object is not available on Windows Phone 8.1.
DatePicker and TimePicker controls
These controls are not available on Windows Phone 8.1.
Hub control
Replace with the Pivot and PivotItem controls. The members exposed by the Pivot control are very similar to the members exposed by the Hub control, which allows you to refactor a Hub control relatively quickly.
NavBar control
Replace with the AppBar and AppBarCommand controls.
New APIs for WinJS APIs on Windows Phone 8.1
The following objects are new for WinJS on Windows and Windows Phone 8.1.
| Object name |
|---|
| WinJS.UI.Pivot object and all its members |
| WinJS.UI.PivotItem object and all its members |
The following APIs have been added to existing objects and namespaces in WinJS on Windows and Windows Phone 8.1 except where noted.
| API name |
|---|
| WinJS.Application.onbackclick event (Windows Phone 8.1 only) |
| WinJS.UI.PageNavigationAnimation enumeration |
| WinJS.UI.AppBar.closedDisplayMode property |
| WinJS.UI.Animation.createPageNavigationAnimations method |
| WinJS.UI.Animation.turnstileForwardIn method |
| WinJS.UI.Animation.turnstileForwardOut method |
| WinJS.UI.Animation.turnstileBackwardIn method |
| WinJS.UI.Animation.turnstileBackwardOut method |
| WinJS.UI.Animation.slideDown method |
| WinJS.UI.Animation.slideUp method |
| WinJS.UI.Animation.slideRightIn method |
| WinJS.UI.Animation.slideRightOut method |
| WinJS.UI.Animation.slideLeftIn method |
| WinJS.UI.Animation.slideLeftOut method |
| WinJS.UI.Animation.continuumForwardIn method |
| WinJS.UI.Animation.continuumForwardOut method |
| WinJS.UI.Animation.continuumBackwardIn method |
| WinJS.UI.Animation.continuumBackwardOut method |
| WinJS.Utilities.isPhone property (Windows Phone 8.1 only) |
The following Cascading Style Sheets (CSS) styles have been added for Windows Phone 8.1.
| CSS class |
|---|
| win-semanticzoom-zoomedoutview class |
| win-semanticzoom-zoomedinview class |
Unsupported WinJS APIs on Windows Phone 8.1
Unsupported WinJS objects on Windows Phone 8.1
The following WinJS.UI controls are not supported on phone.
| Object name | Description |
|---|---|
| BackButton object and all its members | Not needed. Apps that target Windows Phone should listen for the hardware backbutton event. See WinJS.Application.onbackclick |
| CellSpanningLayout and all its members | Use GridLayout or ListLayout instead. |
| DatePicker object and all its members | Use SELECT and OPTION HTML elements. |
| Hub object and all its members | Replace with the Pivot control. See section above. |
| HubSection object and all its members | Replace with the Pivot and PivotItem controls. See previous section. |
| SwipeBehavior enumeration | Replace with phone-appropriate gestures. |
| Flyout object and all its members | Navigate to a new page or use the Windows.UI.Popup context menus. |
| Menu object and all its members | Navigate to a new page or use the Windows.UI.Popup context menus. |
| MenuCommand object and all its members | Navigate to a new page or use the Windows.UI.Popup context menus. |
| NavBar object and all its members | Replace with AppBar and AppBarCommand controls. |
| NavBarCommand object and all its members | Replace with AppBar and AppBarCommand controls. |
| NavBarContainer object and all its members | Replace with AppBar and AppBarCommand controls. |
| Rating object and all its members | Use SELECT and OPTION HTML elements. |
| SearchBox object and all its members | Use INPUT HTML element with the type attribute "text". |
| SettingsFlyout object and all its members | Navigate to a new page or use the Windows.UI.Popup context menus. |
| TimePicker object and all its members | Use SELECT and OPTION elements. |
| Tooltip object and all its members | Navigate to a new page or use the Windows.UI.Popup context menus. |
Unsupported WinJS members on Windows Phone 8.1
The following members of WinJS APIs are not supported on Windows Phone 8.1.
| API name | Description |
|---|---|
| WinJS.UI.Application.onsettings event | This event is ignored. |
| WinJS.UI.AppBar.layout property | This property is ignored. Windows Phone treats custom and commands AppBar controls the same. |
| WinJS.UI.AppBar.sticky property | This property is ignored. |
| WinJS.UI.AppBar.placement property | This property is ignored. Windows Phone treats all AppBar controls as having a placement value of "bottom". |
| WinJS.UI.AppBarCommand.lastElementFocus property | This property is ignored. |
| WinJS.UI.AppBarCommand.firstElementFocus property | This property is ignored. |
| WinJS.UI.AppBarCommand.flyout property | This property is ignored. |
| WinJS.UI.AppBarCommand.tooltip property | This property is ignored. |
| WinJS.UI.ItemContainer.swipeBehavior property | This property is not supported. Replace with phone-appropriate gestures. |
| WinJS.UI.ListView.itemsDraggable property | This property is not supported. Replace with the AppBar control to replicate the functionality. |
| WinJS.UI.ListView.onitemdragbetween event | This event is not supported. |
| WinJS.UI.ListView.onitemdragchanged event | This event is not supported. |
| WinJS.UI.ListView.onitemdragdrop event | This event is not supported. |
| WinJS.UI.ListView.onitemdragend event | This event is not supported. |
| WinJS.UI.ListView.onitemdragenter event | This event is not supported. |
| WinJS.UI.ListView.onitemdragleave event | This event is not supported. |
| WinJS.UI.ListView.onitemdragstart event | This event is not supported. |
| WinJS.UI.ListView.swipeBehavior property | This property is not supported. Replace with phone-appropriate gestures. |
| WinJS.UI.SemanticZoom.enableButton property | This property is ignored. If accessed on in a Windows Phone Store app using JavaScript, the property returns false. If set, the property silently fails. |
Unsupported CSS styles in WinJS on Windows Phone 8.1
The following CSS styles in WinJS are not supported on Windows Phone 8.1.
| CSS class | Description |
|---|---|
| win-backbutton class | Apps that target Windows Phone should listen for the hardware backbutton event. See WinJS.Application.onbackclick. |
| win-ring class | The win-ring class for PROGRESS elements is not supported on Windows Phone. |
| win-semanticzoom-button | The SemanticZoom control on Windows Phone 8.1 does not have a back button. |
Unsupported members of the MSApp object on Windows Phone
The following members of MSApp object are not supported on Windows Phone 8.1.
| Member name | Description |
|---|---|
| createNewView method | Not supported on Windows Phone. Attempting to call this method raises an error. |
| getViewOpener method | Not supported on Windows Phone. Attempting to call this method raises an error. |
| getHtmlPrintDocumentSource method | Not supported on Windows Phone. Attempting to call this method raises an error. |
| createDataPackageFromSelection method | The Data Package feature is not supported on Windows Phone. This method can be called without raising an error but does not return a data package. |
| createDataPackage method | The Data Package feature is not supported on Windows Phone. This method can be called without raising an error but does not return a data package. |
Changed WinJS behaviors on Windows Phone 8.1
Changed WinJS object members on Windows Phone 8.1
The behavior of the following members of WinJS APIs have been changed on Windows Phone 8.1.
| API element | Description of change |
|---|---|
| WinJS.UI.AppBar.hide method | Makes the AppBar go to its closed state. |
| WinJS.UI.AppBar.show method | Makes the AppBar go to its opened state. |
| WinJS.UI.AppBarCommand.type property | The values "flyout" and "separator" are not supported. Setting this property does not raise an error. However, if the AppBarCommand is hosted in a DIV or HR element, an error is raised. |
| WinJS.UI.AppBarCommand.section property | Buttons in the "global" section appear in the app bar, up to the last four buttons declared. Buttons marked as "selection" are displayed as menu items (secondary commands) . |
| WinJS.UI.ListView.selectionMode property | The value "single" is no longer supported. |
Changed CSS styles in WinJS on Windows Phone 8.1
The following CSS styles in WinJS behave differently on Windows Phone 8.1.
| CSS class | Description of change |
|---|---|
| win-appbar class | Set the background color and background opacity of the AppBar. CSS opacity is ignored. Opacity can be set only with background-color style. |
| win-command class | Set the label and icon color of child AppBarCommand controls. |
| win-label class | Set the label and icon color of child AppBarCommand controls. |
Related topics
How to port a Windows Runtime app using JavaScript to Windows Phone