[译] Spark DataGrid Editing SPEC

[译文原创链接: http://www.smithfox.com/?e=168 转载请保留此声明, 谢谢! ]

源文: Spark DataGrid Editing - Functional and Design Specification

介绍:

Spark DataGrid支持两种方式来编辑单元格的值: "item editor" 或是 "item renderer"自身.
"item editor"是一个临时显示在单元格上的组件, 它提供UI来编辑和保存单元格内的值. 

一个"item editor"可以是任何一个实现了 IGridItemEditor 接口的Spark组件, 并且DataGrid每列都可以指定不同的 "item editor" 类.

就象 "item renderer"一样, "item editor"所显示的内容依赖于 dataProvider当前行的内容.

默认情况下, 用户点击了一个 "已选中的" 单元格时才会显示 "item editor", 而且前提必须是: DataGrid的所在GridColumn的 "editable" 属性都是 "true".

在"item editor"有键盘focus的情况下, 回车会保存, 而 "escape" 会使"item editor"直接退出而不保存.

在某些情况下, "item renderer" 自身直接就是单元格的 editor. 如果某列的 "rendererIsEditable" 属性是 true, 点击已选中的单元格(或是用键盘再次选择些单元格)会使键盘的focus移到 "item renderer", 这种情况, 没有其它 editor可选.

GridItemEditor是创建"item editor"的基类. DefaultGridItemEditor 和 ComboBoxGridItemEditor 继承于 GridItemEditor类. GridItemEditor实现了IGridItemEditor接口, 所以一般的 "item editor"只需覆盖少数几个属性和方法就可以了.

Item Editor 生命周期:

"item editor" 的 "session" 开始于响应用户的操作, 比如 "点击一个已选中单元格, 或是显示地调用 DataGrid.startItemEditorSession() 方法."item editor" 是作用在单元格上的, 单元格是可以由row和column的index来定位的.

在 "item edtiro" 显示之前, 会发出一个 "gridItemEditorSessionStarting" GridItemEditorEvent 事件到DataGrid.

这个事件Listener的句柄函数可以通过 Event.preventDefault()方法取消事件, 从面使 "editing session"中止.也可以动态改变列的 itemEditor 属性.

"Item editor"是由 GridColumn.itemEditor属性指定的 IGridItemEditor 类创建的.

和"item renderer"一样, "item editor"实列是重复使用的.如果没有指定 itemEditor, 则默认的 "item editor"类DefaultGridItemEditor会用TextArea 组件来编辑单元格的值.在"item editor"显示前,  rowIndex, column, 和 data 属性都已经被设置好了. 其中 "data" 属性的值就是 dataProvider.getItemAt(rowIndex).

所有实现IGridItemEditor接口的类应该用 "data"的 setter 中去初始化编辑组件的值默认实现类GridItemEditor 用 data[column.dataField] 设置 value属性. 这样允许子类 通过 覆盖 value setter方法将值赋给更多的编辑控件.

下面就是一个定制的 "item editor", 和"default item editor" 相似,用的是TextArea组件:

<s:itemEditor>
    <fx:Component>
	<s:GridItemEditor>
	    <s:TextArea id="valueDisplay"/>
	    <fx:Script>
		<![CDATA[
		    override public function get value():Object
		    {
			return valueDisplay.text;            
		    }

		    override public function set value(newValue:Object):void
		    {
			valueDisplay.text = newValue.toString();
		    }                                        
		]]>
	    </fx:Script>
	</s:GridItemEditor>
    </fx:Component>
</s:itemEditor>

"item editor"被创建后,  在"visible"属性设置为 "true"之前会调用 prepare()方法. 在调用 prepare()后, "item editor"的大小和位置就会被设置, "item editor"的 layout也已经 validated了.开发者可以覆盖 prepare() 方法来微调"item editor"的任何方面. 在下面的例子中,  prepare() 方法用来水平方向放置 textArea组件:

<s:itemEditor>
    <fx:Component>
	<s:DefaultGridItemEditor>
	    <fx:Script>
		<![CDATA[
		    override public function prepare():void
		    {
			super.prepare();
			textArea.y += 8;
			textArea.height -= 16; 
		    }
		]]>
	    </fx:Script>
	</s:DefaultGridItemEditor>
    </fx:Component>
</s:itemEditor> 

在"item editor" 置为可见后, 将发送一个  "gridItemEditorStart" GridItemEditorEvent 事件到DataGrid.但 "item editor" 第一次显示后, 紧接着就会被调用 setFocus()方法, 从而获取了键盘 focus. setFocus() 方法能用来现次将 键盘 focus 移动真正的编辑组件上.例如 DefaultGridItemRenderer类的 setFocus() 应该就是将 focus设置到它的TextArea控件上了.
当"item editor"已经显示, 并且用户可以编辑新的值的时候, "edit session" 就正式开始了.直到调用DataGrid.endEditorSession()使 "edit session" 结束.默认情况下,回车或是"escape"会调用此方法, 并且调用之前分别会 "save"  "cancel". 如果用户点击了"editor"的外面, 或是"item editor"失去键盘focus时, 都会 保存 session.在定义了保存session的快捷键或是在其它的单元格打开了一个 "editor"都会保存 当前的session.session被 saved() ,"editor的 save方法就会被调用.
基类GridItemRenderer 的 save() 方法能根据需要转换字符串为数值或是布尔. 如果editor的值不是, string, numbers, booleans, 那就应该覆盖 save() 方法, 例如:

<s:itemEditor>
    <fx:Component>
	<s:DefaultGridItemEditor>
	    <fx:Script>
		<![CDATA[
		    override public function save():void
		    {
		        data.dataField = myValueConverter(value);
		    }
		]]>
	    </fx:Script>
	</s:DefaultGridItemEditor>
    </fx:Component>
</s:itemEditor> 

在"editor"的 save()或是 cancel()方法调用结束后, 就会发送一个通知性的事件: gridItemEditorSessionSave 或是 gridItemEditorSessionCancel.
另外, ComboBoxGridItemEditor的dataProvider是一个list, 内部用ComboBox来呈现这些list中的值. 因为继承自GridItemEditor所以支持string, number, and boolean. 下例就是显示一个数值列表.

<s:itemEditor>
    <fx:Component>
	<s:ComboBoxGridItemEditor>
	    <s:dataProvider>
		<s:ArrayList>
		    <fx:int>0</fx:int>
		    <fx:int>1</fx:int>
		    <fx:int>2</fx:int>
		    <fx:int>3</fx:int>
		</s:ArrayList>
	    </s:dataProvider>
	</s:ComboBoxGridItemEditor>
    </fx:Component>
</s:itemEditor>

键盘快捷键:

省略翻译:

鼠标操作:

单击:  一个已选中的单元格被点击, 将会打开 "item editor". 如果同时shift键或是ctrl键也按下在, 则"itemEditor"不会打开,因为shift键或是ctrl键是被用来改变grid的选择项的.

双击:  默认情况下, 双击是不会打开 "itemEditor"的. 需要将 DataGrid.doubleClickEnabled 属性设置为 "true".

GridItemEditor, DefaultGridItemEditor, ComboBoxGridItemEditor

(省略一些显而易见的废话 ... )

IGridItemEditor.validate() 方法负责验证"editor"的值是否能被保存. 基类GridItemRenderer验证每个 editor的上层 IValidatorListener 成员, 看是否报错.
如果 validate方法返回false, 则在调用 save()方法后, "edit session" 是不会被关闭的. 如果直接调用DataGrid.endEditorSession(true) 方法, 则肯定能关闭"edit session".save()方法的这种默认行为可能通过覆盖 GridItemEditor.save()方法来改变.
注意: 子类在覆盖GridItemEditor类的方法, 时应该调用super.xxx()保证默认的行为.

GridItemEditor, DefaultGridItemEditor.mxml和ComboBoxGridItemEditor.mxml 都在 Flex SDK source: spark.components.gridClasses 包下.