3.2 JaveScript客户端对象模型
作为客户端对象模型的一种，JaveScript客户端对象模型和.NET客户端对象模型在使用步骤上很类似：
● 初始化ClientContext对象
● 通过ClientContext对象获取到Site/Web对象
● 调用ClientContext.Load方法，定义要获取的信息
● 调用clientContext.executeQueryAsync方法把请求提交到SharePoint
要使用JaveScript客户端对象模型，需要程序开发人员懂的一些基础的JavaScript（JQuery）语法。
3.2.1 环境准备
JaveScript客户端对象模型可以被使用在SharePoint页面或者SharePoint Add-in上。本节将以一个内容编辑器Web部件来存放代码，演示JaveScript客户端对象模型的使用。
在开始之前，先把JQuery上传到网站自带的样式库里，以备后面使用。JQuery是一款优秀的JavaScript库，使用它能让前台开发更方便，并且能兼容多浏览器。
打开上一节用的站点，打开一个页面或者新建一个页面，然后编辑页面，在功能区里，单击插入→Web部件，在“媒体和内容”分类里，选择“内容编辑器”，然后单击“添加”按钮，如图3-14所示：
图3-14 添加内容编辑器Web部件
添加到页面之后，编辑Web部件，如图3-15所示：
图3-15 编辑web部件
在右边的编辑窗口里，找到内容链接的输入框。本节用到JavaScript代码，都会被保存在.js文件里，并上传到顶层站点的样式库里，然后在这里引用，如图3-16所示：
图3-16 引用JaveScript代码
3.2.2 ClientContext
在JaveScript客户端对象模型中，ClientContext是一切对象的入口，因此首先要初始化这个对象。ClientContext的初始化方法如下：
ClientContext context = new ClientContext("http://mysiteurl");
如果要获取当前站点，则使用：
ClientContext.get_current();
和.NET客户端不同的是，JaveScript客户端模型的代码运行在SharePoint上下文环境里，因此并不需要提供用户名密码。
JaveScript客户端对象模型和服务器端对象模型的结构是一样的，但是在命名上去掉了SP，表3-2是对照表：
表3-2 JaveScript客户端对象模型和服务器端对象模型的比较
3.2.3 Site和Web对象
1．获取Site对象
获取Site对象的方法如下：
clientContext.get_Site();
同样，这个时候并没有真正地把Site对象获取过来，需要先执行ClientContext.Load()方法把操作预加载一下，然后执行clientContext.executeQueryAsync方法。
为了不阻塞页面的加载，SharePoint在JavaScript对象模型里提供了clientContext.executeQueryAsync方法，这个方法会把请求发给SharePoint，并且异步获取结果。在接收返回结果的时候，开发人员可以定义两个方法，一个处理结果成功返回的情况，一个处理失败的情况。
下面的代码演示如何获取站点的URL：
<script type='text/javascript'>
var clientContext;
var siteCollection;
SP.SOD.executeFunc('sp.js', 'SP.ClientContext', LoadSite);
function LoadSite() {
clientContext = SP.ClientContext.get_current();
siteCollection = clientContext.get_site();
clientContext.load(siteCollection);
clientContext.executeQueryAsync(onRequestSucceeded, onRequestFailed);
}
function onRequestSucceeded() {
alert('Site Collection URL: ' + siteCollection.get_url());
}
function onRequestFailed(sender, args) {
alert('Error: ' + args.get_message());
}
</script>
SP.SOD.executeFunc('sp.js', 'SP.ClientContext', LoadSite); 这句话的意思是，等sp.js加载完毕，再执行LoadSite方法，从而避免出错。
在上面的例子里，如果请求成功返回，就把网站的URL显示出来；如果请求失败，就把失败的消息显示出来。
把上面的代码保存成siteDemo.js，上传到样式库里，注意一下，样式库默认开启了版本控制，因此每次上传都要记住发布一个主要版本。在内容编辑器Web部件的编辑窗口里引用siteDemo.js，最后单击应用，结果如图3-17所示。
图3-17 获取网站集URL
2．获取Web对象
获取Web对象，有两种方法：
● 通过Site对象的OpenWeb(“myWebRelativeURL”)方法，如果参数为空，那么返回顶层站点的对象。
● 通过ClientContext的get_web()方法，获取当前上下文环境的站点。
下面的代码演示如何获取Web对象的标题和说明：
<script type='text/javascript'>
var clientContext;
var website;
SP.SOD.executeFunc('sp.js', 'SP.ClientContext', LoadWeb);
function LoadWeb() {
clientContext = SP.ClientContext.get_current();
website = clientContext.get_web();
clientContext.load(website);
clientContext.executeQueryAsync(onRequestSucceeded, onRequestFailed);
}
function onRequestSucceeded() {
alert('标题: ' + website.get_title()+"\n 说明:"+website.get_description());
}
function onRequestFailed(sender, args) {
alert('Error: ' + args.get_message());
}
</script>
把代码保存成webDemo.js，按照上面的方法引用到内容编辑器Web部件里，结果如图3-18所示。
图3-18 获取Web标题和说明
上面的代码获取了完整的Web对象，同样，为了减少数据传输，可以仅获取特定的属性，这就要在ClientContext.Load()方法里指定要获取的属性：
clientContext.load(website, 'Title', 'Created');
如何更新Web的属性呢？这就要调用Web对象的set_[property]方法了。
<script type='text/javascript'>
var clientContext;
var website;
SP.SOD.executeFunc('sp.js', 'SP.ClientContext', UpdateWeb);
function UpdateWeb() {
clientContext = SP.ClientContext.get_current();
website = clientContext.get_web();
website.set_title('Updated Web Site');
website.set_description('This is an updated Web site.');
website.update();
clientContext.load(website, 'Title', 'Description');
clientContext.executeQueryAsync(onRequestSucceeded, onRequestFailed);
}
function onRequestSucceeded() {
alert('标题: ' + website.get_title()+"\n 说明:"+website.get_description());
}
function onRequestFailed(sender, args) {
alert('Error: ' + args.get_message());
}
</script>
3.2.4 List对象
使用Web类的lists属性获取网站中列表的集合，步骤和获取网站对象类似，先调用load(clientObject) 方法加载列表集合，然后调用executeQueryAsync(succeededCallback, failedCallback)。
1．获取列表信息
以下的代码演示如何获取网站所有列表的标题以及说明，并显示在表格里。
首先定义一个id为lists的div，作为容器：
<div id="lists"></div>
为了使JaveScript编程更简单，在这里引用JQuery。
<script type='text/javascript' src="/sites/dept/Style%20Library/jquery-
1.11.3.min.js">
</script>
然后获取列表的信息：
<script type='text/javascript'>
SP.SOD.executeFunc('sp.js', 'SP.ClientContext', retrieveAllListProperties);
function retrieveAllListProperties() {
var clientContext = new SP.ClientContext();
var oWebsite = clientContext.get_web();
this.collList = oWebsite.get_lists();
clientContext.load(collList);
clientContext.executeQueryAsync(
Function.createDelegate(this, this.onQuerySucceeded),
Function.createDelegate(this, this.onQueryFailed)
);
}
function onQuerySucceeded() {
var listInfo = '<table><tr><th>标题</th><th>说明</th></tr>';
var listEnumerator = collList.getEnumerator();
while (listEnumerator.moveNext()) {
var oList = listEnumerator.get_current();
listInfo += '<tr><td>' + oList.get_title() + '<td/><td>' +
oList.get_description().toString() + '</td></tr>';
}
listInfo+="</table>";
$('#lists').html(listInfo);
}
function onQueryFailed(sender, args) {
$('#lists').html('Request failed. ' + args.get_message() +
'</br>' + args.get_stackTrace());
}
</script>
在上面的代码里，先是定义了一个id为lists的div，然后引用JQuery，再把获取到的列表信息组装成一个表格，显示在div里面，结果如图3-19所示。
图3-19 获取列表信息
如果要减少不必要的数据传输，可以只获取列表的必要属性，修改ClientContext.Load方法为：
clientContext.load(collList, 'Include(Title, Description)');
2．创建列表
创建列表需要借助于ListCreationInfo类，主要代码如下：
var listCreationInfo = new SP.ListCreationInformation();
listCreationInfo.set_title('My Announcements List');
listCreationInfo.set_templateType(SP.ListTemplateType.announcements);
this.oList = oWebsite.get_lists().add(listCreationInfo);
然后调用ClientContext的Load和executeQueryAsync方法把请求提交到SharePoint里。
3．更新列表
要更新列表属性，调用list.set_[property]方法：
oList.set_description('New Announcements List');
oList.update();
然后调用ClientContext的Load和executeQueryAsync方法把请求提交到SharePoint里。
4．删除列表
删除列表的主要代码如下：
this.oList = oWebsite.get_lists().getByTitle('My Announcements List');
oList.deleteObject();
然后调用ClientContext的executeQueryAsync方法把请求提交到SharePoint里。
3.2.5 ListItem对象
若要使用JavaScript客户端对象模型获取列表项，可使用getItemById(id) 函数返回单个项，也可使用getItems(query) 函数返回多个项。然后使用load(clientObject) 函数获取代表这些项的列表项对象。getItems(query) 函数仍然使用CAML查询，以指定要返回哪些项。为了减少数据传输，不建议获取所有的列表项，也不建议获取所有的栏值。应该只查询需要的列表项和栏。
1．获取列表项
下面的代码演示如何获取通知列表项里面，最新添加的5条通知。
var clientContext = new SP.ClientContext();
var oList = clientContext.get_web().get_lists().getByTitle('通知');
var camlQuery = new SP.CamlQuery();
camlQuery.set_viewXml(
'<View><Query><OrderBy><FieldRef Name="Created" Ascending="FALSE"
/></OrderBy></Query>' +
'<RowLimit>5</RowLimit></View>'
);
this.collListItem = oList.getItems(camlQuery);
然后调用ClientContext的Load和executeQueryAsync方法把请求提交到SharePoint里。结果如图3-20所示。
图3-20 获取最新5个通知
如果只想获取特定的属性，以减少数据传输，那么需要修改ClientContext.Load方法：
clientContext.load(
collListItem,
'Include(Id, DisplayName, HasUniqueRoleAssignments)'
);
2．创建列表项
创建列表项需要借助ListItemCreationInformation对象。下面的代码演示如何创建一个列表项，并为栏赋值：
var oList = clientContext.get_web().get_lists().getByTitle('Announcements');
var itemCreateInfo = new SP.ListItemCreationInformation();
this.oListItem = oList.addItem(itemCreateInfo);
oListItem.set_item('Title', 'My New Item!');
oListItem.set_item('Body', 'Hello World!');
oListItem.update();
之后再调用ClientContext的Load和executeQueryAsync方法把请求提交到SharePoint里。
3．更新列表项
更新列表项的主要代码如下：
this.oListItem = oList.getItemById(3);
oListItem.set_item('Title', 'My Updated Title');
oListItem.update();
之后再调用ClientContext的executeQueryAsync方法把请求提交到SharePoint里。
4．删除列表项
删除列表项的主要代码如下：
oListItem = oList.getItemById(itemId);
oListItem.deleteObject();
之后再调用ClientContext的executeQueryAsync方法把请求提交到SharePoint里。