TextSelectionToolbar - 文本选择工具栏组件

目录

• 功能介绍
• 核心特性
• 使用方法
  • 脚本猫
  • 基础引入
  • 基础示例
  • 使用 SVG 图标
  • 事件监听
  • 销毁工具栏
• 配置选项
• API 方法
  • 按钮管理
  • 状态控制
  • 事件系统
  • 生命周期
• 按钮配置
• 支持的事件
• 样式定制
• 浏览器兼容

功能介绍

TextSelectionToolbar 是一个纯 JavaScript 编写的文本选择工具栏组件。当用户在页面上选中文本时，会自动在选区附近显示一个浮动工具栏，用户可以点击工具栏上的按钮对选中文本执行自定义操作。

核心特性

• 自动触发：选中文本后自动显示工具栏，无需手动干预
• 智能定位：自动计算最佳显示位置，确保工具栏始终在视口内可见
• 灵活配置：支持注册多个自定义按钮、按钮组和分隔线
• 事件系统：提供完整的事件机制，支持监听显示、隐藏、按钮点击等事件
• 容器限制：可指定监听区域，只在特定容器内的文本选择时显示工具栏
• 无污染销毁：提供完整的 destroy 方法，销毁时清理所有 DOM 和事件监听
• 动画效果：内置淡入动画和小三角指示器，提升用户体验

使用方法

脚本猫

// ==UserScript==
// @grant       GM_xmlhttpRequest
// @connect     *
// @require     https://scriptcat.org/lib/4521/1.0.0/WebDAVClient.js?sha384-H3wUQ1kAa17QQ2r8YgdyAyJbQRuk9zm9e0dejIiiHAt2frfUwsSxOLOqsmOCiYIV
// ==/UserScript==

(function () {
  'use strict';
  const toolbar = new TextSelectionToolbar();
  toolbar.registerButton({
    id: 'copy',
    icon: '📋',
    title: '复制文本',
    action: (selection) => {
      navigator.clipboard.writeText(selection.text);
    }
  });
})();

基础引入

将代码直接引入页面或作为模块导入：

// 作为模块导入
const toolbar = new TextSelectionToolbar();

// 或带配置项
const toolbar = new TextSelectionToolbar({
  offsetY: 15,
  zIndex: 9999
});

基础示例

// 初始化工具栏
const toolbar = new TextSelectionToolbar();

// 注册一个按钮
toolbar.registerButton({
  id: 'copy',
  icon: '📋',
  title: '复制文本',
  action: (selection) => {
    navigator.clipboard.writeText(selection.text);
  }
});

// 注册多个按钮（按钮组）
toolbar.registerButtonGroup([
  { id: 'highlight', icon: '🖍', title: '高亮', action: (s) => highlight(s.text) },
  { divider: true },
  { id: 'search', icon: '🔍', title: '搜索', action: (s) => search(s.text) },
  { id: 'translate', icon: '🌐', title: '翻译', action: (s) => translate(s.text) }
]);

使用 SVG 图标

toolbar.registerButton({
  id: 'bold',
  icon: '<svg viewBox="0 0 24 24" width="16" height="16"><path d="M15.6 10.79c.97-.67 1.65-1.77 1.65-2.79 0-2.26-1.94-4-4.37-4H7v14h7.04c2.1 0 3.96-1.73 3.96-3.87 0-1.54-.97-2.87-2.4-3.34z"/></svg>',
  title: '加粗',
  action: (selection) => {
    document.execCommand('bold');
  }
});

事件监听

toolbar.on('show', (selection) => {
  console.log('工具栏显示了，选中文本：', selection.text);
});

toolbar.on('hide', () => {
  console.log('工具栏隐藏了');
});

toolbar.on('buttonClick', (data) => {
  console.log('点击了按钮：', data.buttonId);
});

销毁工具栏

// 使用完毕后销毁，清理所有 DOM 和事件
toolbar.destroy();

配置选项

API 方法

按钮管理

状态控制

事件系统

生命周期

按钮配置

注册按钮时传入的配置对象：

{
  id: 'unique_id',        // 按钮唯一标识符（必填）
  icon: '📌',             // 钮图标（支持 emoji、SVG、HTML）
  title: '固定到顶部',    // 鼠标悬停时显示的提示文字
  action: (selection) => { // 点击回调函数
    // selection 包含:
    // - text: 选中的文本内容
    // - selection: 原生 Selection 对象
    // - range: 选区的 Range 对象
  }
}

支持的事件

样式定制

组件会注入默认样式，但可以通过覆盖 CSS 类来自定义外观：

/* 自定义按钮样式 */
.text-toolbar-btn {
  background: #f5f5f5;
  color: #333;
}

/* 自定义悬停效果 */
.text-toolbar-btn:hover {
  background: #e0e0e0;
  color: #000;
}

/* 自定义激活效果 */
.text-toolbar-btn:active {
  background: #d0d0d0;
  transform: scale(0.98);
}

/* 自定义分隔线样式 */
.text-toolbar-divider {
  background: #ccc;
}

浏览器兼容

组件使用原生 JavaScript 实现，兼容所有现代浏览器：

⚠️ 不支持 IE 浏览器。