Share via


SP.ListItem object

Represents an item or row in a list.

Applies to: apps for SharePoint | SharePoint Foundation 2013 | SharePoint Server 2013

var object = new SP.ListItem()

Members

The ListItem object has the following members.

Constructor

The ListItem object has the following constructor.

Constructor

Description

ListItem

Initializes a new instance of the SP.ListItem object.

Methods

The ListItem object has the following methods.

Method

Description

deleteObject

Deletes the list item.

getUserEffectivePermissions

Gets the effective permissions that a specified user has on the list item.

getWOPIFrameUrl

Gets the full URL to the SharePoint frame page that initiates the SP.Utilities.SPWOPIFrameAction object with the WOPI application associated with the list item.

initNonPropertiesFromJson

loadExpandoFields

Initializes the extended properties associated with the list item.

parseAndSetFieldValue

Sets the value of the field for the list item based on an implementation specific transformation of the value.

recycle

Moves the list item to the Recycle Bin and returns the identifier of the new Recycle Bin item.

refreshLoad

Reloads the extended properties associated with the list item.

update

Commits changed properties of the list item.

validateUpdateListItem

Validates and sets the values of the specified collection of fields for the list item.

Properties

The ListItem object has the following properties.

Property

Description

attachmentFiles

Specifies the collection of attachments that are associated with the list item.

contentType

Gets a value that specifies the content type of the list item.

displayName

Gets a value that specifies the display name of the list item.

effectiveBasePermissions

Gets a value that specifies the effective permissions on the list item that are assigned to the current user.

effectiveBasePermissionsForUI

Gets the effective base permissions for the current user, as they should be displayed in UI.

fieldValues

Gets a collection of key/value pairs containing the names and values for the fields of the list item.

fieldValuesAsHtml

Gets the values for the list item as HTML.

fieldValuesAsText

Gets the list item's field values as a collection of string values.

fieldValuesForEdit

Gets the formatted values to be displayed in an edit form.

file

Gets the file that is represented by the item from a document library.

fileSystemObjectType

Gets a value that specifies whether the list item is a file or a list folder.

folder

Gets a folder object that is associated with a folder item.

id

Gets a value that specifies the list item identifier.

item

Gets or sets the specified field value.

parentList

Gets the parent list that contains the list item.

Remarks

Contains CSOM expando fields, which correspond to the fields defined in the parent list. The CSOM expando field name is the name of the field defined in the list, and the CSOM expando field value is the field value in the list item. The following table defines the mapping between field types and values.

Field Type

CSOM Expando Field Value Type

Meaning

Integer

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Int32.

Allows an integer value.

Text

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM String.

Allows a limited-length string of text.

Note

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM String.

Allows larger amounts of text.

DateTime

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM DateTime.

Allows full date and time values, as well as date-only values.

Counter

It must be CSOM Int32.

Allows a monotonically increasing integer field, which has a unique value in relation to other values that are stored for the field in the list. Counter is used only for the list item ID field, and not intended for use elsewhere.

Choice

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM String.

Allows selection from a set of suggested values. A choice field supports a field-level setting which specifies whether free-form values are supported.

Lookup

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Object.

Allows a reference to another list item. The field supports specification of a list identifier for a targeted list. An optional site ID can also be specified, which specifies the site of the list which contains the target of the lookup.

Boolean

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Boolean.

Allows a true or false value.

Number

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Double.

Allows a positive or negative number. A number field supports a field level setting used to specify the number of decimal places to display.

Currency

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Double.

Allows for currency-related data. The Currency field has a CurrencyLocaleId property which takes a locale identifier of the currency to use.

URL

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Object.

Allows a URL and optional description of the URL.

Computed

N/A

Renders output based on the value of other columns.

Threading

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM String.

Contains data on the threading of items in a discussion board.

Guid

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM GUID.

Specifies that the value of the field is a GUID.

MultiChoice

When its value is undefined; it must be CSOM null; otherwise, it must be CSOM Array.

Allows one or more values from a set of specified choices. A MultiChoice field can also support free-form values.

GridChoice

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Array.

Supports specification of multiple number scales in a list.

Calculated

N/A

Calculated based on the value of other columns.

File

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM String.

Specifies a reference to a file that can be used to retrieve the contents of that file.

Attachments

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Boolean.

Describes whether one or more files are associated with the item. true if a list item has attachments, and false if a list item does not have attachments.

User

When its value is undefined, it MUST be CSOM null; otherwise, it must be CSOM Object.

Contains a lookup to a particular user in the User Info list.

Recurrence

When its value is undefined, it MUST be CSOM null; otherwise, it must be CSOM Boolean.

Specifies whether a field contains a recurrence pattern for an item.

CrossProjectLink

When its value is undefined, it MUST be CSOM null; otherwise, it must be CSOM Boolean.

Allows a link to a Meeting Workspace site.

ModStat

When its value is undefined, it MUST be CSOM null; otherwise, it must be CSOM int32.

Specifies the current status of a moderation process on the document.

Error

N/A

Specifies errors. Value = 24.

ContentTypeId

When its value is undefined, it MUST be CSOM null; otherwise, it MUST be CSOM Object.

Contains a content type ID for an item. ContentTypeId conforms to the structure defined in ContentTypeId.

PageSeparator

N/A

Represents a placeholder for a page separator in a survey list. PageSeparator is only intended to be used with a Survey list.

ThreadIndex

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM String.

Contains a compiled index of threads in a discussion board.

WorkflowStatus

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Int32.

Contains status on a running workflow for a particular item.

AllDayEvent

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Boolean.

Used only in conjunction with an Events list. true if the item is an all-day event (that is, does not occur during a specific set of hours in a day).

WorkflowEventType

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Int32.

A description of a type of a historical workflow event. For more information, see WorkflowEventTypeEnumeration

Facilities

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Array.

Contains the facility or assets of the specified resource group.

FreeBusy

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM String.

Contains the free/busy information of the schedule.

Overbook

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM String.

Contains the double-booking information for the schedule.

Confidential

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Boolean.

Indicates whether this circulation can be viewed only by those to whom it was sent.

WhatsNew

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Boolean.

Indicates whether the current personal items are new in the group site.

DueDate

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM DateTime.

Contains the date and time when the task is expected to be finished.

AllowEditing

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Boolean.

Indicates whether a user who is not the author can edit the content of this resource.

SendTo

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Array

Contains the users to whom this circulation was sent.

Confirmations

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM String.

Contains the confirmation information of this circulation.

CallTo

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Array.

Contains the recipients who should track this note information.

CallTime

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM DateTime.

Contains the date and time when this call was made.

Whereabout

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM String.

Contains the location of the user.

From

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM DateTime.

Contains the date and time when Whereabouts status begins.

Until

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM DateTime.

Contains the date and time when the Whereabouts status ends.

ContactInfo

When its value is undefined, it must be CSOM null; otherwise, it must be CSOM String.

Contains the contact list of the user.

Example

The following example creates an input button on an application page that adds an item to the Announcements list on the current Web site.

<asp:Content ID="Main" ContentPlaceHolderID="PlaceHolderMain" runat="server">
<script type="text/ecmascript" language="ecmascript">

    function runCode() {

        var clientContext = new SP.ClientContext();
        var targetList = clientContext.get_web().get_lists().getByTitle('Announcements');
        var itemCreateInfo = new SP.ListItemCreationInformation();

        this.newListItem = targetList.addItem(itemCreateInfo);

        newListItem.set_item('Title', 'MyNewAnnouncement');
        newListItem.set_item('Body', 'Hello World!');
        newListItem.update();
        clientContext.load(newListItem);

        clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed));
    }

    function onQuerySucceeded() {

        alert('Announcement created!\n\nId: ' + newListItem.get_id() + '\nTitle: ' + newListItem.get_item('Title'));
    }

    function onQueryFailed(sender, args) {

        alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
    }

</script>

    <input id="Button1" type="button" value="Run Code" onclick="runCode()" />

</asp:Content>

REST resource endpoint

See ListItem resource for more information.

Endpoint URI structure

http://<sitecollection>/<site>/_api/web/lists(listid)/items(itemid)

HTTP requests

This resource supports the following HTTP commands:

DELETE syntax

DELETE http://<sitecollection>/<site>/_api/web/lists(listid)/items(itemid)

MERGE syntax

MERGE http://<sitecollection>/<site>/_api/web/lists(listid)/items(itemid)

POST syntax

POST http://<sitecollection>/<site>/_api/web/lists(listid)/items(itemid)