现代拖放

简介

Ext JS 6.2 引入了 Ext.drag API，为 Calendar 包提供了跨工具包的拖放解决方案。此 API 提供了一系列类，允许应用程序轻松添加自定义拖放功能，范围从基本元素操作到复杂的异步数据传输。Ext.drag API 仿照 HTML5 拖放 API 构建，并在其基础上进行了极大的扩展，可用于 Classic 和 Modern Toolkits。

概述

Ext.drag 使元素级 API 保持简单，并提供适当的钩子以与您的组件结合使用。它还允许数据相关操作异步发生。

Ext.drag 由两个主要类组成：Ext.drag.Source 和 Ext.drag.Target。源是可以拖动的东西。目标是可以接收来自源的放置的东西。这两个类都附加到 Ext.dom.Element。

此命名空间还包括处理元素级交互的功能。对于组件，通常需要包装这些类以提供更友好的组件界面。

Ext.drag.Source

拖动源表示可以在屏幕上拖动的可移动元素。以下是一些主要功能

约束

约束限制了拖动可能发生的位置。源的约束由 Ext.drag.Constraint 类处理。此类的配置（以及一些快捷方式）可以传递给拖动源。一些有用的选项包括

• 将拖动限制为仅水平或垂直

• 将拖动限制为特定的屏幕区域 (Ext.util.Region)

• 将拖动限制为父元素

• 通过捕捉到网格的增量来限制拖动的位置。

您可以在我们的 Kitchen Sink Example 中看到应用约束的示例

拖动手柄

默认情况下，源元素任何部分的拖动手势都会启动源上的拖动。手柄允许使用 css 选择器指定元素的特定部分。这在 2 种主要情况下很有用

1. 源应仅在特定区域中拖动，例如，窗口的标题栏。

2. 源具有许多重复元素，应使用唯一数据触发拖动，例如 dataview。

您可以在我们的 Kitchen Sink Example 中看到应用约束的示例

代理

拖动代理是在拖动进行时屏幕上显示的视觉表示。代理元素（如果指定）跟随鼠标光标。此命名空间中当前提供了 3 种实现

1. 原始（默认） - 源元素被移动。

2. 占位符 - 创建一个新元素，并将源元素留在原位。

3. 无 - 不显示代理元素。这通常与 Source 事件结合使用以显示拖动信息。

事件/模板方法

源上的以下事件和模板方法在拖动周期的指定点可用

• beforedragstart/onBeforeDragStart，可以通过返回 false 取消。

• dragstart/onDragStart

• dragmove/onDragMove

• dragend/onDragEnd

• dragcancel/onDragCancel

var logger = Ext.getBody().createChild({
    tag: 'textarea',
    rows: 15,
    cols: 80
}).dom;

function log(eventName, type) {
    return function(item) {
        var val = logger.value;
        if (val.length) {
            val += '\n';
        }

        val += '"' + eventName + '" fired on ' + type;
        logger.value = val;
        logger.scrollTop = logger.scrollHeight;
    };
}

new Ext.drag.Source({
    element: Ext.getBody().createChild({
        html: 'Drag Me',
        style: {
            zIndex: 10,
            width: '100px',
            height: '100px',
            border: '1px solid red',
            position: 'absolute',
            top: '50px',
            left: '600px'
        }
    }),
    listeners: {
        beforedragstart: log('beforedragstart', 'Source'),
        dragstart: log('dragstart', 'Source'),
        dragmove: log('dragmove', 'Source'),
        dragend: log('dragend', 'Source')
    }
});

new Ext.drag.Target({
    element: Ext.getBody().createChild({
        html: 'Drop Here',
        style: {
            width: '300px',
            height: '300px',
            border: '1px solid blue',
            position: 'absolute',
            top: '250px',
            left: '600px'
        }
    }),
    listeners: {
        dragenter: log('dragenter', 'Target'),
        dragmove: log('dragmove', 'Target'),
        dragleave: log('dragleave', 'Target'),
        beforedrop: log('beforedrop', 'Target'),
        drop: log('drop', 'Target')
    }
});

Ext.drag.Target

拖动目标表示可以接收来自源的放置的元素。其大部分功能将在源/目标部分之间的数据交换和交互中描述。

事件/模板方法

源上的以下事件和模板方法在拖动周期的指定点可用

• dragenter/onDragEnter

• dragmove/onDragMove

• dragleave/onDragLeave

• beforedrop/onBeforeDrop，可以通过返回 false 取消。

• drop/onDrop

Ext.data.Info

此类充当单个拖动生命周期的中介和信息持有者。它保存有关特定拖动的所有信息。它还管理拖动的数据交换。此类在整个拖放周期中传递给所有相关事件/模板方法。

描述数据

拖放提供了移动元素和接收事件的机制，但是它没有描述这些操作的底层含义。本节讨论如何使用该数据。

通用

键控数据

与 HTML5 拖动 API 类似，数据被指定为一组键/值对。键用于指示正在传递的数据类型。键的值不受限制，但通常会引用数据类型（文本/图像）或业务逻辑对象（用户/订单）。单个拖动操作可以有许多键/值对。对于添加到 setData 方法的每个键，它也会添加到 info 对象上的 types 数组中，以查询可用类型。

此架构在以下几个方面很有用

• 它允许目标快速决定它们是否对特定源感兴趣。如果某些拖动数据标记为“csv”，则作为表或网格的放置目标可能能够使用该数据，但它可能对文本字段无用。

• 它允许数据根据目标而有所不同。考虑正在拖动的图像类型。可以设置 2 个键，以允许不同目标使用。当放置发生在文本字段目标上时，它可以使用文本数据。在占位符图像目标上，它可以读取 blob 数据并显示图像

  describe: function(info) {

    // The text link to the image
    info.setData('text', theImage.link); 
  
    // The binary image data
    info.setData('image', toBlob(theImage)); 
  

  }

数据可用性

数据可通过 info 对象上的 getData 方法使用以供使用。如果在放置完成之前调用此方法，则会引发异常。只能事先查询数据类型。这样做有两个原因

• 为了与 HTML5 拖动 API 保持一致（应用相同的限制）

• 数据可能难以生成或需要从远程源检索，因此限制访问直到需要时才有用。

但是，仍然可以在 info 对象上拥有在拖动期间可访问的数据。info 对象在整个拖动过程中持续存在，因此可以在任何时候添加属性

describe: function(info) {
    info.userRecords = getTheRecords();
}

指定数据

当拖动启动时，将在源上调用 describe 方法。拖动的数据应在此处指定。这预计由用户实现。describe 方法接收 info 对象。

setData

setData 方法使用 2 个参数调用，一个描述数据的字符串键和一个值。该值可以是任何数据值数据类型（字符串、数字、对象、数组）。它也可以是一个函数，当调用 getData 时将执行该函数以生成数据。请注意，对 getData 的调用仅限于放置完成时。

describe: function(info) {
    // Set immediately available data
    info.setData('userId', user.id);

    // Setup a function to retrieve the data from the server on drop
    info.setData('userInfo', function() {
        var options = {}; // ajax options
        return Ext.Ajax.request(o);
    });
}

Info 属性

或者，如果数据立即可用或易于构造，则可以将其作为属性直接推送到 info 对象上。此数据将在拖动操作的生命周期内的任何时间可用。

describe: function(info) {
    info.userRecords = getTheRecords();
}

使用数据

getData

应从 drop 侦听器或 onDrop 模板方法调用 getData 以检索数据。此方法接受一个参数，即从 setData 指定的数据的键。从 getData 返回的值将始终是 Promise，而与底层类型无关。使用上面的数据集

listeners: {
    drop: function(target, info) {
        info.getData('userId').then(function(v) {
            console.log(v);
        });

        info.getData('userInfo').then(function(response) {
            // The ajax response
        }).catch(function() {
            // Oh no!
        });
    }
}

在这种情况下，userId 值将可用，因此 promise 将立即解决。对于 ajax 数据的情况，它将等待直到请求返回。

Info 属性

对于存储在 info 对象上的属性，可以使用正常的属性访问来访问它们

listeners: {
    drop: function(target, info) {
        console.log(info.userRecords);
    }
}

源和目标之间的交互

默认情况下，所有源都可以与所有目标交互。这可以通过多种方式进行限制。一旦满足一系列条件，目标上的拖动就被认为是有效的。目标仍然会接收无效目标的事件，但是 info 对象上的 valid 标志将为 false。

禁用状态

如果源被禁用，则无法拖动。如果目标被禁用，则任何源都无效。

组

源和目标都可以属于组。组是一个标识符，指示哪些项目可以相互交互。组可以是单个字符串或字符串数组。属于同一组的项目可以交互。以下规则适用

• 如果源和目标都没有组，则拖动有效。

• 如果源和目标都有组并且组相交，则拖动有效。

• 如果源和目标都有组但没有交集，则拖动无效。

• 如果源有组但目标没有，则拖动无效。

• 如果源没有组但目标有，则拖动无效。

以下是一些示例源组配置

// Can only be dropped on targets with no groups
{}

// Can only be dropped on targets that contain group1
{ groups: 'group1' }

// Can be dropped on targets that contain group1 or group2
{ groups: ['group1', 'group2'] }

接受

目标具有可配置的方法 accepts，该方法在源首次进入目标时调用。这允许目标在每个源的基础上确定是否会与其交互。accepts 方法传递 info 对象，应返回一个布尔值，指示是否接受源。请注意，getData 方法不能在此处调用，但是可以访问 info 对象上的任何属性。

// Interrogating types
{
    accepts: function(info) {
        return info.types.indexOf('userRecord') > -1;
    }
}

// Accessing property data
new Ext.drag.Source({
    describe: function(info) {
        info.total = 100;
    }
});

new Ext.drag.Target({
    accepts: function(info) {
        return info.total > 75;
    }
});

组件集成

将拖动命名空间与组件结合使用时，通常需要将部件包装在插件或其他容器中，以提供更好的上下文 API。以下代码示例实现了在 Modern Grid 中拖动行的能力。

该代码不处理执行拖放的任何机制，但是它确实提供了更好的 API 以与组件一起使用，以及填充使拖动功能正常工作所需的一些较低级别的细节。

在此示例中，我们将自定义拖放插件与 Grid 集成。然后，我们将禁用记录名称为“Bar”的任何内容的拖动。

Ext.define('RowDragger', {
    extend: 'Ext.AbstractPlugin',
    alias: 'plugin.rowdrag',

    mixins: ['Ext.mixin.Observable'],

    config: {
        recordType: ''
    },

    constructor: function(config) {
        this.mixins.observable.constructor.call(this, config);
    },

    init: function(component) {
        var me = this,
            type = this.getRecordType();

        this.source = new Ext.drag.Source({
            element: component.element,
            delegate: '.x-grid-row',
            describe: function(info) {
                var row = Ext.Component.fromElement(info.eventTarget, component, 'gridrow');
                info.record = row.getRecord();
            },
            proxy: {
                type: 'placeholder',
                getElement: function(info) {
                    var el = this.element;
                    if (!el) {
                        this.element = el = Ext.getBody().createChild({
                            style: 'padding: 10px; width: 100px; border: 1px solid gray; color: red;',
                        });
                    }
                    el.show().update(info.record.get('name'));
                    return el;
                }
            },
            autoDestroy: false,
            listeners: {
                scope: me,
                beforedragstart: this.makeRelayer('beforedragstart'),
                dragstart: this.makeRelayer('dragstart'),
                dragmove: this.makeRelayer('dragmove'),
                dragend: this.makeRelayer('dragend')
            }
        });
    },

    disable: function() {
        this.source.disable();
    },

    enable: function() {
        this.source.enable();
    },

    doDestroy: function() {
        Ext.destroy(this.source);
        this.callParent();
    },

    makeRelayer: function(name) {
        var me = this;
        return function(source, info) {
            return me.fireEvent(name, me, info);
        };
    }
});

Ext.define('User', {
    extend: 'Ext.data.Model',
    fields: ['name']
});

Ext.Viewport.add({
    xtype: 'grid',
    store: {
        model: 'User',
        data: [{
            id: 1,
            name: 'Foo'
        }, {
               name: 'Bar'
               }, {
               name: 'Baz'
               }]
    },
    columns: [{
        dataIndex: 'name',
        text: 'Name',
        flex: 1
    }],
    plugins: [{
        type: 'rowdrag',
        recordType: 'user',
        listeners: {
            beforedragstart: function(plugin, info) {
                return info.record.get('name') !== 'Bar';
            }
        }
    }]
});

结论

随着 Ext JS 的不断发展，Ext.drag API 将被整合到插件中，例如上面的示例以及更多插件。目前，Ext.drag 提供了一种便捷的方式来处理 Toolkits 的拖放操作，并且与标准的 HTML5 API 良好兼容。