X-editable 文档 中文版
前言
因为要用到 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 英文文档 。
入门指导
-
决定使用哪一个前端框架:
- 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>
-
下载相应的 X-editable 库并且引入至页面中。
<link href="bootstrap-editable/css/bootstrap-editable.css" rel="stylesheet"> <script src="bootstrap-editable/js/bootstrap-editable.js"></script>
注意引入位置在前端框架之后
-
标记元素应该是可编辑的。 通常它是带有
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
orname
- 要更新的字段的名称。 取自id
或data-name
属性value
- 初始值。 对于select有用,其中value是要显示的文本的整数值。 如果为空 - 将取自元素html内容
-
设置可编辑模式:行内或弹出(默认)
//turn to inline mode $.fn.editable.defaults.mode = 'inline';
-
将 editable() 方法应用于这些元素
$(document).ready(function() { $('#username').editable(); });
或者,您可以通过 javascript 来设置
<a href="#" id="username">superuser</a>
$('#username').editable({ type: 'text', pk: 1, url: '/post', title: 'Enter username' });
-
前端准备好了!
View starter template(查看模板) Download starter zip(下载模板zip)
打开页面并单击元素。 输入新值并提交表单。 它将向
/post
发送带有新值的ajax请求。
请求包含要更新的记录的name
,value
andpk
:POST /post { name: 'username', //name of field (column in db) pk: 1 //primary key (record id) value: 'superuser!' //new value }
-
写在尾巴:
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语法不是很熟悉,所以表格内的代码块存在排版错误,建议将表格内代码复制下来重新进行排版。
名称 | 类型 | 预设值 | 说明 |
---|---|---|---|
ajaxOptionssince1.1.1 |
null | null | 提交ajax请求的其他选项。 可参阅: http://api.jquery.com/jQuery.ajaxajaxOptions: { type: 'put', dataType: 'json'} |
anim | string | false | 动画速度(仅限行内模式) |
autotext | string | ‘auto’ | 允许根据元素的值自动设置元素的文本。 可以是auto \| always \| never 。 适用于选择和日期。 例如,如果下拉列表为{1:'a',2:'b'} 且元素值设置为1 ,则其html将自动设置为“a”。auto - 仅当元素为空时,才会自动设置自动文本。always\|never - 尝试 | 绝不设置元素的文本。 |
defaultValuesince 1.4.6 |
string|object | null | 若原始字段值为空(null \| undefined \|'') ,将在输入中显示的值。 |
disabled | boolean | false | 设置可编辑的禁用状态 |
displaysince 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(); }} |
emptyclasssince1.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 (顶部|右侧|底部|左侧)。 无法应用在行内式编辑模式。 |
savenochangesince1.2.0 |
boolean | false | 是否在未提交但保存表单时保存或取消。 |
selectorsince1.4.1 |
string | null | 如果提供了选择器,则可编辑将委派给指定的目标。 对动态生成的DOM元素有效。 请注意,无法使用 emptytext 和autotext 选项初始化委派的目标,因为它们实际上只有在首次单击后才可编辑。您应该手动将 editable-click class设置在该元素上。此外,如果元素最初为空,则应添加class editable-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’数据,否则新值将存储在本地。 |
showbuttonssince 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 等 |
unsavedclasssince 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'); } }); |
initsince 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”}