Document.getSelectedDataAsync method (JavaScript API for Office)

Office Add-ins

Reads the data contained in the current selection of the document.

Last modified: August 04, 2015

Note Note

The name "apps for Office" is changing to "Office Add-ins". During the transition, the documentation and the UI of some Office host applications and Visual Studio tools might still use the term "apps for Office". For details, see New name for apps for Office and SharePoint.

Hosts:

Access, Excel, PowerPoint, Project, Word

Available in requirement sets

Selection

Last changed in Selection

1.1

See all support details

Try it out

Office.context.document.getSelectedDataAsync(coercionType [, options], callback); 

Name

Type

Description

Support notes

coercionType

CoercionType

Host support

Office.CoercionType.Text (string)

Excel, Excel Online, PowerPoint, PowerPoint Online, Word, and Word Online only

Office.CoercionType.Matrix (array of arrays)

Excel, Word, and Word Online only

Office.CoercionType.Table (TableData object)

Access, Excel, Word, and Word Online only

Office.CoercionType.Html

Word only.

Office.CoercionType.Ooxml (Office Open XML)

Word and Word Online only

Office.CoercionType.SlideRange

PowerPoint, and PowerPoint Online only

The type of data structure to return. Required.

options

object

Specifies any of the following optional parameters

valueFormat

ValueFormat

Specifies whether to return the result with its number or date values formatted or unformatted.

filterType

FilterType

Specifies whether to apply filtering when the data is retrieved. Optional.

This parameter is ignored in Word documents.

asyncContext

array, boolean, null, number, object, string, or undefined

A user-defined item of any type that is returned in the AsyncResult object without being altered.

callback

object

A function that is invoked when the callback returns, whose only parameter is of type AsyncResult.

When the function you passed to the callback parameter executes, it receives an AsyncResult object that you can access from the callback function's only parameter.

In the callback function passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return the following information.

Property

Use to...

AsyncResult.value

Access the values in the current selection, which are returned in the data structure or format you specified with the coercionType parameter. (See Remarks for more information about data coercion.)

AsyncResult.status

Determine the success or failure of the operation.

AsyncResult.error

Access an Error object that provides error information if the operation failed.

AsyncResult.asyncContext

Access your user-defined object or value, if you passed one as the asyncContext parameter.

In your task pane or content app, use the getSelectedDataAsync method to write script that reads the data from the user's selection in a document, spreadsheet, presentation, or project. For example, after a user selects content in a Word document, you can use the getSelectedDataAsync method to read that selection, and then submit it to a web service as a query or some other operation.

After reading the selection, you can also use the setSelectedDataAsync and addHandlerAsync methods of the Document object to write back to the selection or add an event handler to detect if the user changes the selection.

The getSelectedDataAsync method can read from the selection only as long as it's active. In apps for Word and Excel, if you need to make a persistent association to read and write to the user's selection, instead use the Bindings.addFromSelectionAsync method to bind to that selection.

Use the coercionType parameter of the getSelectedDataAsync method to specify the data structure or format of the selected data being read.

Specified coercionType

Data returned

Office host application support

Office.CoercionType.Text or "text"

A string.

Word, Excel, PowerPoint, and Project.

Note Note

In Excel, even when a subset of a cell is selected, the entire cell contents are returned.

Office.CoercionType.Matrix or "matrix"

An array of arrays. For example, [['a','b'], ['c','d']] for a selection of two rows in two columns.

Word and Excel.

Office.CoercionType.Table or "table"

A TableData object for reading a table with headers.

Word and Excel.

Office.CoercionType.Html or "html"

In HTML format.

Word only.

Office.CoercionType.Ooxml or "ooxml"

In Open Office XML (OpenXML) format.

Word only.

Tip Tip

When developing your app's code, you can use the "ooxml"coercionType of the getSelectedDataAsync method to see how the content you select in a Word document is defined as OpenXML tags. Then, use those tags in the data parameter of the Document.setSelectedDataAsync method to write content with that formatting or structure to a document. For example, you can insert an image into a document as OpenXML.

Office.CoercionType.SlideRange or "slideRange"

A JSON object that contains an array of the ids, titles, and indexes of the selected slides.

For example, {"slides":[{"id":257,"title":"Slide 2","index":2},{"id":256,"title":"Slide 1","index":1}]} for a selection of two slides.

PowerPoint only.

If the data structure of the selection doesn't match the specified coercionType, the getSelectedDataAsync method will attempt to coerce the data into that type or structure. If the selection can't be coerced into the Office.CoercionType you specified, the AsyncResult.status property returns "failed".

To read the value of the current selection, you need to write a callback function that reads the selection. The following example shows how to:

  • Pass an anonymous callback function that reads the value of the current selection to the callback parameter of the getSelectedDataAsync method.

  • Read the selection as text, unformatted, and not filtered.

  • Display the value on the app's page.

function getText() {
    Office.context.document.getSelectedDataAsync(Office.CoercionType.Text, 
        { valueFormat: "unformatted", filterType: "all" },
        function (asyncResult) {
            var error = asyncResult.error;
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                write(error.name + ": " + error.message);
            } 
            else {
                // Get selected data.
                var dataValue = asyncResult.value; 
                write('Selected data is ' + dataValue);
            }            
        });
}

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

A checkmark (√) in the following matrix indicates that this method is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this method.

For more information about Office host application and server requirements, see Requirements for running apps for Office.

Supported hosts, by platform

Office for Windows desktop

Office Online
(in browser)

Office for iPad

Access

Excel

PowerPoint

Project

Word

Available in requirement sets

Selection

Minimum permission level

ReadDocument (ReadAllDocument required to get Office Open XML)

App types

Content, task pane

Library

Office.js

Namespace

Office

Version

Changes

1.1

In Word Online, added support for Office.CoercionType.Matrix and Office.CoercionType.Table as the coercionType parameter.

1.1

In Excel and Word in Office for iPad, added the same level of support as Excel and Word on Windows desktop.

1.1

In Word Online, added support for Office.CoercionType.Text as the coercionType parameter.

1.1

In content apps for PowerPoint, you can get the ids, titles, and indexes of the selected range of slides by passing Office.CoercionType.SlideRange as the coercionType parameter of the getSelectedDataAsync method. See the Document.goToByIdAsync method topic for an example of how to use this value to navigate to the currently selected slide.

1.0

Introduced

Show:
© 2015 Microsoft