API-字段选项

Field options（字段选项）

columnResizable
create
edit
defaultValue
dependsOn
display
input
inputClass
inputTitle
key
list
listClass
options
optionsSorting
sorting
title
type
visibility
width

字段定义定义了一条记录中字段的结构和行为。像下面这样格式：

FieldName: {
    //Field options
}

columnResizable boolean default: true

一个bool值，代表列是否可以被用户改变大小。

create boolean default: true

bool值，代表是否在添加的表单中显示。

key字段默认是false，其余的默认是true。

edit boolean default: true

bool值，代表是否在编辑的表单中显示。

key字段默认是false，其余的默认是true。

defaultValue string default: none

你可以为这个字段设置一个默认值。但必须是一个有效的值。例如，这个字段是一个选项列表，那么这个值必须是这个列表中的其中一个。

dependsOn string or array default: none

这个选项用于创建级联下拉列表。如果一个下拉列表字段依赖于另外一个，jTable可以自动创建级联下拉列表。查看demo了解使用方法。
下面是一个简单的国家/城市级联下拉列表案例：

CountryId: {
    title: 'Country',
    options: 'Demo/GetCountryOptions',
    list: false
},
CityId: {
    title: 'City',
    dependsOn: 'CountryId', //Cities depends on countries.
    options: function (data) {
        if (data.source == 'list') {
            //Return url of all cities for optimization. 
            return 'Demo/GetCityOptions?countryId=0';
        }
        //This code runs when user opens edit/create form or changes country combobox on an edit/create form.
        return 'Demo/GetCityOptions?countryId=' + data.dependedValues.CountryId;
    }
}

一个字段可以依赖于多个字段。在上面的案例中，你可以用逗号把依赖的字段分开：'ContinentalId,CountryId'，或者用一个数组也可以：dependsOn: ['ContinentalId', 'CountryId']

更多信息查看options。

display function default: none

这个选项是一个function，允许你完全自定义表格中的一列。jTable直接展示function返回的结果到表格上。看下面的案例：

TestColumn: {
    title: 'Test',
    display: function (data) {
        return '<b>test</b>';
    }
}

‘TestColumn’列返回了一个加粗的‘test’文案，会应用到所有行。你可以返回任何text、html或者jQuery object，返回结果会直接展示到table上。每一行都会调用这个方法。在这个函数中，你可以使用data.record获取当前行的数据。例如：用data.record.name来获取数据里面的name属性值。

这个函数可以有很多用处，比如动态创建列、打开子表（点击行的时候）。

input function default: none

这个选项是一个function，允许你定义一个完全自定义的输入元素，在添加/编辑表单中使用。jTable直接将返回结果展示到表单中。看下面的案例：

Name: {
    title: 'Name',
    width: '20%',
    input: function (data) {
        if (data.record) {
            return '<input type="text" name="Name" style="width:200px" value="' + data.record.Name + '" />';
        } else {
            return '<input type="text" name="Name" style="width:200px" value="enter your name here" />';
        }
    }
}

data 参数包含一些属性用于创建输入框的时候。

data.formType：可以是‘create’或者‘edit’（对于表单）。
data.form：是这个表单的一个jQuery选择器。
data.record：如果当前是编辑表单（formType=‘edit’），获取当前行的数据。所以当处于创建表单情况下，此值是undefined。
data.value：获取字段的当前值。如果是创建表单，那么是默认值，如果是编辑表单，等于当前值。

jTable会自动为每个字段创建适当的输入元素，你可以使用这个选项来创建自定义的输入元素。记得设置输入元素的name属性，如果你想用post的方式发送请求到服务器。

inputClass string default: none

一个字符串用来设置这个字段在创建/编辑表单中输入框的样式。因此，你可以在表单中为此字段输入元素设置样式。这在使用验证插件时很有用（我们将很快看到）。

inputTitle string default: none

这个选项为表单中的字段显示不同的标题。如果没有设置，标题会和title中设置的一样。

key boolean default: false

是一个bool值，代表此字段在当前记录中是否是主键。每一行记录中必须有一个且只能有一个主键，在编辑和删除的时候用。

如果一个字段被标记为key，添加和编辑操作会默认设置为false。

如果一个主键字段在编辑表单中不能被编辑，那么会为它自动生成一个hidden元素。这样主键也能发送到服务器。如果主键字段可以被编辑（设置edit为true），则主键的原始值（更新前的值）会作为jtRecordKey发送到服务器。

list boolean default: true

bool值，代表此字段是否在表格中显示。

listClass string default: none

设置此字段在单元格（td）中的样式。这样，可以为表格中的每一个字段设置样式。

options object, array, URL or a function default: none

如果这个字段的值是要在一个选项列表中选择（默认是下拉列表，也可以是radio button列表），你必须提供一个数据源。一个选项数据源可以是一下几种格式：

object：属性名称是value，属性值是显示文本。这个有点怪
array：一个数组。
URL：请求数据作为数据源。
function：一个函数，它接收一些参数并且返回一个object、array或者URL字符串。

定义一个object

创建一个object是定义选项最简单的方法，像下面一样：

PhoneType: {
    title: 'Phone type',
    options: { '1': 'Home phone', '2': 'Office phone', '3': 'Cell phone' }
}

这样，jTable会在添加/编辑表单中为此字段创建一个下拉列表：

‘1’，‘2’，‘3’分别是下拉列表中的值。

定义一个数组

你也可以设置一个数组，像这样：

PhoneType: {
    title: 'Phone type',
    options: [{ Value: '1', DisplayText: 'Home phone' }, { Value: '2', DisplayText: 'Office phone' }, { Value: '2', DisplayText: 'Cell phone' }]
}

当然，如果值和显示的文本是一样的，也可以这样写：

ClassYear: {
    title: 'Phone type',
    options: ['1','2','3','4']
}

定义一个URL

你也可以定义一个URL来下载数据：

PhoneType: {
    title: 'Class year',
    options: '/Demo/GetPhoneTypes.php'
}

服务器正确返回的格式应该是这样的：

{
   "Result":"OK",
   "Options":[
      {
         "DisplayText":"Home phone",
         "Value":"1"
      },
      {
         "DisplayText":"Office phone",
         "Value":"2"
      },
      {
         "DisplayText":"Cell phone",
         "Value":"3"
      }
   ]
}

Result可以是“OK”或者“ERROR”，但如果是“ERROR”，必须返回一个“Message”属性。

定义一个函数

你可以定义函数来动态返回object、array或者URL。这样对于特殊的记录你可以使用不同的选项。

PhoneType: {
    title: 'Phone type',
    options: function(data) {
        if (data.source == 'list') {
            //Return url all options for optimization. 
            return '/Demo/GetPhoneTypes.php?UserType=0';
        }
        //This code runs when user opens edit/create form to create combobox.
        //data.source == 'edit' || data.source == 'create'
        return '/Demo/GetPhoneTypes.php?UserType=' + data.record.UserType;
    }
}

像上面一样，如果返回一个URL，jTable会下载数据作为选项。

为了优化，jTable将基于URL缓存所有选项列表，如果返回相同的URL则从本地缓存获取数据。你可以在函数中调用 data.clearCache() 方法来清除缓存。

IMPORTANT: jTable also uses this function to show the related field in the table for each shown record. This is because your record contains Value of the field, not DisplayText and jTable needs to show display text (instead of value) in the table. So, when data.source'list', returning different URLs causes more than one download to list records in the table. This may be a major performance problem. So, as shown the sample above, return URL of all options while listing (data.source'list') and return filtered options in edit/create forms (if you need).

你可能想要用ajax请求来从服务器获取数据。这种情况下，你应该从服务器同步获取数据，因为你应该从函数返回选项。参考demo和jQuery async 选项。

这个函数有一个data参数，它包含一些可用的字段和方法：

data.source：这个字段用于知道为什么调用这个方法。可选项：‘list’，‘create’，‘edit’。
data.clearCache()：此方法用于清除当前返回的URL的缓存。所以你可以确保的是你的选项将会被重新下载。
data.form：此字段用于获取添加/编辑表单的引用（jQuery选择器）。当data.source是‘create’或者‘edit’的时候是有效的。
data.record：此字段用于通过调用这个函数获取响应的记录。因此，你可以根据记录的字段返回选项。如果data.source是‘list’或者‘edit’则是有效的。
data.dependedValues：如果你对这个字段设置了‘dependsOn’选项，你可以使用data.dependedValues来获取当前依赖字段的值。参考dependsOn。

dependsOn选项和data.dependedValues作为一对，提供了创建级联下拉列表。点击查看完整案例。

optionsSorting string default: none

默认，jTable不会对option进行排序。此选项可用于自动排序options。这个选项的有效值：

value：根据value对options进行排序（ascending）。
value-desc：根据value对options进行排序（descending）。
text：根据display text对options进行排序（ascending）。
text-desc：根据display text对options进行排序（descending）。

sorting boolean default: true

代表是否可以根据此列对表格进行排序（如果表格开启了排序）。

title string default: none

此列在表格中显示的标题，在表单中是作为此字段的label。如果该字段显示在表单中那么这个选项是必须的。

type string default: text

设置此字段的数据类型。如果此字段是text或者number，不需要在设置。其它一些类型：

password：在表单中展示一个type=password的文本框。
textarea：在表单中展示一个type=textarea的文本框。
data：时间字段（不包含time部分：2017-04-09）。在表单中会自动创建一个jQueryUI日期选择器。如果此字段是date（datetime）类型，可以自定义一些附加选项：
- displayFormat：对时间进行格式化。查看 jQueryUI datepicker formats
radiobutton：如果此字段是下拉列表中选择的值，它可以是combobox（默认）或者是radio button list。如果是单选按钮列表，设置类型为radiobutton。你必须提供options列表数据。
checkbox：在编辑这个字段的时候展示一个复选框。如果一个字段是checkbox,可以自定义一些附加选项:
- values：这个属性用来这是选中/未选中状态。例如：{ '0' : 'Passive', '1' : 'Active' }。第一个值是未选中状态，第二个值是选中状态。
- formText：默认的，当用户改变复选框的状态时它的显示文本会跟着改变。如果你想固定文本不变，你可以为此字段设置该选项（string类型）。
- setOnTextClick：默认的，当用户点击复选框文本时，复选框的状态会改变。如果你不想做什么，可以设置该选项为false。
hidden：隐藏字段可以用于表单中编辑隐藏字段。它不会显示在表格上。你可能会想给隐藏字段设置默认值，可以使用defaultValue选项。查看案例了解简单的使用。

visibility string default: 'visible'

该字段对应的列可以通过设置此属性或者通过用户操作来展示或者隐藏。可选值：

fixed：该列会一直显示，但是用户操作不会影响。
visible：该列默认是显示的，但是可以被用户隐藏。
hidden：该列默认是隐藏的，但是可以被用户展示。

注意：用户可以通过右击列的标题来选择哪些列需要显示和隐藏。

width percentage default: '10%'

该列在表格中所占的宽。是一个百分比值（‘30%’）。如果该字段显示在表格上，那么它是必须的。最好将所有的字段的宽设置为100%。

注意：jTable的设计是适合其容器元素，而不是固定的宽度。所以，所有的列都将是100%。如果你要修改表的宽度，请设置它的容器宽度。

posted @ 2017-04-12 11:10 dm-andy 阅读(409) 评论(0) 编辑收藏举报

刷新页面返回顶部

YoungDreamer