插件 jQuery.xmlrpc 中文API文档
插件 jQuery.xmlrpc 中文API文档
源码 & 下载
- Github地址：https://github.com/timheap/jquery-xmlrpc
- 源码下载： -
- 效果演示： -
插件特点
这是一个位于jQuery之上的小型库，用于与XML-RPC服务进行通信 - 而不用担心XML-RPC的可怕臃肿。使用此库，您可以将JSON参数传递给库，并以JSON格式接收响应。为您处理编码JSON文档，智能地映射两种语言之间的类型。
基本用法
只需在页面中包含jQuery库和此库：
<script src="jquery-1.8.1.js"></script>
<script src="jquery.xmlrpc.js"></script>
这是建立在jQuery 1.8.1之上的。它可能适用于旧版本，并可能继续使用新版本。
该 jQuery.xmlrpc 功能是该库的主要工作原理。
这样：
$.xmlrpc({
url: '/RPC2',
methodName: 'foo',
params: ['bar', 1, 4.6, true, [1, 2, 3], {name: 'value'}],
success: function(response, status, jqXHR) { /* ... */ },
error: function(jqXHR, status, error) { /* ... */ }
});
它需要所有相同的参数jQuery.ajax，因此请参考更多文档。添加的两个新密钥是：
methodName
这是放在 <methodName> XML-RPC元素中的方法。它应该是一个字符串。与之通信的XML-RPC服务将确定您可以调用的有效方法名称。
params
要发送的参数数组。如果您不想发送任何参数，请指定一个空数组，或者根本不提供此键。
有关更多信息，请参阅有关编码和解码XML-RPC文档的文档部分。
获取数据
当XML-RPC调用返回时，<params>元素的内容被解析为JSON并success作为第一个参数提供给AJAX调用的回调，就像JSON请求一样。
错误处理
如果在传输过程中出现任何HTTP错误，将使用正常的jQuery AJAX错误处理。如果XML-RPC服务成功回复，但回复了<fault>响应，$.xmlrpc.XmlRpcFault则抛出一个。error与其他错误一样，此错误将作为第三个参数发送到AJAX调用的回调。
类型
JSON和XML-RPC是两种不相关的标记语言，因此在类型之间进行转换需要对这两种语言有一点了解。幸运的是，大多数类型都有两种语言之间的直接映射。
编码和解码XML-RPC文档
使用下表查看XML-RPC类型如何映射到JavaScript类型：
| XML-RPC | JavaScript |
|---|---|
| < nil> | null |
| < array> | Array |
| < struct> | Object |
| < string> | String |
| < boolean> | Boolean |
| < int> | Number |
| < i4> | Number |
| < i8> | Number |
| < i16> | Number |
| < double> | Number |
| < dateTime.iso8601> | Date |
| < base64> | ArrayBuffer |
注意:JavaScript没有用于整数和浮点数的单独类型，它只有Number。因此，无法判断4是否真的意味着
<int>4</int>或<double>4</double>。如果这对您来说是一个问题，请继续阅读。
强制类型
有时，从JSON到XML-RPC的自动类型猜测可能对您不起作用。此问题的最常见来源是编码数字。库有时可以将Number编码为<int>而不是<float>，因为没有可靠的方法来确定实际需要的内容。
要强制类型，请在对$ .xmlrpc.force的调用中包装该值。这些类型以XML-RPC等价物命名，如上表所述。
要强制将浮点JavaScript 编号 编码为<i8> 并作为参数发送，请使用以下命令：
var forcedValue = $.xmlrpc.force('i8', 4.5)
$.xmlrpc({
url: '/RPC2',
methodName: 'foo',
params: [forcedValue]
});
添加和扩展类型
您可以通过将成员添加到$ .xmlrpc.types并与$ .xmlrpc.makeType函数结合，将您自己的类型添加到XML-RPC 。有关更多信息，请参阅 $ .xmlrpc.makeType（）
API
如果您需要扩展此库，则会公开以下API。您不必在日常使用库时使用此API。
$.xmlrpc()
调用远程过程。这是jQuery.ajax() 的一个小包装器， 因此请参阅相关文档以获取更多信息。它需要以下参数：
网址
要调用的服务的URL。可选的。如果未指定，则从选项dict中提取
选项
请求的选项。大多数选项直接传递给 jQuery.ajax()，但两个键除外。
该方法名键必须提供，并且必须是一个字符串。它用作调用的 < methodName>
该PARAMS键可以用来发送参数。这必须是一个值数组。保留此空白，或提供并清空数组以不发送任何参数。
有关如何将JavaScript类型转换为XML-RPC类型的更多信息，请参阅类型
获取数据
当XML-RPC调用返回时，< params>元素的内容被解析为JSON并作为第一个参数提供给AJAX调用的成功回调，就像JSON请求一样。
处理错误
如果在传输过程中出现任何HTTP错误，将使用正常的jQuery AJAX错误处理。如果XML-RPC服务成功回复，但回复<fault>响应，则抛出 $.xmlrpc.XmlRpcFault。
与其他错误一样，此错误将作为第三个参数发送到AJAX调用的错误回调。
$.xmlrpc.document()
根据方法名称和一组参数创建XML-RPC文档。它需要以下参数：
方法名
这是放在XML-RPC 的<methodName>元素中的方法。它应该是一个字符串。与之通信的XML-RPC服务将确定您可以调用的有效方法名称。
PARAMS
要发送的参数数组。如果您不想发送任何参数，请指定一个空数组。
JavaScript调用：
$.xmlrpc.document('foo', ['bar, true, [1, 2, 3]]);
生成以下XML文档（没有空格）：
<methodCall>
<methodName>foo</methodName>
<params>
<param>
<value><string>bar</string></value>
</param>
<param>
<value><boolean>1</boolean></value>
</param>
<param>
<value><array><data>
<value><int>1</int></value>
<value><int>2</int></value>
<value><int>3</int></value>
</data></array></value>
</param>
</params>
</methodCall>
$.xmlrpc.toXmlRpc()
获取值，并将其编码为XML-RPC节点。因为XML节点必须由XML文档自己的createElement创建，所以在调用$ .xmlrpc.document之外不能使用它。它需要以下参数：
值
要编码的值
$XML
帮助函数，用于在文档上创建XML节点。然后返回，由jQuery包装。
$.xmlrpc.parseDocument()
解析XML-RPC文档，并返回其内容。如果文档表示XML-RPC错误，则抛出 $.xmlrpc.XmlRpcFault。它需要以下参数：
示例
以下XML文档：
<?xml version="1.0"?>
<methodResponse>
<params>
<param>
<value><string>foo</string></value>
</param>
<param>
<value><int>3</int></value>
</param>
<param>
<value><struct>
<member>
<name>foo</name>
<value><i4>1</i4></value>
</member>
<member>
<name>bar</name>
<value><i4>2</i4></value>
</member>
</struct></value>
</param>
</params>
</methodResponse>
解析者：
$.xmlrpc.parseDocument(doc);
会导致JSON文档：
[
'foo',
3,
{
foo: 1,
bar: 2
}
]
$ .xmlrpc.parseNode（）
获取单个XML元素，并返回其等效的JSON。它需要一个论点：
节点
要解码的XML节点。它应该是使用$ .xmlrpc.makeType（）注册的类型之一 。如果找不到类型，则抛出错误。
示例
XML元素：
<struct>
<member>
<name>foo</name>
<value><i4>1</i4></value>
</member>
<member>
<name>bar</name>
<value><i4>2</i4></value>
</member>
</struct>
将通过调用解析：
$.xmlrpc.parseNode(node)
产生JSON：
{
foo: 1,
bar: 2
}
$ .xmlrpc.makeType（）
将XML-RPC类型添加到库中。然后，库将在返回时知道如何解码此类型的元素。它需要以下参数：
标签
此表示的XML-RPC元素的名称。示例：‘boolean’
简单
如果元素是简单类型。除
编码
获取JavaScript值，并将其编码为XML-RPC元素。接收要编码的值，以及用于在正确文档上创建XML节点的辅助函数 - 此帮助必须用于为子元素创建XML节点。
简单类型只需要返回节点的文本，创建节点就是为您处理的。
解码
获取XML元素，并将其解码为JavaScript表示形式。
简单类型接收节点的文本而不是节点本身。
示例
一个简单的布尔节点：
// Boolean type. True == '1', False == '0'
$.xmlrpc.makeType('boolean', true, function(value) {
return value ? '1' : '0';
}, function(text) {
return text == '1';
});
一个复杂的自定义元素：
/**
* Convert
* {foo: 1, bar: "hello"}
* into
* <custom><foo>1</foo><bar><string>hello</string></bar></custom>
* Note the call to `$.xmlrpc.toXmlRpc`` to recursively encode the `bar` element.
*/
$.xmlrpc.makeType('custom', false, function(value, $xml) {
return $xml('custom').append([
$xml('foo').text($.xmlrpc.toXmlRpc(value.foo, $xml)),
$xml('bar').text($.xmlrpc.toXmlRpc(value.foo, $xml))
]);
}, function(node) {
return {
foo: parseInt($(node).find('> foo').text()),
bar: fromXmlRpc($(node).find('> bar > *').get(0)),
}
});
$.xmlrpc.force()
强制在XML-RPC中将值编码为特定类型。它需要以下参数：
类型
强制值的类型。[types documentation] [types]中指定的XML-RPC类型之一，或者使用$ .xmlrpc.makeType添加的自定义类型 之一。
值
将被编码为类型的任何值。
示例
强制将浮点数编码为i8，作为参数发送：
var forcedValue = $.xmlrpc.force('i8', 4.5)
$.xmlrpc({
url: '/RPC2',
methodName: 'foo',
params: [forcedValue]
});
