tm-ui-common

v2.0.1

Published

3 months ago

A reusable UI component library for Tampermonkey scripts

0High
0Medium
0Low

reerdream

tampermonkey ui components javascript es6 css3 html5

tm-ui-common

一个为 Tampermonkey 脚本设计的可重用 UI 组件库。

特性

📦 轻量级 - 无依赖，纯 JavaScript 实现
🎨 可定制 - 丰富的样式选项和主题支持
📱 响应式 - 适配不同屏幕尺寸
♿ 可访问性 - 遵循 WCAG 标准
🧪 测试覆盖 - 完整的单元测试

安装

npm install tm-ui-common

快速开始

基本使用

import { Button, Input, Label, Icon } from 'tm-ui-common';

// 创建按钮
const button = new Button({
  text: '点击我',
  type: 'primary',
  onClick: (event) => {
    console.log('按钮被点击了');
  }
});

// 创建输入框
const input = new Input({
  placeholder: '请输入内容',
  clearable: true,
  onChange: (event) => {
    console.log('输入框内容变化:', input.getValue());
  }
});

// 创建标签
const label = new Label({
  text: '这是一个标签',
  type: 'success',
  closable: true,
  onClose: () => {
    console.log('标签被关闭了');
  }
});

// 创建图标
const icon = new Icon({
  name: '搜索图标',
  type: 'svg',
  svgPath: 'M15.5 14h-.79l-.28-.27A6.471 6.471 0 0 0 16 9.5 6.5 6.5 0 1 0 9.5 16c1.61 0 3.09-.59 4.23-1.57l.27.28v.79l5 4.99L20.49 19l-4.99-5zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z',
  onClick: () => {
    console.log('图标被点击了');
  }
});

在 HTML 中使用

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>tm-ui-common 示例</title>
  <!-- 引入样式 -->
  <link rel="stylesheet" href="node_modules/tm-ui-common/dist/tm-ui-common.css">
</head>
<body>
  <div id="app"></div>
  
  <!-- 引入脚本 -->
  <script type="module">
    import { Button, Input, Label, Icon } from 'node_modules/tm-ui-common/dist/tm-ui-common.esm.js';
    
    const app = document.getElementById('app');
    
    // 创建按钮
    const button = new Button({
      text: '点击我',
      type: 'primary',
      container: app
    });
    
    // 创建输入框
    const input = new Input({
      placeholder: '请输入内容',
      container: app
    });
  </script>
</body>
</html>

在 Tampermonkey 脚本中使用

// ==UserScript==
// @name         示例脚本
// @namespace    http://tampermonkey.net/
// @version      0.1
// @description  使用 tm-ui-common 的示例脚本
// @author       You
// @match        https://example.com/*
// @grant        none
// @require      https://cdn.jsdelivr.net/npm/tm-ui-common@latest/dist/tm-ui-common.js
// ==/UserScript==

(function() {
  'use strict';
  
  // 创建容器
  const container = document.createElement('div');
  container.style.position = 'fixed';
  container.style.top = '10px';
  container.style.right = '10px';
  container.style.zIndex = '9999';
  document.body.appendChild(container);
  
  // 创建按钮
  const button = new TMUICommon.Button({
    text: '点击我',
    type: 'primary',
    onClick: () => {
      alert('按钮被点击了');
    },
    container: container
  });
  
  // 创建输入框
  const input = new TMUICommon.Input({
    placeholder: '请输入内容',
    container: container
  });
})();

组件

按钮 (Button)

按钮组件支持多种类型、尺寸和状态。

属性

| 属性 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | text | string | 'Button' | 按钮文本 | | type | string | 'primary' | 按钮类型 (primary, secondary, success, danger, warning, info, light, dark) | | size | string | 'medium' | 按钮尺寸 (small, medium, large) | | disabled | boolean | false | 是否禁用 | | loading | boolean | false | 是否显示加载状态 | | block | boolean | false | 是否块级显示 | | outline | boolean | false | 是否轮廓样式 | | rounded | boolean | false | 是否圆角 | | icon | string | '' | 图标类名 | | iconPosition | string | 'left' | 图标位置 (left, right) | | onClick | function | null | 点击事件处理函数 | | container | HTMLElement | document.body | 容器元素 |

方法

| 方法 | 描述 | | --- | --- | | setText(text) | 设置按钮文本 | | setType(type) | 设置按钮类型 | | setSize(size) | 设置按钮尺寸 | | setDisabled(disabled) | 设置禁用状态 | | setLoading(loading) | 设置加载状态 | | setBlock(block) | 设置块级显示 | | setOutline(outline) | 设置轮廓样式 | | setRounded(rounded) | 设置圆角 | | setIcon(icon) | 设置图标 | | setIconPosition(iconPosition) | 设置图标位置 | | getElement() | 获取按钮元素 | | destroy() | 销毁按钮 |

输入框 (Input)

输入框组件支持多种类型、尺寸和状态。

属性

| 属性 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | type | string | 'text' | 输入框类型 (text, password, email, number, tel, search, url, etc.) | | placeholder | string | '' | 占位符文本 | | value | string | '' | 初始值 | | label | string | '' | 标签文本 | | name | string | '' | 输入框名称 | | disabled | boolean | false | 是否禁用 | | readonly | boolean | false | 是否只读 | | required | boolean | false | 是否必填 | | clearable | boolean | false | 是否可清除 | | size | string | 'medium' | 输入框尺寸 (small, medium, large) | | prefix | string | '' | 前缀文本或图标 | | suffix | string | '' | 后缀文本或图标 | | maxlength | number | undefined | 最大输入长度 | | minlength | number | undefined | 最小输入长度 | | max | number | undefined | 最大值（仅对数字类型有效） | | min | number | undefined | 最小值（仅对数字类型有效） | | step | number | undefined | 步长（仅对数字类型有效） | | onChange | function | null | 值变化事件处理函数 | | onFocus | function | null | 聚焦事件处理函数 | | onBlur | function | null | 失焦事件处理函数 | | onInput | function | null | 输入事件处理函数 | | onClear | function | null | 清除事件处理函数 | | container | HTMLElement | document.body | 容器元素 |

方法

| 方法 | 描述 | | --- | --- | | getValue() | 获取输入框值 | | setValue(value) | 设置输入框值 | | getType() | 获取输入框类型 | | setType(type) | 设置输入框类型 | | getPlaceholder() | 获取占位符文本 | | setPlaceholder(placeholder) | 设置占位符文本 | | getName() | 获取名称 | | setName(name) | 设置名称 | | setDisabled(disabled) | 设置禁用状态 | | setReadonly(readonly) | 设置只读状态 | | setRequired(required) | 设置必填状态 | | setClearable(clearable) | 设置可清除状态 | | setSize(size) | 设置尺寸 | | setPrefix(prefix) | 设置前缀 | | setSuffix(suffix) | 设置后缀 | | getElement() | 获取输入框元素 | | getWrapper() | 获取包装器元素 | | focus() | 聚焦到输入框 | | blur() | 失焦 | | select() | 选择输入框中的文本 | | destroy() | 销毁输入框 |

标签 (Label)

标签组件支持多种类型、尺寸和状态。

属性

| 属性 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | text | string | 'Label' | 标签文本 | | type | string | 'default' | 标签类型 (default, primary, secondary, success, danger, warning, info, light, dark) | | size | string | 'medium' | 标签尺寸 (small, medium, large) | | closable | boolean | false | 是否可关闭 | | rounded | boolean | false | 是否圆角 | | pill | boolean | false | 是否药丸形状 | | icon | string | '' | 图标类名 | | color | string | '' | 自定义颜色 | | backgroundColor | string | '' | 自定义背景颜色 | | borderColor | string | '' | 自定义边框颜色 | | onClick | function | null | 点击事件处理函数 | | onClose | function | null | 关闭事件处理函数 | | container | HTMLElement | document.body | 容器元素 |

方法

| 方法 | 描述 | | --- | --- | | setText(text) | 设置标签文本 | | setType(type) | 设置标签类型 | | setSize(size) | 设置标签尺寸 | | setClosable(closable) | 设置可关闭状态 | | setRounded(rounded) | 设置圆角状态 | | setPill(pill) | 设置药丸形状状态 | | setIcon(icon) | 设置图标 | | setColor(color) | 设置颜色 | | setBackgroundColor(backgroundColor) | 设置背景颜色 | | setBorderColor(borderColor) | 设置边框颜色 | | getElement() | 获取标签元素 | | show() | 显示标签 | | hide() | 隐藏标签 | | toggle(force) | 切换标签显示状态 | | destroy() | 销毁标签 |

图标 (Icon)

图标组件支持多种类型、尺寸和状态。

属性

| 属性 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | name | string | 'icon' | 图标名称 | | type | string | 'svg' | 图标类型 (svg, font, image) | | size | string | 'medium' | 图标尺寸 (xsmall, small, medium, large, xlarge) | | color | string | 'inherit' | 图标颜色 | | spin | boolean | false | 是否旋转 | | pulse | boolean | false | 是否脉冲动画 | | rotate | boolean | false | 是否旋转 180 度 | | flip | boolean | false | 是否翻转 | | flipDirection | string | 'horizontal' | 翻转方向 (horizontal, vertical, both) | | svgPath | string | '' | SVG 图标路径 | | svgViewBox | string | '0 0 24 24' | SVG 图标视图框 | | fontClass | string | '' | 字体图标类名 | | imageSrc | string | '' | 图片图标源 | | alt | string | '' | 图片图标替代文本 | | onClick | function | null | 点击事件处理函数 | | container | HTMLElement | document.body | 容器元素 |

方法

| 方法 | 描述 | | --- | --- | | setName(name) | 设置图标名称 | | setType(type) | 设置图标类型 | | setSize(size) | 设置图标尺寸 | | setColor(color) | 设置图标颜色 | | setSpin(spin) | 设置旋转状态 | | setPulse(pulse) | 设置脉冲状态 | | setRotate(rotate) | 设置旋转 180 度状态 | | setFlip(flip) | 设置翻转状态 | | setFlipDirection(flipDirection) | 设置翻转方向 | | setSvgPath(svgPath) | 设置 SVG 路径 | | setSvgViewBox(svgViewBox) | 设置 SVG 视图框 | | setFontClass(fontClass) | 设置字体图标类名 | | setImageSrc(imageSrc) | 设置图片源 | | setAlt(alt) | 设置替代文本 | | getElement() | 获取图标元素 | | show() | 显示图标 | | hide() | 隐藏图标 | | toggle(force) | 切换图标显示状态 | | destroy() | 销毁图标 |

工具函数

DOM 工具函数

| 函数 | 描述 | | --- | --- | | createElement(tag, attributes, content) | 创建元素 | | querySelector(selector, context) | 查找单个元素 | | querySelectorAll(selector, context) | 查找多个元素 | | addClass(element, className) | 添加类名 | | removeClass(element, className) | 移除类名 | | toggleClass(element, className, force) | 切换类名 | | hasClass(element, className) | 检查类名 | | setStyles(element, styles) | 设置样式 | | getData(element, key) | 获取数据属性 | | setData(element, key, value) | 设置数据属性 | | removeElement(element) | 移除元素 | | emptyElement(element) | 清空元素 | | insertBefore(parent, newElement, referenceElement) | 在参考元素之前插入 | | insertAfter(referenceElement, newElement) | 在参考元素之后插入 | | getOffset(element) | 获取元素偏移量 | | getSize(element) | 获取元素尺寸 |

事件工具函数

| 函数 | 描述 | | --- | --- | | addEvent(element, type, handler, options) | 添加事件监听器 | | removeEvent(element, type, handler) | 移除事件监听器 | | addEventOnce(element, type, handler) | 添加一次性事件监听器 | | dispatchEvent(element, type, data) | 触发自定义事件 | | stopPropagation(event) | 阻止事件冒泡 | | preventDefault(event) | 阻止默认行为 | | stopEvent(event) | 阻止事件冒泡和默认行为 | | delegateEvent(parent, selector, type, handler) | 委托事件处理 | | addEvents(element, eventMap) | 添加多个事件监听器 | | getEventTarget(event) | 获取事件目标 | | getEventTargetBySelector(event, selector) | 获取匹配选择器的事件目标 | | createEventSystem() | 创建事件系统 | | throttle(func, delay) | 节流函数 | | debounce(func, delay) | 防抖函数 |

样式定制

CSS 变量

tm-ui-common 使用 CSS 变量来定义样式，可以通过覆盖这些变量来自定义样式。

:root {
  /* 主题颜色 */
  --primary-color: #007bff;
  --secondary-color: #6c757d;
  --success-color: #28a745;
  --danger-color: #dc3545;
  --warning-color: #ffc107;
  --info-color: #17a2b8;
  --light-color: #f8f9fa;
  --dark-color: #343a40;
  
  /* 字体 */
  --font-family-base: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
  --font-size-base: 1rem;
  
  /* 间距 */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  --spacing-xl: 2rem;
  
  /* 边框 */
  --border-width: 1px;
  --border-radius: 0.25rem;
  
  /* 阴影 */
  --box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);
  
  /* 过渡 */
  --transition-base: all 0.3s ease;
}

暗色主题

[data-theme="dark"] {
  --text-color: #e9ecef;
  --body-bg: #121212;
  --component-bg: #1e1e1e;
  --border-color: #2d2d2d;
}

开发

安装依赖

npm install

开发模式

npm run dev

构建

npm run build

测试

npm test

代码检查

npm run lint

格式化代码

npm run format

浏览器支持

Chrome (最新)
Firefox (最新)
Safari (最新)
Edge (最新)

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

tm-ui-common

特性

安装

快速开始

基本使用

在 HTML 中使用

在 Tampermonkey 脚本中使用

组件

按钮 (Button)

属性

方法

输入框 (Input)

属性

方法

标签 (Label)

属性

方法

图标 (Icon)

属性

方法

工具函数

DOM 工具函数

事件工具函数

样式定制

CSS 变量

暗色主题

开发

安装依赖

开发模式

构建

测试

代码检查

格式化代码

浏览器支持

许可证

贡献