Web UIKit

最近更新时间:2026-05-06 17:29:22

我的收藏

简介

SMH Web UI Kit​ 是一款基于 React 的开箱即用云盘 UI 组件库。它深度对接腾讯云 SMH(智能媒体托管)服务,开发者仅需传入基础配置与 Token 获取函数,即可在现有应用中快速集成完整的网盘功能,免去从零搭建文件管理前端的繁琐工作。

功能介绍

核心能力

浏览与导航:支持分页加载的文件/文件夹浏览。
上传能力:集成分片上传、断点续传、秒传检测及实时进度回调。
下载:支持浏览器原生下载。
操作:支持新建文件夹、移动、复制及重命名。
空间管理:实时展示存储空间配额与使用量。
安全删除:默认进入回收站,支持删除与恢复。

高级特性

多维搜索:支持按关键字、文件类型、后缀、大小及时间范围筛选。
全格式预览:支持图片、音视频播放器,支持文档及 Markdown 渲染。
分享与协作:生成临时访问链接,便捷分享文件。
批量处理:支持框选、Shift 多选及批量下载/删除操作。

双模式 UI 适配

操作
Full 完整模式
Compact 简洁模式
设计理念
流动蓝图,功能完备
传统列表,轻量紧凑
适用场景
独立云盘页面
嵌入 Drawer / 侧栏 / 弹窗
视图模式
表格 / 网格双视图切换
仅表格视图
批量操作
✅ 框选 + 快捷键选择
-
排序控件
-
分享功能
-
媒体预览
✅ 支持视频/音频/Markdown
-
上传面板
✅ 支持队列/速度/耗时
-
回收站
-
重命名交互
弹窗式
行内编辑

注意事项

librarySecret 绝不能暴露给前端,token 的生成必须由后端完成。
getAccessToken 函数引用需保持稳定,建议 useCallback 在组件外部使用包裹或定义,避免不必要的重新初始化。
组件调用时调用 clearConfig() ,清理内部状态(包括所有 token 空间和客户端缓存),防止内存泄漏和状态浪费。
expiresAt 多种时间格式:每秒计时器、秒级计时器、ISO 8601字符串、Date 对象,SDK 内部会自动统一转换。
组件默认占满父容器的 100% 高度,请确保父容器有合适的高度约束。
切换空间时,SDK 内部会根据 spaceId 自动管理 Token 和客户端状态。如需强制刷新某个空间的 Token,可使用 clearSpaceCache(spaceId)

准备工作

在接入之前,您需要准备以下内容:

1. 准备腾讯云 SMH 资源

您需要登录 腾讯云 SMH 控制台 完成媒体库创建后获取如下信息:
参数
说明
示例
basePath
SMH API 地址
https://smhxxxxxxx.api.tencentsmh.cn
libraryId
媒体库 ID
Smhxxxxxxxxxxxxx
librarySecret
媒体库密钥(仅后端持有
your_secret
spaceId
空间 ID(业务方通过 创建空间 API 获取)
spacexxxxx
说明:
创建媒体库时有租户模式和媒体类型选项,请依据业务实际使用进行选择,如网盘业务可以选择多租户模式+文件媒体库类型

2. 开发者自行实现签发 Token 接口

UI Kit 在前端通过 smh-js-sdk 直连 腾讯云 SMH API 完成所有文件操作(上传、下载、删除等)。每次请求都需要携带一个 accessToken 作为身份凭证。但签发 Token 需要 librarySecret(媒体库密钥),密钥绝不能暴露给客户端。因此必须由您的后端持有密钥,调用 SMH API 签发 Token,再返回给前端使用。node 服务端示例如下:
const express = require('express');
const app = express();
app.use(express.json())

app.post('/api/generate-space-token', async (req, res) => {
const { spaceId } = req.body;

// 调用 SMH API 签发 token
const params = new URLSearchParams({
library_id: libraryId, // libraryId 替换为真实的 libraryId
library_secret: librarySecret, // ⚠️ 仅后端持有, librarySecret 替换为真实的 librarySecret
Grant: 'space_admin', // 签发给前端使用的权限推荐为本空间内最大权限
Period: '7200', // 过期时间 2 小时
spaceId, // 空间id
});
const response = await fetch(`${basePath}/api/v1/token?${params}`); // basePath 替换为真实的 basePath
const tokenData = await response.json();

res.json({
accessToken: tokenData.accessToken,
expiresAt: Date.now() + 2 * 60 * 60 * 1000, // 毫秒级时间戳
});
});


app.listen(3000, () => {
console.log(`server running at http://localhost:3000`);
});

3. 执行以下命令,安装客户端依赖

npm install smh-web-uikit
说明:
smh-web-uikit 目前仅支持 react 项目, 如需使用组件方式则宿主项目需自行安装 react、react-dom(^16.0.0)。
安装方式:在宿主项目的 package.json 中增加 react、react-dom 依赖项后执行 npm i

开始接入

方式一:使用组件(推荐)

react 应用启动后, 直接引入组件使用

import { SpaceDrive } from 'smh-web-uikit' // 引入主组件
import 'smh-web-uikit/dist/style.css' // 引入样式变量

function App() {
// accessToken 提供函数(详见下方说明)
const getAccessToken = async (spaceId = 'your-space-id') => {
// 这里替换为 开发者自行实现签发 Token 接口
const res = await fetch('http://localhost:3000/api/get-smh-token', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ spaceId }),
})
const data = await res.json()
return {
accessToken: data.accessToken,
expiresAt: data.expiresAt, // 支持:毫秒时间戳、秒级时间戳、ISO 8601 字符串(含纳秒精度)
}
}

return (
<SpaceDrive
basePath="https://api.tencentsmh.cn"
libraryId="smhxxx-xxxxx"
spaceId="space-xxxxx"
getAccessToken={getAccessToken}
/>
)
}
export default App;

组件参数说明

参数
描述
类型
是否必填
basePath
SMH API 地址
string
libraryId
媒体库 ID
string
spaceId
空间 ID
string
getAccessToken
Token 提供函数
() => Promise<{ accessToken, expiresAt }>
uiMode
UI 模式, 默认值 'Full'
'full' | 'compact'
enableSearch
启用搜索, 默认值 'false'
boolean
enableRecycleBin
启用回收站, 默认值 'false'
boolean
title
顶部标题文字, 默认值 '云盘'
string

方式二:仅使用服务层(自定义 UI)

如果您需要完全自定义 UI,或使用 Vue / Angular 等其他框架,可以跳过组件,直接调用服务层 API。操作步骤如下:
1. 使用如下命令进行初始化配置。
import { setSmhConfig, initToken, clearConfig } from 'smh-web-uikit';

setSmhConfig({
basePath: 'https://smhxxxxxxx.api.tencentsmh.cn', // 需要替换为真实的basePath
libraryId: 'Smhxxxxxxxxxxxxx', // 需要替换为真实的libraryId
spaceId: 'spacexxxxx', // 需要替换为真实的spaceId
getAccessToken: async () => {
const res = await fetch('http://localhost:3000/api/get-smh-token', { // 需要替换为真实的请求地址
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ spaceId: 'spacexxxxx' }),// 需要替换为真实的spaceId
});
const data = await res.json();
return { accessToken: data.accessToken, expiresAt: data.expiresAt };
},
// 可选:自定义错误提示
onError: ({ message }) => console.error('[SMH]', message),
});

// 在 async 函数中调用
async function initialize() {
await initToken();
}
initialize();
2. 使用如下命令进行 API 调用。

import {
getFileList,
uploadFile,
delFile,
delDirectory,
createDirectory,
moveFile,
moveDirectory,
renameFile,
renameDirectory,
getPreview,
getDocPreviewUrl,
downloadFile,
getFileInfo,
getFilePreviewUrlOrContent,
getSpaceUsage,
searchFiles,
resetClient,
// 回收站
getRecycleList,
recycleRestore,
recycleRestoreBatch,
recyclePurge,
recyclePurgeBatch,
recycleEmpty,
} from 'smh-web-uikit'


API 参考

以下为完整的 API 接口, 可根据需要自由组合使用。

文件操作

函数
说明
备注
getFileList(dirPath, { page, pageSize })
获取文件列表
分页加载
uploadFile(file, filePath, callbacks)
上传文件
分片/秒传,自动创建目录
downloadFile(filePath, fileName?)
下载文件
触发浏览器下载
delFile(filePath)
删除文件
默认进回收站
delDirectory(dirPath)
删除目录
默认进回收站
createDirectory(dirPath)
创建文件夹
同名自动重命名
moveFile(from, to)
移动文件
冲突自动重命名
moveDirectory(from, to)
移动目录
冲突自动重命名
copyFile(from, to)
复制文件
冲突自动重命名
copyDirectory(from, to)
复制目录
冲突自动重命名
renameFile(old, new)
重命名文件
同名会报冲突错误
renameDirectory(old, new)
重命名目录
同名会报冲突错误
getFileInfo(filePath)
获取文件详情
支持获取文件或文件夹信息
searchFiles(options)
搜索文件
QPS 上限10

预览与下载

函数
说明
getPreview(filePath, isDOC)
图片/视频返回 URL,文档返回文本内容
getDocPreviewUrl(filePath)
获取文档在线预览 URL(用于 iframe)
getFilePreviewUrlOrContent(file)
自动判断类型获取预览
getSpaceUsage()
获取空间配额和已用容量

回收站

函数
说明
getRecycleList({ page, pageSize })
获取回收站列表
recycleRestore(recycledItemId)
恢复单个项目
RecycleRestoreBatch(ids)
批量恢复
recyclePurge(recycledItemId)
永久删除单个项目
RecyclePurgeBatch(ids)
批量永久删除
recycleEmpty()
清空回收站

Token 与配置管理

函数
说明
setSmhConfig(config)
设置配置(应用启动时调用)
initToken()
初始化 Token
ensureValidToken()
确保 Token 有效,自动续期
isTokenExpiringSoon()
检查 Token 是否即将过期(5 分钟内)
clearConfig()
清除所有配置和缓存
clearSpaceCache(spaceId)
清除指定空间的 Token 缓存