wiston-ui-components

v1.2.3

Published

8 months ago

Wiston UI Components 是一个基于 Web Components 标准的现代 UI 组件库，提供了丰富的交互组件，支持原生 HTML、React、Vue 等多种前端框架。

0High
0Medium
0Low

wiston_huang

Wiston UI Components 使用指南

Wiston UI Components 是一个基于 Web Components 标准的现代 UI 组件库，提供了丰富的交互组件，支持原生 HTML、React、Vue 等多种前端框架。

安装

npm install wiston-ui-components

快速开始

在 HTML 中使用

<!DOCTYPE html>
<html>
<head>
    <script type="module" src="https://unpkg.com/wiston-ui-components/dist/wiston-ui-components.umd.js"></script>
    <link rel="stylesheet" href="https://unpkg.com/wiston-ui-components/dist/style.css">
</head>
<body>
    <wui-button type="primary">Hello World</wui-button>
</body>
</html>

在 React 中使用

import "wiston-ui-components/dist/style.css";
import { defineWUIButton, defineWuiInput, defineWuiSelect, defineWuiDropdown,defineAllComponents } from "wiston-ui-components";
import { useWuiInput, useWuiSelect, useWuiDropdown } from "./hooks/useWebComponent";

// 单独注册组件
defineWUIButton();
defineWuiInput();
defineWuiSelect();
defineWuiDropdown();

// 注册全部可用组件
defineAllComponents();

function App() {
  return (
    <div>
      <wui-button type="primary">Hello World</wui-button>
    </div>
  );
}

组件详解

WUI-Button 按钮组件

基础的按钮组件，支持多种类型和状态。

基础用法

<wui-button>默认按钮</wui-button>
<wui-button type="primary">主要按钮</wui-button>
<wui-button type="success">成功按钮</wui-button>
<wui-button type="warning">警告按钮</wui-button>
<wui-button type="danger">危险按钮</wui-button>
<wui-button type="info">信息按钮</wui-button>

属性

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | type | string | 'default' | 按钮类型：primary/success/warning/danger/info/default | | disabled | boolean | false | 是否禁用 | | loading | boolean | false | 是否显示加载状态 | | size | string | 'default' | 按钮尺寸：small/default/large |

事件

document.querySelector('wui-button').addEventListener('click', (e) => {
  console.log('按钮被点击');
});

WUI-Input 输入框组件

功能丰富的输入框组件，支持多种输入类型和状态。

基础用法

<wui-input type="text" placeholder="请输入文本"></wui-input>
<wui-input type="password" placeholder="请输入密码"></wui-input>
<wui-input type="email" placeholder="请输入邮箱"></wui-input>

清除按钮

<wui-input type="text" placeholder="带清除按钮" clearable></wui-input>

React Hook 用法

const inputRef = useWuiInput({
  onInput: (value, event) => {
    console.log('实时输入:', value);
  },
  onChange: (value, event) => {
    console.log('输入完成:', value);
  },
  onFocus: (event) => {
    console.log('获得焦点');
  },
  onBlur: (event) => {
    console.log('失去焦点');
  }
});

return <wui-input ref={inputRef} type="text" placeholder="请输入内容" />;

属性

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | type | string | 'text' | 输入类型：text/password/email/number等 | | placeholder | string | '' | 占位符文本 | | disabled | boolean | false | 是否禁用 | | clearable | boolean | false | 是否显示清除按钮 | | size | string | 'default' | 输入框尺寸：small/default/large | | value | string | '' | 输入框的值 |

WUI-Select 选择器组件

强大的选择器组件，支持单选、多选、搜索等功能。

单选模式

const selectRef = useWuiSelect({
  options: [
    { label: '选项1', value: '1' },
    { label: '选项2', value: '2' },
    { label: '选项3', value: '3' }
  ],
  placeholder: '请选择',
  value: selectedValue,
  onChange: (value) => {
    setSelectedValue(value);
  }
});

return <wui-select ref={selectRef} />;

多选模式

const multiSelectRef = useWuiSelect({
  options: [
    { label: 'JavaScript', value: 'js' },
    { label: 'TypeScript', value: 'ts' },
    { label: 'Python', value: 'py' }
  ],
  multiple: true,
  placeholder: '请选择编程语言',
  value: selectedValues,
  onChange: (values) => {
    setSelectedValues(values as string[]);
  }
});

return <wui-select ref={multiSelectRef} />;

限制选择数量

const limitedSelectRef = useWuiSelect({
  options: [...],
  multiple: true,
  multipleLimit: 3, // 最多选择3个
  placeholder: '最多选择3个',
  value: selectedValues,
  onChange: (values) => {
    setSelectedValues(values as string[]);
  }
});

带清除按钮

const clearableSelectRef = useWuiSelect({
  options: [...],
  clearable: true,
  placeholder: '可清除的选择器',
  value: selectedValue,
  onChange: (value) => {
    setSelectedValue(value);
  }
});

属性

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | options | Array | [] | 选项列表，格式：[{label: string, value: string}] | | multiple | boolean | false | 是否多选 | | multipleLimit | number | 0 | 多选时的最大选择数量，0表示无限制 | | clearable | boolean | false | 是否显示清除按钮 | | placeholder | string | '请选择' | 占位符文本 | | size | string | 'default' | 选择器尺寸：small/default/large | | disabled | boolean | false | 是否禁用 | | value | string | string[] | null | 当前选中的值 |

WUI-Dropdown 下拉框组件

高级下拉框组件，支持搜索、多选等高级功能。

基础用法

const dropdownRef = useWuiDropdown({
  options: [
    { label: '苹果', value: 'apple' },
    { label: '香蕉', value: 'banana' },
    { label: '橙子', value: 'orange' }
  ],
  placeholder: '请选择水果',
  value: selectedValue,
  onChange: (value) => {
    setSelectedValue(value);
  }
});

return <wui-dropdown ref={dropdownRef} />;

支持搜索

const searchableDropdownRef = useWuiDropdown({
  options: [...],
  searchable: true,
  placeholder: '可搜索的下拉框',
  value: selectedValue,
  onChange: (value) => {
    setSelectedValue(value);
  }
});

多选模式

const multiDropdownRef = useWuiDropdown({
  options: [...],
  multiple: true,
  searchable: true,
  clearable: true,
  maxHeight: '300px',
  placeholder: '多选下拉框',
  value: selectedValues,
  onChange: (values) => {
    setSelectedValues(values as string[]);
  }
});

属性

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | options | Array | [] | 选项列表，格式：[{label: string, value: string}] | | multiple | boolean | false | 是否多选 | | searchable | boolean | false | 是否支持搜索 | | clearable | boolean | false | 是否显示清除按钮 | | placeholder | string | '请选择' | 占位符文本 | | size | string | 'default' | 下拉框尺寸：small/default/large | | disabled | boolean | false | 是否禁用 | | maxHeight | string | '200px' | 下拉菜单最大高度 | | value | string | string[] | null | 当前选中的值 |

WUI-Link 链接组件

美观的链接组件，支持多种样式和状态。

基础用法

<wui-link href="https://example.com">默认链接</wui-link>
<wui-link href="https://example.com" color="primary">主要链接</wui-link>
<wui-link href="https://example.com" color="danger">危险链接</wui-link>

属性

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | href | string | '' | 链接地址 | | color | string | 'default' | 链接颜色：primary/danger/default | | size | string | 'default' | 链接尺寸：small/default/large | | underline | boolean | false | 是否显示下划线 | | disabled | boolean | false | 是否禁用 | | target | string | '_self' | 链接打开方式：_self/_blank |

React Hooks

为了更好地在 React 中使用组件，我们提供了专用的 Hooks：

useWuiInput

import { useWuiInput } from './hooks/useWebComponent';

const inputRef = useWuiInput({
  onInput: (value, event) => { /* 实时输入回调 */ },
  onChange: (value, event) => { /* 输入完成回调 */ },
  onFocus: (event) => { /* 获得焦点回调 */ },
  onBlur: (event) => { /* 失去焦点回调 */ },
  onKeyDown: (event) => { /* 按键回调 */ }
});

useWuiSelect

import { useWuiSelect } from './hooks/useWebComponent';

const selectRef = useWuiSelect({
  options: Array<{label: string, value: string}>,
  onChange?: (value: string | string[], event: Event) => void,
  size?: string,
  placeholder?: string,
  disabled?: boolean,
  multiple?: boolean,
  clearable?: boolean,
  multipleLimit?: number,
  value?: string | string[]
});

useWuiDropdown

import { useWuiDropdown } from './hooks/useWebComponent';

const dropdownRef = useWuiDropdown({
  options: Array<{label: string, value: string}>,
  onChange?: (value: string | string[], event: Event) => void,
  size?: string,
  placeholder?: string,
  disabled?: boolean,
  multiple?: boolean,
  searchable?: boolean,
  clearable?: boolean,
  maxHeight?: string,
  value?: string | string[]
});

样式自定义

CSS 变量

组件支持通过 CSS 变量进行样式自定义：

:root {
  --wui-primary-color: #3b82f6;
  --wui-success-color: #10b981;
  --wui-warning-color: #f59e0b;
  --wui-danger-color: #ef4444;
  --wui-border-radius: 6px;
  --wui-font-size: 14px;
}

事件处理

原生事件

所有组件都支持标准的 DOM 事件：

document.querySelector('wui-button').addEventListener('click', (e) => {
  console.log('按钮被点击');
});

document.querySelector('wui-input').addEventListener('input', (e) => {
  console.log('输入值:', e.target.value);
});

自定义事件

选择器和下拉框组件会触发自定义的 change 事件：

document.querySelector('wui-select').addEventListener('change', (e) => {
  console.log('选中值:', e.detail.value);
});

注意事项

组件注册：在使用组件前需要先注册对应的组件定义
样式引入：记得引入 CSS 样式文件
事件绑定：在 React 中建议使用提供的 Hooks 来处理事件
属性设置：布尔属性可以直接写属性名，如 <wui-input clearable />
数据格式：选择器组件的 options 必须是 {label: string, value: string} 格式的数组

浏览器支持

Chrome 54+
Firefox 63+
Safari 10.1+
Edge 79+

支持所有现代浏览器，需要 Web Components 标准支持。

问题反馈

如果您在使用过程中遇到问题，请提交 issue 或联系开发团队。

更多示例和详细文档请参考项目中的 example 目录。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Wiston UI Components 使用指南

安装

快速开始

在 HTML 中使用

在 React 中使用

组件详解

WUI-Button 按钮组件

基础用法

属性

事件

WUI-Input 输入框组件

基础用法

清除按钮

React Hook 用法

属性

WUI-Select 选择器组件

单选模式

多选模式

限制选择数量

带清除按钮

属性

WUI-Dropdown 下拉框组件

基础用法

支持搜索

多选模式

属性

WUI-Link 链接组件

基础用法

属性

React Hooks

useWuiInput

useWuiSelect

useWuiDropdown

样式自定义

CSS 变量

事件处理

原生事件

自定义事件

注意事项

浏览器支持

问题反馈