我们保证每页只显示一个小型广告。别担心，隐藏此消息将确保您不会再次被烦扰。
与 UI 无缝集成
API 旨在使将数据源集成到 UI 组件的过程变得无缝，将 API 请求状态 自动绑定到 UI 状态。
例如，将 API 行为添加到 input 将在 oninput 事件中发生，而 button 将在 onclick 事件中查询服务器。
保留模板化的 URL
API 帮助您将 URL 与代码分离。在代码中使用命名的 API 操作，例如 获取关注者，而不是像 http://foo.com/get/1.0/followers.json 这样的 URL。
$('.button') .api({ action: 'get followers' }) ;
集中管理您的整个 API，确保您不会在整个代码库中修改 URL。使用 直观的模板系统 定义您的端点，该系统会 自动传递 您在 UI 中找到的数据。
$.fn.api.settings.api = { 'get followers' : '/followers/{id}?results={count}', 'create user' : '/create', 'add user' : '/add/{id}', 'search' : '/query/{query}/{/sort}' };
HTTP 200 不是成功
在回调触发之前解析您的 JSON 以获取 success 条件，确保正确捕获服务器错误，并在您的前端代码中触发错误条件。
// 没有此状态的响应将触发错误条件 $.fn.api.settings.successTest = function(response) { return response.status == 'OK'; }
动态翻译 API
使用使用一些混乱代码的第三方 API？没问题！API 允许您 修改 API 的原始 JSON 响应，然后再让您的代码使用它。
用于第三方集成和模拟的工具
新的强大回调，例如 response 和 responseAsync，允许您异步模拟响应并触发与 API 相同的回调。
API 示例
帕特里克·拉塞尔
帕特里克住在旧金山，学习法语文学。
创建 API
API 操作
API 通过定义一组服务器操作来工作，这些操作可以被元素查询。操作通常用简短的短语表示，例如 保存配置文件 或 获取关注者，它们对应于服务器上模板化的 URL 资源。
操作中指定的 URL 变量会在运行时被替换，允许各个组件查询不同的 URL。
您 API 中列出的 URL 可以包含必需参数和可选参数，这些参数可以在每次调用时进行调整。
必需参数
使用格式
{variable}如果找不到，将中止请求。
/* 两个必需变量 */ $.fn.api.settings.api = { 'get followers' : '/followers/{id}?results={count}' };
可选参数
使用格式
{/variable}如果找不到，不会中止请求。
如果不可用，将从 URL 中自动删除。
可选参数之前的所有斜杠都将从 URL 中删除，允许您将它们包含在资源路径中。
/* 一个必需变量，一个可选变量 */ $.fn.api.settings.api = { 'get followers' : '/followers/{id}/{/sort}' };
创建您的 API
您应该在您的应用程序中定义一次端点。通常，这在每个页面上包含的中央配置文件中完成。
这些命名的 API 端点全局存储在 $.fn.api.settings.api 中。
将您的端点定义在一个地方，可以确保在您更新应用程序时，您只需要更新一个位置即可获得新的 URL。
/* 全局定义 API 端点一次 */ $.fn.api.settings.api = { 'get followers' : '/followers/{id}?results={count}', 'create user' : '/create', 'add user' : '/add/{id}', 'follow user' : '/follow/{id}', 'search' : '/search/?query={value}' };
使用 URL
命名的 API 操作不需要使用 API，您也可以手动指定请求的 URL 并使用相同的模板。
$('.search.button') .api({ url: 'http://www.google.com?q={value}' }) ;
查询 API 操作
附加 API 事件
API 事件通过将命名的操作附加到页面上的元素来触发。这些操作会在您的 API 中查找命名的端点，并为每次调用翻译来自您元素的模板化值。
任何元素都可以直接附加 API 操作。默认情况下，操作将在最适合元素类型的事件中发生。例如，按钮将在 onclick 事件中调用您的服务器，输入框将在 oninput 事件中调用，表单将在 onsubmit 事件中调用。
可以在初始化时在 Javascript 中指定 API 操作和数据
// 将 '/follow/{id}' 翻译为 'follow/22' $('.follow.button') .api({ action: 'follow user', urlData: { id: 22 } }) ;
或
API 操作和数据也可以在元数据中指定
// 也调用 '/follow/22' $('.follow.button') .api() ;
指定 DOM 事件
如果您需要覆盖 API 事件发生的事件，可以使用 on 参数。
$('.follow.button') .api({ action: 'follow user', on: 'mouseenter' }) ;
立即调用
如果您需要 API 操作立即发生，请使用 on: 'now'。这仍然会触发对调用元素的相同状态更新，但会立即发生。
$('.follow.button') .api({ action: 'follow user', on: 'now' }) ;
请记住，传递新的设置对象将销毁上一个实例及其所有设置和事件。如果您想保留上一个实例，可以使用 query 行为触发新的请求。
// 使用事件设置 API 按钮 $('.follow.button') .api({ action: 'follow user' }) ; // 立即执行查询 $('.follow.button') .api('query') ;
设置请求
将数据路由到 URL
如果您的 API URL 包含模板化变量，它们将在您的请求过程中通过四种可能的方式之一替换，这些方式按继承顺序排列。
默认情况下，URL 中使用的所有参数都使用 encodeURIComponent 进行编码，以防止恶意字符串影响您的查询。要禁用此功能，可以设置 encodeParameters: false。
1. 自动路由的 URL 变量
如果在 URL 操作中指定了一些特殊值，它们将被自动替换。
| 变量 | 描述 | 适用于 |
|---|---|---|
| text | 元素的当前文本值 | 所有元素 |
| value | 元素的当前输入值 | 输入元素 |
$.fn.api.settings.api.search = '/search/?query={value}'; $('.routed.example .search input') .api({ action : 'search', stateContext : '.ui.input' }) ;
2. 在数据属性中指定的 URL 变量
您可以将 URL 值作为 HTML5 元数据属性包含在内。
这通常是为每个触发元素包含唯一 URL 数据的最简单方法。例如，许多关注按钮将触发相同的端点，但每个按钮都有自己的用户 ID。
// 为每个按钮请求不同的 URL $('.follow.button') .api({ action: 'follow user' }) ;
3. 在 JavaScript 中指定的设置
可以在 JavaScript 对象中运行时指定 URL 变量和 GET/POST 数据。
$('.follow.button') .api({ action : 'follow user', method : 'POST', // 替换到 URL 中 urlData: { id: 22 }, // 通过 POST 传递 data: { name: 'Joe Henderson' } }) ;
4. 从 beforeSend 返回的设置
所有运行设置（不仅仅是 URL 数据）都可以在特殊的回调函数 beforeSend 中进行调整，该回调函数在发送 API 请求之前发生。
$('.follow.button') .api({ action: 'follow user', beforeSend: function(settings) { settings.urlData = { id: 22 }; return settings; } beforeXHR: function(xhr) { // 用额外的标题调整 XHR xhr.setRequestHeader ('Authorization', 'Basic XXXXXX'); return xhr; } }) ;
调整请求
修改 XHR
另一个回调函数 beforeXHR 允许您在发送之前修改 XHR 对象。这对于在发送请求之前调整 XHR 请求的属性（如修改标题）很有用。
$('.follow.button') .api({ action: 'follow user', beforeXHR: function(xhr) { // 用额外的标题调整 XHR xhr.setRequestHeader ('Authorization', 'Basic XXXXXX'); return xhr; } }) ;
禁用请求
为了方便起见，API 会自动阻止对当前禁用的元素的请求。
// 这永远不会发生 $('.disabled.button') .api({ action: 'follow user' }) ;
取消请求
beforeSend 还可以用来检查是否需要发出请求的特殊条件。如果 beforeSend 回调函数返回 false，请求将被取消。
// 在你的代码中的某个地方设置 window.isLoggedIn = false; $('.follow.button') .api({ action: 'follow user', beforeSend: function(settings) { // 如果没有登录，取消请求 if(!isLoggedIn) { $(this).state('flash text', '需要登录！'); return false; } } }) ;
传递数据
1. 路由的表单数据
当您使用 serializeForm 设置或在表单上附加 API 事件时，API 会自动将最接近的表单包含在发送到服务器的数据中。
结构化表单数据比jQuery 的序列化 有几个好处
- 序列化对象 正确地将结构化表单名称（如
name="name[first]"）转换为嵌套的对象字面量。 - 可以在 JavaScript 中的
beforeSend中修改结构化表单数据。 - 表单数据将自动转换为相应的 JavaScript 等效项，例如，复选框将转换为
boolean值。
结构化数据示例
以下表单展示了上面提到的结构化表单数据的一些优势。
$('form .submit.button') .api({ action: 'create user', serializeForm: true, data: { foo: 'baz' }, beforeSend: function(settings) { // 表单数据可以在 beforeSend 中编辑 if(settings.data.username == '') { settings.data.username = 'New User'; } // 打开控制台以检查对象 console.log(settings.data); return settings; } }) ;
2. 在 JavaScript 中路由的数据
在初始化 API 请求时，可以指定服务器数据。
$('.form .submit') .api({ data: { session: 22, name: 'Baz' } }) ;
3. 在 beforeSend 中添加的数据
可以使用特殊的回调函数 beforeSend 来指定 POST 或 GET 数据，该回调函数可以用来在发送请求之前检索数据。
$('.form .submit') .api({ action: 'create user', serializeForm: true, // 所有请求中都相同的任意 POST/GET 数据 data: { session: 22 }, // 在回调函数中针对每个元素修改数据 beforeSend: function(settings) { // 如果没有 id，取消请求 if(!$(this).data('id')) { return false; } settings.data.userID = $(this).data('id'); return settings; } }) ;
服务器响应
响应回调
服务器发出的成功响应将触发 onSuccess，无效结果将触发 onFailure。
onError 仅在 XHR 错误时触发，不会在无效的 JSON 响应时触发。
您可以使用 onResponse 回调函数在解析成功测试之前调整 JSON 响应。
$('.follow.button') .api({ onResponse: function(response) { // 对响应进行一些调整 return response; }, successTest: function(response) { // 测试 JSON 响应是否有效 return response.success || false; }, onComplete: function(response) { // XHR 完成后始终调用 }, onSuccess: function(response) { // 有效响应且 response.success = true }, onFailure: function(response) { // 请求失败，或有效响应但 response.success = false }, onError: function(errorMessage) { // 无效响应 }, onAbort: function(errorMessage) { // 导航到新页面，CORS 问题，或用户取消了请求 } }) ;
确定 JSON 成功
API 对 JSON 响应有特殊的成功条件。API 不是根据请求的 HTTP 响应提供成功和失败回调函数，而是仅当服务器响应表明操作成功时，才认为请求成功。响应将传递给验证测试 successTest，该测试可以用来检查 JSON 中是否有有效响应。
例如，您可能希望所有成功的 JSON 响应都返回一个顶级属性，表示响应的成功。
{ "success": true, "message": "我们已从服务器检索到您的数据" "data": { // 此处的有效载荷 } }
您可以指定一个成功测试来检查此 success 值。这很可能是在全局范围内为所有 API 请求设置的。
$.fn.api.settings.successTest = function(response) { if(response && response.success) { return response.success; } return false; };
修改响应 JSON
从 2.0 版本开始，API 包含一个 onResponse 回调函数，它允许您在响应被验证之前调整服务器响应，从而允许您在其他回调函数触发之前转换响应。这对于 API 响应无法修改，但需要响应符合所需的 JSON 结构的情况很有用。
$('.ui.search') .search({ type : 'category', minCharacters : 3, apiSettings : { url : '//api.github.com/search/repositories?q={query}', onResponse : function(githubResponse) { var response = { results : {} } ; if(!githubResponse || !githubResponse.items) { return; } // 将 GitHub API 响应转换为可与搜索一起使用 $.each(githubResponse.items, function(index, item) { var language = item.language || 'Unknown', maxResults = 8 ; if(index >= maxResults) { return false; } // 创建新的语言类别 if(response.results[language] === undefined) { response.results[language] = { name : language, results : [] }; } // 将结果添加到类别中 response.results[language].results.push({ title : item.name, description : item.description, url : item.html_url }); }); return response; } } }) ;
控制状态
UI 状态
API 会自动添加 loading 和 error 的类名。这将使您能够在 API 调用进行时自动触发不同的 UI 状态。
如果需要其他元素而不是触发 API 元素来接收状态类名，可以使用 settings.stateContext 指定不同的选择器。
使用 stateContext 可以轻松地执行诸如在按下提交按钮时触发表单的加载状态之类的操作。
API 模块中包含的状态
| 状态 | 描述 | API 事件 |
|---|---|---|
| loading | 表示用户需要等待 | XHR 已初始化 |
| error | 表示发生了错误 | XHR 请求返回错误（不会在由页面更改引起的 onAbort 或 successTest 失败时触发）。在 settings.errorDuration 内保持可见 |
| disabled | 阻止 API 操作 | none |
文本状态
使用状态模块初始化 API 操作可以更细粒度地控制 UI 状态，例如设置激活或停用的状态，以及调整每个状态的文本值的能力
$('.follow.button') .api({ action: 'follow user' }) .state({ onActivate: function() { $(this).state('flash text'); }, text: { inactive : '关注', active : '已关注', deactivate : '取消关注', flash : '添加了关注者！' } }) ;
状态模块中包含的状态
| 状态 | 描述 | 发生在 |
|---|---|---|
| inactive | 默认状态 | |
| active | 选中状态 | 在 API 请求成功时切换 |
| activate | 解释激活操作 | 如果处于非活动状态，则在悬停时 |
| deactivate | 解释停用操作 | 如果处于活动状态，则在悬停时 |
| hover | 解释交互 | 在所有状态下悬停时，覆盖 activate/deactivate |
| disabled | 表示元素无法交互 | 以编程方式触发。阻止 API 请求。 |
| flash | 用于显示临时消息的纯文本状态 | 以编程方式触发 |
| success | 表示用户操作成功 | 以编程方式触发 |
| warning | 表示用户操作出现问题 | 以编程方式触发 |
高级用法
满足响应
从 2.0 版本开始，API 包含两个新的参数 response 和 responseAsync，允许您指定 JavaScript 对象或函数来返回 API 响应。（以前为 mockResponse 和 mockResponseAsync。）
$('.sync.mocked .button') .api({ response: { success: true } }) .state({ text: { inactive : '关闭', active : '打开' } }) ;
使用自定义后端
使用 responseAsync，您可以指定一个函数来执行 API 请求。这使您能够使用 $.ajax 之外的自定义后端或包装器来集成 API 请求。
$('.async.mocked .button') .api({ responseAsync: function(settings, callback) { var response = { success: true }; // 在此处执行任何异步任务 setTimeout(function() { callback(response); }, 500); } }) .state({ text: { inactive : '关闭', active : '打开' } }) ;
行为
可以使用以下语法调用所有以下行为
$('.your.element') .api('behavior name', argumentOne, argumentTwo) ;
| 行为 | 描述 |
|---|---|
| query | 使用现有的 API 设置执行查询 |
| add url data(url, data) | 将数据添加到现有的模板 URL，并返回完整的 URL 字符串 |
| get request | 获取当前 API 请求的承诺 |
| abort | 中止当前 API 请求 |
| reset | 从元素中删除加载和错误状态 |
| was cancelled | 返回上次请求是否被取消 |
| was failure | 返回上次请求是否失败 |
| was successful | 返回上次请求是否成功 |
| was complete | 返回上次请求是否已完成 |
| is disabled | 返回元素是否已禁用 |
| is mocked | 返回元素响应是否已模拟 |
| is loading | 返回元素是否正在加载 |
| set loading | 将加载状态设置为元素 |
| set error | 将错误状态设置为元素 |
| remove loading | 从元素中删除加载状态 |
| remove error | 从元素中删除错误状态 |
| get event | 获取 API 请求将发生的事件 |
| get url encoded value(value) | 仅当传递的值未被编码时才返回encodeURIComponent的值 |
| 读取缓存的响应(url) | 读取 URL 的本地缓存响应 |
| 写入缓存的响应(url, response) | 写入 URL 的缓存响应 |
| 创建缓存 | 创建新的缓存，删除所有本地缓存的 URL |
| 销毁 | 从页面和所有事件中删除 API 设置 |
API
AJAX
API
| 默认 | 描述 | |
|---|---|---|
| 开启 | 自动 | API 事件何时发生 |
| 缓存 | 是 | 可以设置为 'local' 以在使用 JSON API 时缓存成功返回的 AJAX 响应。这有助于避免在 API 端点在重复访问时返回相同结果时的服务器往返。设置为false将向 URL 添加缓存破坏参数。 |
| 状态上下文 | 这个 | UI 状态将应用于此元素，默认为触发元素。 |
| 编码参数 | 是 | 是否在将参数添加到 URL 字符串之前使用encodeURIComponent对其进行编码 |
| 默认数据 | 是 | 是否自动包含默认数据，如 {value} 和 {text} |
| 序列化表单 | 否 | 是否序列化最近的表单并将其包含在请求中 |
| 节流 | 0 | 发出请求后等待多长时间才能触发请求，这对于对oninput进行速率限制很有用 |
| 节流第一个请求 | 是 | 设置为 false 时，不会延迟发出的第一个请求，当没有其他请求排队时 |
| 中断请求 | 否 | 是否可以在另一个请求仍在挂起时发生 API 请求 |
| 加载持续时间 | 0 | 显示加载指示的最小持续时间 |
| 隐藏错误 | 自动 | 默认的auto会在错误持续时间后自动删除错误状态，除非元素是form |
| 错误持续时间 | 2000 | 设置为true，将不会删除错误。设置为以毫秒为单位的持续时间以在请求错误后显示错误状态。 |
请求设置
| 默认 | 描述 | 可能的值 | |
|---|---|---|---|
| 操作 | 否 | 用于查询的命名 API 操作，最初在 $.fn.settings.api 中指定 | 字符串或 false |
| URL | 否 | 用于查询的模板化 URL，将覆盖指定的 action | 字符串或 false |
| URL 数据 | 否 | 用于替换的变量 | |
| 响应 | 否 | 可以设置为 JavaScript 对象，该对象将自动返回，而不是从服务器请求 JSON | {} 或 false |
| responseAsync(settings, callback) | 否 | 当指定时，此函数可用于从服务器检索内容并异步返回它，而不是标准 AJAX 调用。回调函数应返回服务器响应。 | 函数或 false |
| 模拟响应 | 否 | response的别名 |
|
| 模拟响应异步 | 否 | responseAsync的别名 |
|
| 方法 | 获取 | 将请求传输到服务器的方法 | 任何有效的 http 方法 |
| 数据类型 | JSON | 预期响应的数据类型 | xml、json、jsonp、script、html、text |
| 数据 | {} | 要与请求一起发送的 POST/GET 数据 |
回调
| 上下文 | 描述 | |
|---|---|---|
| beforeSend(settings) | 初始化的元素 | 允许在请求之前修改设置或取消请求 |
| beforeXHR(xhrObject) | 允许修改请求的 XHR 对象 | |
| onRequest(promise, xhr) | 状态上下文 | 发出请求时发生的回调。接收 API 成功承诺和 XHR 请求承诺。 |
| onResponse(response) | 状态上下文 | 允许在其他回调解析服务器响应之前修改它，以确定 API 事件是否成功 |
| successTest(response) | 确定完成的 JSON 响应是否应该被 视为成功 | |
| onSuccess(response, element, xhr) | 状态上下文 | 成功响应后的回调，JSON 响应必须通过successTest |
| onComplete(response, element, xhr) | 状态上下文 | 无论条件如何，请求完成后的回调 |
| onFailure(response, element) | 状态上下文 | 失败响应的回调，或失败successTest的 JSON 响应 |
| onError(errorMessage, element, xhr) | 状态上下文 | 从返回的状态码或 XHR 失败中发生的服务器错误的回调。 |
| onAbort(errorMessage, element, xhr) | 状态上下文 | 用户点击链接或手动取消请求导致的中止的回调。 |
模块
这些设置是所有模块的原生设置，并定义了组件如何将内容绑定到 DOM 属性以及模块的调试设置。
| 默认 | 描述 | |
|---|---|---|
| 名称 | API | 日志语句中使用的名称 |
| 命名空间 | api | 事件命名空间。确保模块拆卸不会影响附加到元素的其他事件。 |
| 正则表达式 |
regExp : { required: /\{\$*[A-z0-9]+\}/g, optional: /\{\/\$*[A-z0-9]+\}/g, }
|
用于模板匹配的正则表达式 |
| 选择器 |
selector: { disabled : '.disabled', form : 'form' }
|
用于查找模块一部分的选择器 |
| 类名 |
className: { loading : 'loading', error : 'error' }
|
用于确定元素状态的类名 |
| 元数据 |
metadata: { action : 'action', url : 'url' }
|
用于存储 XHR 和响应承诺的元数据 |
| 静默 | 否 | 静默所有控制台输出，包括错误消息，无论其他调试设置如何。 |
| 调试 | 否 | 向控制台输出调试信息 |
| 性能 | 是 | 显示带有性能指标的console.table输出 |
| 详细 | 否 | 调试输出包括所有内部行为 |
| 错误 |
// errors error : { beforeSend : '发送前函数已中止请求', error : '您的请求出现错误', exitConditions : 'API 请求中止。满足退出条件', JSONParse : '在错误处理期间无法解析 JSON', legacyParameters : '您正在使用旧版 API 成功回调名称', missingAction : '使用了 API 操作，但未定义 URL', missingSerialize : '缺少必需的依赖项 jquery-serialize-object，使用基本序列化', missingURL : '未为 API 事件指定 URL', noReturnedValue : '发送前回调必须返回 settings 对象，发送前被忽略。', parseError : '解析您的请求时出现错误', requiredParameter : '缺少必需的 URL 参数：', statusMessage : '服务器出现错误：', timeout : '您的请求超时' }
|
|