TerminalDesktop 组件库说明文档

介绍

本组件库旨在提供一套基于Vant，简单、易用的组件，用于构建终端应用。它提供有一些列快速连接API的方法。

启动示例

控制台运行：npm run serve

启动后浏览器打开：http://localhost:5008

开始使用

1. 安装依赖

TerminalDesktop 将 Vant、Axios、@vant/use 和 @vant/popperjs 作为对等依赖（peer dependencies），需要先安装：

npm install vant axios @vant/use @vant/popperjs --save
# 或
yarn add vant axios @vant/use @vant/popperjs

2. 引入插件

import { Terminaldesktop } from 'terminaldesktop'

// 在 Vue 中引入插件，并可传入配置项
app.use(Terminaldesktop, { request: { baseURL: "/api" } })

// 引入样式
import 'terminaldesktop/dist/package/index.css'

如果是在uniapp中使用

如果你是在uniapp中使用此框架，并且需要适配小程序和app，你需要做一下axios的适配。

首先安装axios-adapter-uniapp适配工具： npm i axios-adapter-uniapp --save

然后在request配置文件中使用axios-adapter-uniapp适配器。

import axiosAdapterUniapp from 'axios-adapter-uniapp'

export default {
    // baseURL: "http://localhost",
    // 注意下面这行代码用于应用axios-adapter-uniapp适配器
    adapter: axiosAdapterUniapp,
}

常用工具方法：

可通过'terminaldesktop'解包导入以下方法或者对象。import { version } from 'terminaldesktop'

config对象

配置项，可在插件传入配置项覆盖默认配置。包含有：

• function get(configType, path, customConfig) 查找获取配置项。
• config.final.request 获取请求配置。
• version() 获取当前版本号。
• tool对象 包含常用工具方法。
• function createTerminalApp(component, rootProps = undefined, configs = {}) 用于创建终端应用。
• function requestApi(options) 数据请求方法，服务器前缀可配置{ request: { baseURL:"http://api/" } }

使用本地配置

我们提供了本地配置支持，你可创建好config文件之后，在Vue引入插件时同时进行注入：

import { Terminaldesktop } from 'terminaldesktop'
import request from 'local/config/request.config.js'
import response from 'local/config/response.config.js'
import runtimeConfig from './local/runtime.config.js'

app.use( Terminaldesktop ,{ configs:{ request: request,response: response,runtime: runtimeConfig }})

常见问题

可利用axios的transformRequest配置项，在请求时验证和加入token。在request全局配置中进行配置：

transformRequest: [function(data, headers) {
    const token = '请求token';
    headers["Authorization"] = token || '';
    return JSON.stringify(data);
}]

更多用法可查看axios配置项transformRequest的相关文档。

原因：TerminalDesktop 将 Vant 和 Axios 作为对等依赖（peer dependencies），未打包进库本身，需要用户项目自行安装。

解决方案：在项目根目录执行以下命令安装依赖：

npm install vant axios @vant/use --save
# 或
yarn add vant axios @vant/use

安装完成后重新运行构建命令即可。

原因：Vant 4.x 版本将工具函数提取到了单独的 @vant/use 包中，需要单独安装。

解决方案：安装 @vant/use 依赖：

npm install @vant/use --save
# 或
yarn add @vant/use

原因：Vant 4.x 版本的 Popover 组件依赖 @vant/popperjs 包，需要单独安装。

解决方案：安装 @vant/popperjs 依赖：

npm install @vant/popperjs --save
# 或
yarn add @vant/popperjs

组件目录结构

src/components/
├── button/           # 按钮相关组件
├── container/        # 容器相关组件
├── data/             # 数据展示相关组件
├── elements/         # 基础元素组件
├── form/             # 表单相关组件
├── lib/              # 基础库和工具
├── others/           # 其他组件
└── scene/            # 场景相关组件

组件分类说明

1. 按钮组件 (button/)

提供了多种功能按钮，支持 API 调用、确认对话框、抽屉弹出等功能。

2. 容器组件 (container/)

提供了布局和容器相关组件，如按钮组、卡片、导航栏等。

3. 数据组件 (data/)

提供了数据展示和处理组件，如数据列表、分页加载等。

4. 基础元素组件 (elements/)

提供了基础 UI 元素，如提示信息、工具提示等。

5. 表单组件 (form/)

提供了丰富的表单控件，如自动完成、复选框、单选框、选择器、开关、上传组件等。

6. 基础库 (lib/)

提供了组件库的基础功能，如 API 请求能力、可中断操作等。

7. 其他组件 (others/)

提供了其他辅助组件，如请求组件等。

8. 场景组件 (scene/)

提供了特定场景下的组件，如搜索栏、导航等。

组件详细介绍

按钮组件

ApiButton

• 功能：支持 API 调用的按钮组件
• 特性：自动处理加载状态、支持 API 请求前后的事件回调
• 使用场景：需要点击按钮触发 API 请求的场景
• Props：
  • api：API 地址，默认值为当前页面 URL
  • apiMethod：API 请求方法，默认值为 "get"，支持 "get", "post", "put", "delete"
  • apiParam：API 请求参数，默认值为 {}
  • active：是否激活 API 请求，默认值为 false
  • requestConfig：请求配置，默认值为 {}
  • responseConfig：响应配置，默认值为 {}
  • loading：是否显示加载状态，默认值为 true
• Events：
  • apiBefore：API 请求前触发
  • apiAfter：API 请求后触发
  • apiSuccess：API 请求成功触发
  • apiFail：API 请求失败触发
  • apiException：API 请求异常触发

ConfirmButton

• 功能：带确认对话框的按钮组件
• 特性：点击按钮后弹出确认对话框，确认后执行操作
• 使用场景：需要用户确认后执行的操作，如删除、提交等
• Props：
  • title：对话框标题，默认值为 undefined
  • width：对话框宽度，默认值为 '320px'
  • message：对话框内容，默认值为 '该操作需要再次确认，是否确定？'
  • messageAlign：对话框内容对齐方式，默认值为 'center'
  • theme：对话框主题，默认值为 'default'
  • confirmButtonText：确认按钮文本，默认值为 '确认'
  • confirmButtonColor：确认按钮颜色，默认值为 '#ee0a24'
  • cancelButtonText：取消按钮文本，默认值为 '取消'
  • cancelButtonColor：取消按钮颜色，默认值为 'black'
  • lockScroll：是否锁定背景滚动，默认值为 true
  • allowHtml：是否允许对话框内容使用 HTML，默认值为 false

DrawerButton

• 功能：带抽屉弹出的按钮组件
• 特性：点击按钮后弹出抽屉，可在抽屉中展示内容
• 使用场景：需要在抽屉中展示详细信息或表单的场景
• Props：
  • drawerRound：抽屉是否圆角，默认值为 false
• Events：
  • 无特定事件，继承自 van-button 和 van-popup 的事件
• Expose：
  • close()：关闭抽屉
  • open()：打开抽屉
• 插槽：
  • default：抽屉内容

PromptButton

• 功能：带表单弹窗的按钮组件
• 特性：点击按钮后弹出带表单的对话框，收集用户输入后提交 API
• 使用场景：需要用户输入信息后执行操作的场景
• Props：
  • showCancelButton：是否显示取消按钮，默认值为 true
  • showConfirmButton：是否显示确认按钮，默认值为 true
  • apiParam：API 请求参数，默认值为 {}
• Events：
  • confirm：点击确认按钮时触发
• 插槽：
  • default：弹窗内容，通常为表单

容器组件

ButtonGroup

• 功能：按钮组容器
• 特性：将多个按钮组合在一起，提供统一的样式
• 使用场景：需要展示一组相关按钮的场景
• Props：无
• Events：无

Card

• 功能：卡片组件，支持内容展开/收起
• 特性：可折叠的卡片，方便展示和隐藏内容
• 使用场景：需要展示可折叠内容的场景
• Props：
  • type：卡片类型，默认值为 ""
• Events：无
• 插槽：
  • title：卡片标题
  • default：卡片内容

NavigatorBar

• 功能：导航栏组件
• 特性：固定在顶部的导航栏，支持标题、左侧返回按钮和右侧操作按钮
• 使用场景：应用的页面导航h
• Props：
  • title：导航栏标题，默认值为 ""
  • shadow：是否显示导航栏阴影，默认值为 true
• Events：
  • click-left：点击左侧返回按钮时触发
• 插槽：
  • title：导航栏标题
  • left：左侧按钮
  • right：右侧按钮

数据组件

DataList

• 功能：数据列表组件，支持下拉刷新和分页加载
• 特性：自动处理数据加载、分页、空状态等
• 使用场景：需要展示列表数据的场景，如商品列表、订单列表等
• Props：
  • api：API 地址，默认值为当前页面 URL
  • apiMethod：API 请求方法，默认值为 "get"，支持 "get", "post", "put", "delete"
  • apiParam：API 请求参数，默认值为 {}
  • active：是否激活 API 请求，默认值为 false
  • requestConfig：请求配置，默认值为 {}
  • responseConfig：响应配置，默认值为 {}
  • pullRefresh：是否开启下拉刷新，默认值为 true
  • pullRefreshAttrs：下拉刷新属性，默认值为 {}
  • emptyText：空状态文本，默认值为 "暂无相关信息"
  • pagerMode：分页模式，默认值为 "click"，支持 "scroll", "click"
  • pagerText：分页按钮文本，默认值为 "点击查看更多"
  • pagerClass：分页按钮类名，默认值为 ""
  • loadingText：加载中文本，默认值为 "加载中..."
  • offset：滚动触发加载的偏移量，默认值为 300
  • dataBind：数据绑定方法，默认值为返回原始数据的函数
• Events：
  • apiBefore：API 请求前触发
  • apiAfter：API 请求后触发
  • apiSuccess：API 请求成功触发
  • apiFail：API 请求失败触发
  • apiException：API 请求异常触发
  • load：加载更多数据时触发
  • refresh：下拉刷新时触发
• Expose：
  • requestApi()：手动触发 API 请求
• 插槽：
  • default：列表内容，接收 list 和 loading 参数
  • empty：空状态内容
  • loading：加载状态内容
  • pager：分页按钮内容

基础元素组件

Tips

• 功能：提示信息组件
• 特性：提供两种模式：普通提示和带弹窗的提示
• 使用场景：需要展示提示信息的场景
• Props：
  • type：提示类型，默认值为 "tips"，支持 "tips", "box"
• Events：无
• 插槽：
  • default：提示内容

Tooltip

• 功能：工具提示组件
• 特性：支持鼠标悬停或点击触发，可自定义位置和内容
• 使用场景：需要为元素添加额外说明的场景
• Props：
  • trigger：触发方式，默认值为 "hover"，支持 "hover", "click"
  • placement：提示框位置，默认值为 "bottom"，支持 "top", "bottom", "left", "right"
  • showDelay：显示延迟时间，默认值为 0
  • hideDelay：隐藏延迟时间，默认值为 200
  • disabled：是否禁用提示框，默认值为 false
  • always：是否总是显示提示框，默认值为 false
• Events：无
• 插槽：
  • default：触发元素
  • content：提示内容

表单组件

Autocomplete

• 功能：自动完成组件，根据输入关键词搜索数据
• 特性：支持 API 调用获取数据，提供下拉选择
• 使用场景：需要根据用户输入提供建议的场景，如搜索框、地址输入等
• Props：
  • api：API 地址，默认值为当前页面 URL
  • apiMethod：API 请求方法，默认值为 "get"，支持 "get", "post", "put", "delete"
  • apiParam：API 请求参数，默认值为 {}
  • active：是否激活 API 请求，默认值为 false
  • requestConfig：请求配置，默认值为 {}
  • responseConfig：响应配置，默认值为 {}
  • title：弹窗标题，默认值为 ""
  • tips：提示信息，默认值为 ""
  • itemClass：选项类名，默认值为 ""
  • emptyText：空状态文本，默认值为 "暂无相关数据"
  • placeholder：输入框占位符，默认值为 ""
  • interval：搜索间隔时间，默认值为 1000
  • paramName：搜索参数名，默认值为 "keyword"
  • loading：是否显示加载状态，默认值为 true
  • responseTips：是否显示响应提示，默认值为 false
  • height：弹窗高度，默认值为 "80%"
  • icon：输入框图标，默认值为 "search"
  • clickClose：点击选项后是否关闭弹窗，默认值为 true
• Events：
  • apiBefore：API 请求前触发
  • apiAfter：API 请求后触发
  • apiSuccess：API 请求成功触发
  • apiFail：API 请求失败触发
  • apiException：API 请求异常触发
  • change：选择选项后触发
• Expose：
  • setInputValue(val)：手动设置输入框的值
• 插槽：
  • value：选项内容，接收 value 参数

CheckboxList

• 功能：复选框列表组件
• 特性：支持从 API 获取选项数据，可自定义选项展示
• 使用场景：需要用户选择多个选项的场景
• Props：
  • api：API 地址，默认值为当前页面 URL
  • apiMethod：API 请求方法，默认值为 "get"，支持 "get", "post", "put", "delete"
  • apiParam：API 请求参数，默认值为 {}
  • active：是否激活 API 请求，默认值为 false
  • requestConfig：请求配置，默认值为 {}
  • responseConfig：响应配置，默认值为 {}
  • textPropName：选项文本属性名，默认值为 "text"
  • valuePropName：选项值属性名，默认值为 "value"
  • square：复选框形状，默认值为 "square"
  • button：是否以按钮形式显示，默认值为 false
• Events：
  • apiBefore：API 请求前触发
  • apiAfter：API 请求后触发
  • apiSuccess：API 请求成功触发
  • apiFail：API 请求失败触发
  • apiException：API 请求异常触发
  • bind：数据绑定完成后触发
• 插槽：
  • default：选项内容，接收 item 参数

RadioList

• 功能：单选框列表组件
• 特性：支持从 API 获取选项数据，可自定义选项展示
• 使用场景：需要用户从多个选项中选择一个的场景
• Props：
  • api：API 地址，默认值为当前页面 URL
  • apiMethod：API 请求方法，默认值为 "get"，支持 "get", "post", "put", "delete"
  • apiParam：API 请求参数，默认值为 {}
  • active：是否激活 API 请求，默认值为 false
  • requestConfig：请求配置，默认值为 {}
  • responseConfig：响应配置，默认值为 {}
  • textPropName：选项文本属性名，默认值为 "text"
  • valuePropName：选项值属性名，默认值为 "value"
  • button：是否以按钮形式显示，默认值为 false
• Events：
  • apiBefore：API 请求前触发
  • apiAfter：API 请求后触发
  • apiSuccess：API 请求成功触发
  • apiFail：API 请求失败触发
  • apiException：API 请求异常触发
  • bind：数据绑定完成后触发
• 插槽：
  • default：选项内容，接收 item 参数

Select

• 功能：下拉选择器组件
• 特性：支持单选和多选，可从 API 获取选项数据
• 使用场景：需要用户从下拉列表中选择选项的场景
• Props：
  • api：API 地址，默认值为当前页面 URL
  • apiMethod：API 请求方法，默认值为 "get"，支持 "get", "post", "put", "delete"
  • apiParam：API 请求参数，默认值为 {}
  • active：是否激活 API 请求，默认值为 false
  • requestConfig：请求配置，默认值为 {}
  • responseConfig：响应配置，默认值为 {}
  • placeholder：输入框占位符，默认值为 "点击进行选择"
  • title：弹窗标题，默认值为 ""
  • position：弹窗位置，默认值为 "bottom"
  • destroyOnClose：关闭时是否销毁弹窗，默认值为 true
  • round：是否圆角，默认值为 true
  • requestTiming：请求时机，默认值为 "click"，支持 "beforeMount", "click"
  • multiple：是否支持多选，默认值为 false
  • height：弹窗高度，默认值为 "auto"
  • removeAble：是否可移除已选项，默认值为 true
  • share：共享选项的标识，默认值为 ''
• Events：
  • apiBefore：API 请求前触发
  • apiAfter：API 请求后触发
  • apiSuccess：API 请求成功触发
  • apiFail：API 请求失败触发
  • apiException：API 请求异常触发
  • click：点击选择器时触发
  • cancel：取消选择时触发
  • confirm：确认选择时触发
  • open：弹窗打开时触发
  • closed：弹窗关闭时触发
  • selectAll：全选时触发
• 插槽：
  • default：选项内容，接收 item 参数
  • empty：空状态内容

Switch

• 功能：开关组件
• 特性：支持 API 调用，可自定义激活和非激活值
• 使用场景：需要用户切换状态的场景，如启用/禁用功能
• Props：
  • api：API 地址，默认值为当前页面 URL
  • apiMethod：API 请求方法，默认值为 "get"，支持 "get", "post", "put", "delete"
  • apiParam：API 请求参数，默认值为 {}
  • active：是否激活 API 请求，默认值为 false
  • requestConfig：请求配置，默认值为 {}
  • responseConfig：响应配置，默认值为 {}
  • activeValue：激活状态的值，默认值为 true
  • inactiveValue：非激活状态的值，默认值为 false
  • paramName：参数名，默认值为 "param"
• Events：
  • apiBefore：API 请求前触发
  • apiAfter：API 请求后触发
  • apiSuccess：API 请求成功触发
  • apiFail：API 请求失败触发
  • apiException：API 请求异常触发
  • change：开关状态改变时触发

Uploader

• 功能：文件上传组件
• 特性：支持多文件上传、自动提交到服务器、删除文件等
• 使用场景：需要用户上传文件的场景
• Props：
  • api：上传 API 地址，必填
  • apiMethod：上传 API 请求方法，默认值为 "post"，支持 "post", "put"
  • apiParam：上传 API 请求参数，默认值为 {}
  • fileFormName：文件表单名，默认值为 "file"
  • deleteApi：删除文件 API 地址
  • deleteApiMethod：删除文件 API 请求方法，默认值为 "post"
  • deletable：是否可删除文件，默认值为 true
  • deleteParamName：删除文件参数名，默认值为 "deleteParam"
• Events：
  • uploadSuccess：文件上传成功触发
  • uploadFail：文件上传失败触发
  • uploadException：文件上传异常触发
  • uploaded：文件上传完成触发
  • deleteSuccess：文件删除成功触发
  • deleteFail：文件删除失败触发
  • deleteException：文件删除异常触发
  • deleteBefore：文件删除前触发
• Expose：
  • closeImagePreview()：关闭图片预览
  • chooseFile()：选择文件
  • reuploadFile(index)：重新上传文件
• 插槽：
  • default：自定义上传按钮
  • preview：自定义文件预览

基础库

ApiAble.js

• 功能：API 请求能力的基础库
• 特性：定义了 API 请求相关的属性和事件
• 使用场景：为组件提供 API 请求能力
• 导出内容：
  • ApiAbleProps：API 请求相关的属性定义
  • ApiEvents：API 请求相关的事件定义
• Props：
  • api：API 地址，默认值为当前页面 URL
  • apiMethod：API 请求方法，默认值为 "get"，支持 "get", "post", "put", "delete"
  • apiParam：API 请求参数，默认值为 {}
  • active：是否激活 API 请求，默认值为 false
  • requestConfig：请求配置，默认值为 {}
  • responseConfig：响应配置，默认值为 {}
• Events：
  • apiBefore：API 请求前触发
  • apiAfter：API 请求后触发
  • apiSuccess：API 请求成功触发
  • apiFail：API 请求失败触发
  • apiException：API 请求异常触发

AbortAble.js

• 功能：可中断操作的基础库
• 特性：提供操作中断的能力，允许用户在操作执行前取消
• 使用场景：需要支持用户取消操作的场景
• 方法：
  • abortFn()：中断操作的函数
  • abortChecker(action, abort)：检查是否中断操作的函数，action 为未中断时执行的函数，abort 为中断时执行的函数

NavigatorBarStore.js

• 功能：导航栏状态管理
• 特性：管理导航栏的标题、按钮等状态
• 使用场景：全局导航栏状态管理
• 状态：
  • title：导航栏标题

Symbols.js

• 功能：组件间通信的符号定义
• 特性：定义了用于组件间通信的符号
• 使用场景：组件间的通信
• 符号：
  • SearchBar：搜索栏组件的符号
  • SearchBarReset：搜索栏重置的符号

其他组件

Requester

• 功能：API 请求组件
• 特性：封装了 API 请求的逻辑，提供统一的请求处理
• 使用场景：需要在组件中执行 API 请求的场景
• Props：
  • api：API 地址，默认值为当前页面 URL
  • apiMethod：API 请求方法，默认值为 "get"，支持 "get", "post", "put", "delete"
  • apiParam：API 请求参数，默认值为 {}
  • active：是否激活 API 请求，默认值为 false
  • requestConfig：请求配置，默认值为 {}
  • responseConfig：响应配置，默认值为 {}
• Events：
  • apiBefore：API 请求前触发
  • apiAfter：API 请求后触发
  • apiSuccess：API 请求成功触发
  • apiFail：API 请求失败触发
  • apiException：API 请求异常触发
• Expose：
  • requestApi()：手动触发 API 请求

场景组件

SearchBar

• 功能：搜索栏组件
• 特性：提供搜索功能和重置功能
• 使用场景：需要用户输入搜索条件的场景
• Props：无
• Events：
  • reset：点击重置按钮时触发

SearchBarItem

• 功能：搜索栏项组件
• 特性：用于在搜索栏中显示一个选择项
• 使用场景：搜索栏中的选项展示
• Props：
  • initData：初始数据，默认值为 undefined
  • icon：图标名称，默认值为 ""
  • filteIcon：过滤状态的图标名称，默认值为 ""
  • label：标签文本，默认值为 ""
  • type：类型，默认值为 "popup"，支持 "popup", "popover"
  • height：弹窗高度，默认值为 "50%"
  • title：弹窗标题，默认值为 ""
  • tips：提示信息，默认值为 ""
  • prop：属性名，默认值为 ""
• Events：
  • reset：点击重置按钮时触发
• Expose：
  • reset()：重置方法
  • isEmpty：是否为空的计算属性
• 插槽：
  • default：弹窗内容，接收 value 和 differents 参数
  • value：搜索栏中显示的选中值，接收 value 和 differents 参数

Navigator

• 功能：导航组件
• 特性：提供应用的导航功能
• 使用场景：应用的导航菜单
• Props：
  • type：类型，默认值为 ""
  • list：导航项列表，默认值为 []

使用示例

ApiButton 使用示例

<template>
  <TdApiButton api="/api/submit" api-method="post" api-param="{id: 1}">
    提交
  </TdApiButton>
</template>

<script setup>
import TdApiButton from '@/components/button/ApiButton.vue'
</script>

DataList 使用示例

<template>
  <TdDataList api="/api/list" v-model="list">
    <template #default="{ list }">
      <div v-for="item in list" :key="item.id">
        {{ item.name }}
      </div>
    </template>
  </TdDataList>
</template>

<script setup>
import TdDataList from '@/components/data/DataList.vue'
import { ref } from 'vue'

const list = ref([])
</script>

Select 使用示例

<template>
  <TdSelect v-model="value" api="/api/options" placeholder="请选择">
  </TdSelect>
</template>

<script setup>
import TdSelect from '@/components/form/Select.vue'
import { ref } from 'vue'

const value = ref('')
</script>

依赖说明

• Vue 3：组件库基于 Vue 3 开发
• Vant：使用 Vant 作为基础 UI 组件库
• Lodash：用于工具函数
• Axios：用于网络请求

开发说明

1. 组件命名规范：使用 Td 前缀，如 TdApiButton
2. 组件文件结构：按照功能分类存放
3. 组件通信：使用 Vue 3 的 Composition API 和 provide/inject
4. API 请求：统一使用 Requester 组件处理

更新日志

• 1.0.57 修复了TdDatalist中存在的问题。
• 1.0.41 修复了TdDatalist存在的分页与重新请求数据加载方式问题。
• 1.0.35 增加adapter文件夹的输出，uniapp用户可复制使用适配文件。修复部分bug。
• 1.0.34 增加了对uniapp的支持：requestApi（axios）适配；提示组件的适配。增加dist/config文件输出。
• 1.0.32 修复TdDatalist存在的问题。修复TdNavigatorBar存在的样式问题。优化requestApi请求方法。
• 1.0.26 增加NavigatorBar支持RouterView方式，由子页面控制。
• 1.0.0 初始版本。

贡献指南

欢迎提交 Issue 和 Pull Request 来改进组件库。

许可证

MIT License