tm-ui-common
Version:
A reusable UI component library for Tampermonkey scripts
480 lines (396 loc) • 13.6 kB
Markdown
# tm-ui-common
一个为 Tampermonkey 脚本设计的可重用 UI 组件库。
## 特性
- 📦 轻量级 - 无依赖，纯 JavaScript 实现
- 🎨 可定制 - 丰富的样式选项和主题支持
- 📱 响应式 - 适配不同屏幕尺寸
- ♿ 可访问性 - 遵循 WCAG 标准
- 🧪 测试覆盖 - 完整的单元测试
## 安装
```bash
npm install tm-ui-common
```
## 快速开始
### 基本使用
```javascript
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 中使用
```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 脚本中使用
```javascript
// ==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 变量来定义样式，可以通过覆盖这些变量来自定义样式。
```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;
}
```
### 暗色主题
```css
[data-theme="dark"] {
--text-color: #e9ecef;
--body-bg: #121212;
--component-bg: #1e1e1e;
--border-color: #2d2d2d;
}
```
## 开发
### 安装依赖
```bash
npm install
```
### 开发模式
```bash
npm run dev
```
### 构建
```bash
npm run build
```
### 测试
```bash
npm test
```
### 代码检查
```bash
npm run lint
```
### 格式化代码
```bash
npm run format
```
## 浏览器支持
- Chrome (最新)
- Firefox (最新)
- Safari (最新)
- Edge (最新)
## 许可证
MIT
## 贡献
欢迎提交 Issue 和 Pull Request。