Viselect Vanilla 实现网页元素框选功能详解

项目概述

Viselect Vanilla 是一个轻量级的纯 JavaScript 库，用于在网页中实现元素框选功能。它允许用户通过鼠标或触摸操作来选择和操作页面上的元素，非常适合需要批量操作或区域选择的 Web 应用场景。

核心特性

1. 零依赖：纯原生 JavaScript 实现，不依赖任何其他库
2. 跨框架兼容：支持 Vue、React、Preact、Svelte、Lit-Element 和 Angular 等主流前端框架
3. 响应式设计：完美适配桌面和移动设备
4. 高度可配置：提供丰富的配置选项满足不同需求
5. 轻量级：压缩后体积极小，对性能影响小

安装方式

通过包管理器安装

推荐使用 npm 或 yarn 进行安装：

npm install @viselect/vanilla

通过脚本标签引入

直接在 HTML 中引入 CDN 资源：

<script src="https://cdn.jsdelivr.net/npm/@viselect/vanilla/dist/viselect.umd.js"></script>

通过 ES6 模块导入

现代前端项目中推荐使用模块化导入：

import SelectionArea from "@viselect/vanilla"

快速开始

基础样式设置

为了使选择区域可见，需要添加一些基础样式：

.selection-area {
    background: rgba(46, 115, 252, 0.11);
    border: 2px solid rgba(98, 155, 255, 0.81);
    border-radius: 0.1em;
}

禁用文本选择

如果不需要文本选择功能，可以在容器上添加以下样式：

.container {
    user-select: none;
}

配置详解

Viselect Vanilla 提供了丰富的配置选项：

const selection = new SelectionArea({
    // 选择区域元素类名
    selectionAreaClass: 'selection-area',
    
    // 选择区域容器类名
    selectionContainerClass: 'selection-area-container',
    
    // 容器选择器
    container: 'body',
    
    // 可选择的元素选择器
    selectables: [],
    
    // 可开始选择的区域
    startareas: ['html'],
    
    // 选择边界
    boundaries: ['html'],
    
    // 行为配置
    behaviour: {
        // 重叠元素处理方式：invert(反转)、keep(保持)、drop(移除)
        overlap: 'invert',
        
        // 选择判定方式：cover(覆盖整个元素)、center(触碰中心)、touch(触碰)
        intersect: 'touch',
        
        // 触发拖动的阈值(像素)
        startThreshold: 10,
        
        // 触发选择的鼠标按键和修饰键组合
        triggers: [0],
        
        // 滚动配置
        scrolling: {
            speedDivider: 10,
            manualSpeed: 750,
            startScrollMargins: {x: 0, y: 0}
        }
    },
    
    // 功能配置
    features: {
        // 触摸支持
        touch: true,
        
        // 范围选择
        range: true,
        
        // 点击外部取消选择
        deselectOnBlur: false,
        
        // 单击选择配置
        singleTap: {
            allow: true,
            intersect: 'native'
        }
    }
});

事件系统

Viselect 提供了完整的事件生命周期：

事件名称	触发时机	返回值影响
beforestart	用户点击边界内区域时	返回 false 取消选择
beforedrag	用户开始拖动选择前	返回 false 取消拖动选择
start	选择开始时	-
move	选择进行中	-
stop	选择结束时	-

事件监听示例

selection.on('start', evt => {
    console.log('选择开始', evt);
}).on('move', evt => {
    console.log('选择进行中', evt);
}).on('stop', evt => {
    console.log('选择结束', evt);
});

API 方法

Viselect 提供了丰富的操作方法：

• resolveSelectables() - 刷新可选择元素列表
• getSelection() - 获取当前选中元素
• getSelectionArea() - 获取选择区域元素
• cancel() - 取消当前选择
• destroy() - 销毁实例
• disable()/enable() - 禁用/启用选择功能
• select()/deselect() - 手动选择/取消选择元素
• clearSelection() - 清除所有选择
• trigger() - 手动触发选择

实际应用技巧

动态列表处理

对于虚拟滚动或动态加载的列表，需要在元素变化后调用：

selection.resolveSelectables();

事件对象结构

所有事件都包含以下属性：

{
    selection: SelectionArea,  // 当前实例
    event: Event | null,       // 原始事件对象
    store: {
        touched: Element[],    // 当前触达的元素
        selected: Element[],   // 当前选择的元素
        stored: Element[],     // 所有已存储的元素
        changed: {
            added: Element[],  // 新增的元素
            removed: Element[] // 移除的元素
        }
    }
}

最佳实践

1. 性能优化：对于大型列表，合理设置 selectables 选择器，避免选择过多元素
2. 用户体验：根据场景配置合适的 intersect 模式，平衡精确度和易用性
3. 移动适配：确保启用 touch 功能并测试不同设备的触摸体验
4. 无障碍访问：为选择操作提供键盘替代方案

Viselect Vanilla 通过简洁的 API 和灵活的配置，为 Web 应用提供了强大的元素选择功能，是构建现代化交互界面不可或缺的工具之一。