简介
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 资源
参数 | 说明 | 示例 |
basePath | SMH API 地址 | https://smhxxxxxxx.api.tencentsmh.cn |
libraryId | 媒体库 ID | Smhxxxxxxxxxxxxx |
librarySecret | 媒体库密钥(仅后端持有) | your_secret |
spaceId | 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 签发 tokenconst params = new URLSearchParams({library_id: libraryId, // libraryId 替换为真实的 libraryIdlibrary_secret: librarySecret, // ⚠️ 仅后端持有, librarySecret 替换为真实的 librarySecretGrant: 'space_admin', // 签发给前端使用的权限推荐为本空间内最大权限Period: '7200', // 过期时间 2 小时spaceId, // 空间id});const response = await fetch(`${basePath}/api/v1/token?${params}`); // basePath 替换为真实的 basePathconst 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 (<SpaceDrivebasePath="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', // 需要替换为真实的basePathlibraryId: 'Smhxxxxxxxxxxxxx', // 需要替换为真实的libraryIdspaceId: 'spacexxxxx', // 需要替换为真实的spaceIdgetAccessToken: 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 缓存 |