时间戳

首页 > 技术文章 > X-editable 文档 中文版

X-editable 文档 中文版

Sherlock-J 2018-08-26 16:08 原文

前言

因为要用到 Bootstrap-table ，不可避免的会用到表格编辑功能，而 X-editable 可在页面上创建可编辑元素。 它可以与前端框架（Bootstrap，jQuery UI，jQuery ）配合使用，编辑模式包括弹出和行内模式。只是兜兜转转找了下只有英文文档，还是不方便查阅，所以进行了部分翻译。翻译范围为：Getting started与$().editable(options) 两部分，但这两部分足够完成80%的需要了，一部分是demo，另一部分是options。各输入组件（例如text、date、textarea等）一些不同的细微设置请查阅源文档。此翻译的文档版本为 X-editable 1.5.1（2018年8月）。翻译到中途的时候，发现个人能力有限，完整文档的翻译所费时间远远超出预期，向各位致以歉意。如有错误，烦请指教。

附上链接X-editable 英文文档 。

入门指导

  1. 决定使用哪一个前端框架：

    • Bootstrap
    • jQuery UI
    • only jQuery (+ Poshytip)

    ​

    引入至页面中。以下是 bootstrap 的例子:

    <link href="//netdna.bootstrapcdn.com/bootstrap/3.0.0/css/bootstrap.min.css" rel="stylesheet">
<script src="http://code.jquery.com/jquery-2.0.3.min.js"></script>
<script src="//netdna.bootstrapcdn.com/bootstrap/3.0.0/js/bootstrap.min.js"></script>

  2. 下载相应的 X-editable 库并且引入至页面中。

    <link href="bootstrap-editable/css/bootstrap-editable.css" rel="stylesheet">
<script src="bootstrap-editable/js/bootstrap-editable.js"></script>

    注意引入位置在前端框架之后

  3. 标记元素应该是可编辑的。 通常它是带有data-*属性的<A>元素。

    <a href="#" id="username" data-type="text" data-pk="1" data-url="/post" data-title="Enter username">superuser</a>

    您应该定义的主要属性是：

    • type - 文本输入类型(text, textarea, select 等等)
    • url - 与服务器连接的URL，来交互一些需要处理的值 (/post, post.php 等等)
    • pk - 要更新的记录的主键
    • id or name - 要更新的字段的名称。 取自id或data-name属性
    • value - 初始值。 对于select有用，其中value是要显示的文本的整数值。 如果为空 - 将取自元素html内容

    ​

  4. 设置可编辑模式：行内或弹出（默认）

    //turn to inline mode
$.fn.editable.defaults.mode = 'inline';

  5. 将 editable() 方法应用于这些元素

    $(document).ready(function() {
    $('#username').editable();
});

    或者，您可以通过 javascript 来设置

    <a href="#" id="username">superuser</a>

    $('#username').editable({
    type: 'text',
    pk: 1,
    url: '/post',
    title: 'Enter username'
});

  6. 前端准备好了！

    View starter template（查看模板） Download starter zip（下载模板zip）

    打开页面并单击元素。 输入新值并提交表单。 它将向/post发送带有新值的ajax请求。
    请求包含要更新的记录的name, value and pk：

    POST /post
{
    name:  'username',  //name of field (column in db)
    pk:    1            //primary key (record id)
    value: 'superuser!' //new value
}

    ​

  7. 写在尾巴：

    X-editable对服务器端语言没有限制：您可以使用您喜欢的任何语言编写它。

    例如，您要在服务器上验证提交的值：

    • 如果值有效，则应返回 HTTP 状态 200 OK 。 页面上的元素将自动更新。 无需回复 response body。
    • 如果值无效，则应返回 HTTP 状态 != 200 （例如 400 请求无效），并在响应正文中显示错误消息。 页面上的元素不会更新，可编辑的表单将显示错误消息。

    默认请求方法是POST，您可以通过默认配置更改它：

    $.fn.editable.defaults.ajaxOptions = {type: "PUT"};

    JSON response:

    如果您的服务器返回JSON，您始终可以在响应正文中发送带有错误标志的HTTP状态200。
    在success 进行逻辑控制：

    //assume server response: 200 Ok {status: 'error', msg: 'field cannot be empty!'}
$('#username').editable({
   ...
   success: function(response, newValue) {
       if(response.status == 'error') return response.msg; //msg will be shown in editable form
   }
});

    本地化交互:

    如果您不想在服务器上发送值，只需保留空url选项。 您可以在success 进行逻辑控制：

    $('#username').editable({
    type: 'text',
    title: 'Enter username',
    success: function(response, newValue) {
        userModel.set('username', newValue); //update backbone model
    }
});

$().editable(options)

使页面上的任何HTML元素都可编辑。 通过jQuery方法。

选项（Options）

可以通过javascript $().editable({...})或通过data-* html属性定义选项。
请同时参阅input dependent options（文本输入控件）部分。
此外，您可以从其文档中选择一些弹出窗口的核心选项：bootstrap-popover，jquery-ui-tooltip。

注意，因为译者markdown语法不是很熟悉，所以表格内的代码块存在排版错误，建议将表格内代码复制下来重新进行排版。

名称 类型 预设值 说明
ajaxOptions
since1.1.1		 null null 提交ajax请求的其他选项。 可参阅: http://api.jquery.com/jQuery.ajax
ajaxOptions: { type: 'put', dataType: 'json'}
anim string false 动画速度（仅限行内模式）
autotext string ‘auto’ 允许根据元素的值自动设置元素的文本。 可以是auto \| always \| never。 适用于选择和日期。 例如，如果下拉列表为{1：'a'，2：'b'}且元素值设置为1，则其html将自动设置为“a”。
auto - 仅当元素为空时，才会自动设置自动文本。
always\|never - 尝试 | 绝不设置元素的文本。
defaultValue
since 1.4.6		 string|object null 若原始字段值为空（null \| undefined \|''），将在输入中显示的值。
disabled boolean false 设置可编辑的禁用状态
display
since 1.2.0		 function|boolean null 在元素的text中进行value的自定义显示。
如果为null，则使用默认输入的显示。
如果为false，则不会调用显示方法，元素的文本将不会更改。
参数：
1. value: 要显示的当前值
2. response：从版本1.4.0起，服务器响应（显示如果在进行ajax后调用）
对于带有源（select，checklist）参数的输入是不同的：
参数：
1. value: 要显示的当前值。
2. sourceData ：当前输入的项目数组（例如下拉项）
3. response：从版本1.4.0起，服务器响应（显示如果在进行ajax后调用）
要使用当前选定的项目$.fn.editableutils.itemsByValue(value, sourceData).
display: function(value, sourceData) { //display checklist as comma-separated values var html = [], checked = $.fn.editableutils.itemsByValue(value, sourceData); if(checked.length) { $.each(checked, function(i, v) { html.push($.fn.editableutils.escape(v.text)); }); $(this).html(html.join(', ')); } else { $(this).empty(); }}
emptyclass
since1.4.1		 string editable-empty 当可编辑文本为空时应用的CSS类。
emptytext string ‘Empty’ 元素为空时显示的文本。
errorsince
since1.4.4		 function null 错误回调。 请求失败时调用（ response status！= 200）。当您想要解析错误响应并显示自定义消息时有用。 返回类型必须为string (要在错误块中显示的消息)。
error: function(response, newValue) { if(response.status === 500) { return 'Service unavailable. Please try later.'; } else { return response.responseText; }}
highlight
since1.4.5		 string|boolean #FFFF80 用于在更新后显示高亮元素的颜色。 通过CSS3过渡实现，适用于现代浏览器。
mode
since1.4.0		 string ‘popup’ 编辑模式，可以是 popup 弹出式或inline行内式
name string null 字段名称。 将在服务器上提交。 可以从id属性中获取
onblur
since1.1.1		 string ‘cancel’ 用户在容器外部单击时的操作。 可以 cancel\|submit\|ignore(取消|提交|忽略)。设置忽略允许同时打开几个容器。
params object|function null 提交的其他参数。 如果定义为object- 它将附加到原始ajax数据（pk，name和value）。
如果定义为 function - 返回的对象将覆盖原始的ajax数据。
params: function(params) { //originally params contain pk, name and value params.a = 1; return params;}
pk string|object|function null 可编辑对象的主键（例如，数据库中的记录ID）。 对于复合键，使用对象，例如 {id：1，lang：‘en’}。 可以通过函数动态计算。
placement string ‘top’ 容器相对于元素的放置。
可以是top\|right\|bottom\|left （顶部|右侧|底部|左侧）。
无法应用在行内式编辑模式。
savenochange
since1.2.0		 boolean false 是否在未提交但保存表单时保存或取消。
selector
since1.4.1		 string null 如果提供了选择器，则可编辑将委派给指定的目标。
对动态生成的DOM元素有效。
请注意，无法使用emptytext和autotext选项初始化委派的目标，因为它们实际上只有在首次单击后才可编辑。
您应该手动将editable-clickclass设置在该元素上。
此外，如果元素最初为空，则应添加classeditable-empty，set data-value =""并将emptytext写入元素：
<div id="user"> <!-- empty --> <a href="#" data-name="username" data-type="text" class="editable-click editable-empty" data-value="" title="Username">Empty</a> <!-- non-empty --> <a href="#" data-name="group" data-type="select" data-source="/groups" data-value="1" class="editable-click" title="Group">Operator</a></div> <script>$('#user').editable({ selector: 'a', url: '/post', pk: 1});</script>
send string ‘auto’ 在服务器上发送数据的策略。 可以是auto \| always \| never （自动|一直|永不）。 仅当定义了pk和url时，才会在服务器上发送’auto’数据，否则新值将存储在本地。
showbuttons
since 1.1.1		 boolean|string true 显示按钮的位置：left（true）\| bottom \| false（左侧|底部|隐藏）。
没有按钮将自动提交。
success function null 成功回调。 在服务器上成功发送值并且响应状态= 200时调用。用于处理json响应。 例如，如果您的后端响应可以是{success：true}或{success：false，msg：“server error”}，则可以在此回调中检查它。
如果它返回string - 意味着发生错误，字符串显示为错误消息。
如果它返回像{newValue：<something>}这样的对象 - 它会覆盖用户提交的值。除此以外，newValue只是渲染到元素中。
success: function(response, newValue) { if(!response.success) return response.msg;}
toggle string ‘click’ 如何切换至编辑模式。 click\| dblclick \| mouseenter \| manual(点击|双击|指针穿过|手动)。
设置为手动时，您应手动调用可编辑的显示/隐藏方法。
注意：如果在某些DOM元素的单击处理程序中调用show或toggle，则需要应用e.stopPropagation()，因为在文档上的任何单击时都会关闭容器。$('#edit-button').click(function(e) { e.stopPropagation(); $('#username').editable('toggle');});
type string ‘text’ 输入类型。可以是 text\|textarea\|select\|date\|checklist 等
unsavedclass
since 1.4.1		 string editable-unsaved 存储值但未发送到服务器时应用的CSS（pk为空或send=‘never’）。
如果您在本地使用可编辑项并将它们一起提交，则可以将其设置为null。
url string|function null 要提交的网址，例如’/post’。
如果是函数 - 它将被调用，而不使用ajax。 函数应返回对象以运行失败/完成回调。
url: function(params) { var d = new $.Deferred(); if(params.value === 'abc') { return d.reject('error message'); //returning error via deferred object } else { //async saving data in js model someModel.asyncSaveMethod({ ..., success: function(){ d.resolve(); } }); return d.promise(); }}
validate function null 客户端验证的功能。 如果返回字符串 - 表示验证未通过，且会将返回值显示。 从1.5.1开始，您可以通过从validate返回对象来修改提交的值：
{newValue: '...'} or {newValue: '...', msg: '...'}
validate: function(value) { if($.trim(value) == '') { return 'This field is required'; }}
value mixed element’s text 输入的初始值。 如果未设置，则取自元素的文本。
请注意，如果元素的文本为空 - 文本将从值自动生成，可以自定义（请参阅autotext选项）。
例如，要显示货币符号：
<a id="price" data-type="text" data-value="100"></a><script>$('#price').editable({ ... display: function(value) { $(this).text(value + '$'); } }) </script>

方法（Methods）

所有的方法都可以通过以下形式调用： $().editable('method', params);

方法 参数 描述
$().editable(options) options 对象 通过jQuery方法初始化可编辑元素。
$('#username').editable({ type: 'text', url: '/post', pk: 1});
activate() none 激活可见容器的输入（例如设置焦点）
destroy() none 从元素中删除可编辑的功能
disable() none 禁用可编辑
enable() none 启用可编辑
getValue() isSingle Bool 是否只返回单个元素的值 返回可编辑元素的当前值。
请注意，它返回一个具有名称 - 值对的对象，而不是一个值本身。 它允许从多个元素中获取数据。
如果某些可编辑的值为null或 undefined ，则将其从结果对象中排除。 当参数isSingle设置为true时 - 假设您有单个元素，将返回editable而不是object的值。
$('#username, #fullname').editable('getValue');//result:{username: "superuser",fullname: "John"}//isSingle = true$('#username').editable('getValue', true);//result "superuser"
hide() none 隐藏容器
option(key, value) key String|object 选项名称或具有多个选项的对象
value 多种类型 要加入的新值		 设置新选项：
$('.editable').editable('option', 'pk', 2);
setValue(value, convertStr) value 多种类型 要加入的新值
convertStr Boolean 是否将值从字符串转换为内部格式		 设置编辑组件的新值
show() closeAll Boolean 是否在显示此文件时关闭所有其他可编辑容器。 默认为true。 显示容器
submit(options) options Object：
1. url Object 提交数据的url
2. data Object 提交的数据
3. ajaxOptions Object 额外的ajax选项
4. error(obj) Function 错误处理
5. success(obj,config) Function 成功处理		 此方法从多个可编辑元素中收集值，并将它们全部提交给服务器。
原则上，它只为成功运行所有字段和提交的客户端验证。
请参阅 creating new records以获取详细信息。
从1.5.1起， submit可以应用于单个元素以编程方式发送数据。 在这种情况下，url， success和 error 默认初始化，你可以以此方式调用调用： $('#username').editable('submit')。
toggle() closeAll Boolean 是否在显示此容器时关闭所有其他可编辑容器。 默认为true。 切换容器可见性（ show / hide）
toggleDisabled() none 切换可编辑元素的启用/禁用状态
validate() none 对匹配的可编辑元素进行客户端验证
$('#username, #fullname').editable('validate'); // possible result: { username: "username is required", fullname: "fullname should be minimum 3 letters length" }

事件（Events）

事件 回调参数 描述
hidden event Object 事件对象
reason String 隐藏原因。 可以是save\|cancel\|onblur\|nochange\|manual		 当容器被隐藏时被触发。 它既可以保存也可以取消。
注意：Bootstrap popover有自己的 hidden 事件，现在无法与x-editable的事件区别。 解决方法是检查arguments.length，对于x-editable，其值始终为2。
$('#username').on('hidden', function(e, reason) { if(reason === 'save' \|\| reason === 'cancel') { //auto-open next editable $(this).closest('tr').next().find('.editable').editable('show'); } });
init
since 1.2.0		 event Object 事件对象
editable Object 可编辑的实例（因为它不能通过数据访问（’ editable’））		 元素由$().editable()方法初始化时触发。 请注意，您应该在应用editable之前设置init处理程序。
$('#username').on('init', function(e, editable) { alert('initialized ' + editable.options.name);});$('#username').editable();
save event Object 事件对象
params Object 额外的参数：
1. newValue Mixed 提交的值
2. response Object ajax 响应		 提交新值时触发。 您可以使用$(this).data('editable')来访问可编辑的实例。
$('#username').on('save', function(e, params) { alert('Saved value: ' + params.newValue);});
shown event Object 事件对象 在显示容器并呈现表单时触发（对于select将等待加载下拉选项）。
注意：Bootstrap popover有自己的 shown 事件，现在无法与x-editable的事件分开。 解决方法是检查arguments.length，对于x-editable，值始终为2。
$('#username').on('shown', function(e, editable) { editable.input.$input.val('overwriting value of input..');});

注意

注意：您可以修改$ .fn.editable.defaults为页面上的所有可编辑元素设置默认选项。
例如，强制所有元素通过PUT方法提交：$ .fn.editable.defaults.ajaxOptions = {type：“put”}

推荐阅读