Question

如何使用 Gridx

Answer 1

创建 Gridx
选用合适的 store 和 cache
　　Gridx 与 DataGrid 一样，都以 Dojo 的 store 作为数据源。不过，Gridx 需要用户指出所用的 store 是异步的还是同步的。异步 store 通常由服务器端提供数据，向它请求数据时往往需要异步地接收返回数据；而同步 store 的所有数据一般都在客户端，因此所有的请求都能同步完成。异步 store 往往会带来更为复杂的逻辑，因此 Gridx 针对这两种 store 分别进行了优化。但由于无法从 store 本身得知它是否异步，同时为了减小代码量，用户需要将这个信息告知 Gridx。告知的方法是设置 cacheClass 参数：

　　清单 1. 创建 Gridx 并配置 cacheClass 参数
　　require([
　　"gridx/Grid",
　　"gridx/core/model/cache/Sync",
　　......
　　"dojo/domReady!"
　　], function(Gridx, Cache, ......){
　　......
　　var grid = new Gridx({
　　cacheClass: Cache
　　store: store,
　　......
　　});
　　grid.placeAt('gridContainerNode');
　　grid.startup();
　　});目前 Gridx 有两种 cache 实现：gridx/core/model/cache/Sync 和 gridx/core/model/cache/Async，前者用于同步 store，后者用于异步 store。Async 的实现逻辑比 Sync 要复杂得多，这是因为它需要考虑数据的延迟加载。这样，如果用户的应用只需要客户端数据，就完全不必用到关于延迟加载的代码，从而减小了最终下载到浏览器的代码量。

　　cacheClass 既可以直接接受 cache 实现的构造函数（如上例），也可以接受 MID，例如：

　　清单 2. 用 MID 设置 cacheClass 参数
　　var grid = new Gridx({
　　cacheClass: "gridx/core/model/cache/Async"
　　......
　　});这种写法更适合以 HTML 声明的方式创建 Gridx 的场合，因为它不需要引入额外的变量。

　　目前 Gridx 能够直接支持 dojo(x)/data/* 的老 store 以及 dojo/store/* 的新 store，而不需要任何适配转换。常用的同步 store 有 dojo/data/ItemFileWriteStore 以及 dojo/store/Memory。常用的异步 store 有 dojox/data/JsonRestStore、dojox/data/QueryReadStore 以及 dojo/store/JsonRest。

　　需要特别注意的是，Gridx 要求 store 中的数据行必须具有唯一标识符（ID）。对于老 store 而言，也就是必须要实现 dojo/data/api/Identity。所幸刚才列举的常用 store 都满足这个要求。

　　声明列
　　配好 store 并选择好 cache 之后，就需要声明 Gridx 的列结构。列声明使用 structure 参数，这和 DataGrid 类似。所不同的是，Gridx 的列声明结构非常简单，只支持一维数组，没有 DataGrid 中视图（View）和子行（rows/cells）等复杂的声明结构：

　　清单 3. 一维数组结构的列声明
　　var grid = new Gridx({
　　cacheClass: Cache
　　store: store,
　　structure: [
　　{id: 'column1', ......},
　　{id: 'column2', ......},
　　{id: 'column3', ......},
　　......
　　]
　　});下面各小节详细介绍列声明中各个属性的含义。

　　id、name、field
　　对于 Gridx 来说，每一列都有一个唯一标识符（ID）。用户最好能指定一些有意义的 ID，从而方便以后的使用。如果用户没有指定，那么 Gridx 会分别赋予"1", "2", "3", ....... 等字符串类型的自然数作为列的默认 ID。

　　与 DataGrid 类似，name 属性是指表头上显示出来的列名。name 属性可以是任意字符串，甚至可以包含 HTML 标签，从而做出各种定制效果。例如：{id: 'column1', name: '<b>Company <i>Name</i></b>'}。

　　field 属性也是从 DataGrid 沿袭下来的，指该列在 store 中的对应域。该列中的单元格会从这个 field 域中取得数据。

　　图 1. name 属性作为普通字符串、未指定、以及带 HTML/CSS 的各种情况

　　formatter 函数
　　Gridx 的 formatter 函数与 DataGrid 中的同名函数不同，其目的在于为 Gridx 提供数据，而不是对数据做显示上的修饰。如果某一列没有 field 参数，就可以通过 formatter 函数来提供数据，例如：

　　清单 4. 使用 formatter 函数组合多个域的数据
　　{id: 'column1', formatter: function(rawData){
　　return rawData.field1 + rawData.field2;
　　});这样，这一列就能显示两个数据域的和。

　　图 2. formatter 函数综合多个数据域的内容产生了 Summary 列中的数据

　　formatter 函数所传入的 rawData 参数是以 store 的 field 名称作为 key 的关联数组（对象），包含当前行中的所有数据，形如：

　　清单 5. rawData 格式
　　rawData: {
　　field1: data1,
　　field2: data2,
　　......
　　}这种形式要比某些 store（主要是老 store）的数据项（item）更容易使用，也使接口与新 store 保持一致。

　　decorator 函数
　　Gridx 对数据的产生和数据的修饰做了严格的区分。formatter 是用于产生数据，decorator 函数则用于修饰数据。例如：

　　清单 6. 用 decorator 函数为单元格添加 HTML/CSS
　　{id: 'column1', field: 'field1',
　　decorator: function(cellData, rowId, rowIndex){
　　return "<a href='www.google.com?q=" + cellData + "'><b>" +
　　cellData + "</b></a>";
　　}
　　}这样就能在单元格中显示出链接。

　　图 3. 使用 decorator 对数据做修饰

　　decorator 函数只能返回字符串，不像 DataGrid 的 formatter 函数还可以返回 widget 实例。关于如何在单元格中显示 widget 的问题将在其他文章中详细介绍。

　　style 和 class
　　通过在 decorator 函数中加入 HTML 标签和 style 属性可以对单元格中的内容做各种修饰，但无法改变单元格本身的样式。要做到这一点，需要 style 或 class：

　　清单 7. 字符串形式的 style 和 class 参数
　　{id: 'column1', field: 'field1',
　　style: 'text-align: center;',
　　'class': 'mySpecialColumn'
　　}style 和 class 都会直接加入到 <TD> 标签的 style 属性和 class 属性。

　　style 和 class 还可以写成一个返回字符串的函数，这样单元格的样式就能随数据而变化：

　　清单 8. 函数形式的 style 和 class 参数
　　{id: 'column1', field: 'field1',
　　style: function(cell){
　　return cell.data() % 2 ? 'color: red;' : 'color: blue;';
　　},
　　'class': function(cell){
　　return cell.data() %2 ? 'oddClass' : 'evenClass';
　　}
　　}这里 style 和 class 函数所传入的 cell 参数代表了当前所处理的单元格，可以通过各种方便的方法获取有关该单元格的一切信息。

　　图 4. 使用 style 函数为每一个单元格设置独特背景色的例子

　　配置功能模块
　　有了 store、cacheClass 和 structure 后，Gridx 就能运行了。不过这样的 Gridx 除了显示数据之外，几乎没有任何界面功能。Gridx 几乎所有的功能都是由可选模块（module）实现的，需要在创建时声明使用了那些模块。这提供了巨大的灵活性来满足各种不同的需求。

　　声明模块的是 modules 属性：

　　清单 9. 通过 modules 参数配置功能模块
　　require([
　　"gridx/Grid",
　　"gridx/core/model/cache/Sync",
　　"gridx/modules/VirtualVScroller",
　　"gridx/modules/ColumnResizer",
　　"gridx/modules/Focus",
　　"gridx/modules/SingleSort",
　　......
　　dojo/domReady!"
　　], function(Gridx, Cache, VirtualVScroller, ColumnResizer, Focus, SingleSort, ......){
　　......
　　var grid = new Gridx({
　　cacheClass: Cache
　　store: store,
　　structure: structure,
　　vScrollerLazy: true,// 模块参数可作为 Gridx 参数传递
　　modules: [
　　VirtualVScroller, // 用法 1：直接列举模块构造函数
　　"gridx/modules/ColumnResizer", // 用法 2：模块 MID
　　{ // 用法 3：带有 moduleClass 的对象
　　moduleClass: SingleSort,
　　initialOrder: { colId: 'column1', descending: true }
　　},
　　{ // 用法 4： moduleClass 也接受 MID
　　moduleClass: "gridx/modules/Focus"
　　}
　　]
　　});
　　......
　　});从上面的例子可见，要使用一个模块先要引入该模块的文件，然后直接列举在 modules 数组中即可。modules 数组中的模块既可以是模块构造函数本身，也可以是模块的 MID，还可以是一个含有 moduleClass 属性的对象。模块本身也可能有参数，这些参数既可以与 moduleClass 一起放在一个对象里（如 initialOrder），也可以直接作为 Gridx 的参数，只不过需要加上所属模块的名称作为前缀（如 vScrollerLazy，这里 vScroller 是模块名称，lazy 是属性名，加上前缀后首字母大写）。模块参数直接作为 Gridx 参数可以使代码更为简洁，因此是推荐的配置方法。

　　上面的例子中加入了 4 个模块：VirtualVScroller 实现了延迟渲染的功能，每次只渲染出需要显示的行，从而可以很快地完成拥有大量数据的 Grid 的创建；ColumnResizer 实现了鼠标拖动改变列宽的功能；SingleSort 是一个单列排序的简单实现；Focus 模块则是对键盘的支持，这是一个被许多其他模块引用的模块，对于 A11y 非常重要。

　　熟悉 DataGrid 的用户会发现这些功能在 DataGrid 中都是默认自带的。虽然这些功能很常用，但用户在不需要它们的时候却难以屏蔽；即使能够屏蔽它们的功能，大量的有关这些功能的代码也依旧存在，而这不失为一种浪费。