主 SDK 接口文档
概述
主 SDK (index.js) 是整个 JavaScript SDK 的入口点,整合了 HTTP 请求、WebSocket 通信、权限管理等多个子模块,提供了统一的 API 接口。
主要属性
ddiot 对象
const ddiot = {
// API 函数集合
...apiFunc,
...adminFunc,
// 基础属性
bloc_id: 0, // 区域ID
request: sendHttp, // HTTP 请求实例
websocket: null, // WebSocket 实例
websocketConf: null, // WebSocket 配置
permission: permission, // 权限管理
iglobal: iglobal, // 全局变量
uploadImgUrl: '', // 图片上传地址
apiBsaeUrl: '', // API 基础地址
imgBaseUrl: '', // 图片基础地址
siteUrl: '', // 站点地址
WECHAT_LOGIN: true, // 微信登录开关
WECHAT_AUTH_BACK_URL: 'WECHAT_AUTH_BACK_URL', // 微信授权回调URL
// H5 环境下的微信 JS SDK
// #ifdef H5
jweixin: jweixin,
// #endif
}
初始化方法
install 方法
install(vueInstance, extra = {})
初始化 SDK 并将其安装到 Vue 实例上。
参数说明
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| vueInstance | Vue Instance | - | Vue 实例 |
| extra | Object | {} | 额外配置 |
extra 配置说明
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
| http | Object | 是 | HTTP 配置 |
| websocketConf | Object | 否 | WebSocket 配置 |
WebSocket 配置要求
WebSocket 配置必须包含以下参数:
url: WebSocket 服务器地址authUrl: 认证服务器地址heartRateType: 心跳类型heartRate: 心跳间隔app_id: 应用ID
使用示例
// 在 main.js 中使用
app.use(ddiot, {
websocketConf: {
url: "wss://iot.ddicms.com:9502/addons",
authUrl: 'wss://iot.ddicms.com:9502/auth',
heartRateType: 'heart',
heartRate: 20000,
app_id: 'your_app_id',
app_secret: 'your_app_secret',
},
http: {
successCode: 200,
apiConfig: {
bloc_id: 1,
store_id: 1,
baseUrl: 'https://api.example.com',
// ... 其他配置
}
}
})
WebSocket 相关方法
createSocket 方法
createSocket(route = 'addons')
创建 WebSocket 连接。
参数说明
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| route | String | 'addons' | 路由类型 |
返回值
返回一个 Promise,解析为 WebSocket 实例。
使用示例
// 创建 WebSocket 连接
const createWebSocket = async () => {
try {
const socket = await ddiot.createSocket('addons')
console.log('WebSocket 创建成功:', socket)
ddiot.websocket = socket
} catch (error) {
console.error('WebSocket 创建失败:', error)
}
}
closeSocket 方法
closeSocket()
关闭 WebSocket 连接并清理实例。
HTTP 请求方法
request 方法
request(url, method, data, loading = false, header = {})
发起 HTTP 请求。
参数说明
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| url | String | - | 请求URL |
| method | String | - | 请求方法 (GET, POST, PUT, DELETE 等) |
| data | Object | {} | 请求数据 |
| loading | Boolean | false | 是否显示加载动画 |
| header | Object | {} | 请求头 |
使用示例
// 获取设备组数据
const getDeviceData = async (deviceMac) => {
try {
const response = await ddiot.request('/device/deviceGroup', 'POST', {
device_mac: deviceMac
}, true, {
scene: 'iot'
})
return response.data
} catch (error) {
console.error('请求失败:', error)
}
}
辅助方法
toast 方法
toast(text, duration, success)
显示 Toast 提示。
参数说明
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| text | String | "出错啦~" | 提示文本 |
| duration | Number | 2000 | 显示时长 |
| success | Boolean | false | 是否显示成功图标 |
使用示例
ddiot.toast('操作成功', 2000, true)
modal 方法
modal(title, content, showCancel, callback, confirmColor, confirmText)
显示模态对话框。
参数说明
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| title | String | '提示' | 标题 |
| content | String | - | 内容 |
| showCancel | Boolean | - | 是否显示取消按钮 |
| callback | Function | - | 回调函数 |
| confirmColor | String | "#5677fc" | 确认按钮颜色 |
| confirmText | String | "确定" | 确认按钮文本 |
使用示例
ddiot.modal('确认操作', '您确定要执行此操作吗?', true, (confirm) => {
if (confirm) {
// 执行确认操作
}
})
平台检测方法
isAndroid
isAndroid()
检测是否为 Android 平台。
isPhoneX
isPhoneX()
检测是否为 iPhone X 系列设备。
时间相关方法
logTime
logTime(remark)
记录当前时间戳。
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| remark | String | 备注信息 |
使用示例
ddiot.logTime('开始执行操作')
// ... 执行某些操作
ddiot.logTime('操作完成')
登录状态相关方法
isLogin
isLogin()
检查是否已登录。
getToken
getToken()
获取访问令牌。
getRefToken
getRefToken()
获取刷新令牌。
工具函数
constNum
constNum()
返回特定平台的常量值。
HTTP 配置
配置结构
{
successCode: 200, // 成功状态码
apiConfig: {
bloc_id: 1, // 区域ID
store_id: 1, // 商店ID
baseUrl: '', // API 基础URL
siteUrl: '', // 站点URL
uploadImgUrl: '', // 上传图片URL
imgBaseUrl: '', // 图片基础URL
headerFunc: (config) => {}, // 请求头生成函数
beforRequest: (config) => {}, // 请求前处理函数
getToken: () => {}, // 获取令牌函数
getRefToken: () => {}, // 获取刷新令牌函数
refTokenCallBack: (res) => {}, // 刷新令牌回调函数
},
responseSuccessCallBack: (res) => {}, // 响应成功回调
apiList: [], // API 列表
}
请求拦截器
beforRequest
在请求发送前对配置进行处理。
beforRequest: (config) => {
const token = uni.getStorageSync('access_token')
const whiteList = ['/wechat/decrypt/msg', '/wechat/basics/signup']
if (whiteList.some(path => config.url.includes(path))) {
return config
}
if (!token) {
// 未登录处理
uni.reLaunch({
url: '/pages/login/index'
})
return Promise.reject(config)
}
return config
}
responseSuccessCallBack
处理响应成功后的逻辑。
responseSuccessCallBack: (res) => {
if (res && (res.code === 403 || res.code === 402)) {
// 登录过期处理
uni.removeStorageSync('access_token')
uni.reLaunch({
url: '/pages/login/index'
})
} else if (res.code !== 200) {
// 其他错误处理
uni.showModal({
title: '提示',
content: res.message,
showCancel: false
})
}
}
权限管理
SDK 集成了权限管理模块,支持不同平台的权限申请。
// 使用权限管理
const checkPermission = async () => {
const result = await ddiot.permission('location')
if (result) {
// 有权限,执行相关操作
} else {
// 无权限,引导用户授权
}
}
实际应用示例
页面中使用 SDK
// 在 Vue 组件中使用
import { getCurrentInstance } from 'vue'
export default {
setup() {
const { proxy } = getCurrentInstance()
const $ddiot = proxy.$ddiot
// 获取设备数据
const fetchDeviceData = async (mac) => {
try {
const response = await $ddiot.request('/device/info', 'GET', { mac })
return response.data
} catch (error) {
console.error('获取设备数据失败:', error)
}
}
// 初始化 WebSocket
const initWebSocket = async () => {
try {
const ws = await $ddiot.createSocket()
$ddiot.websocket = ws
// 监听消息
ws.on('device_status', (data) => {
console.log('设备状态更新:', data)
})
} catch (error) {
console.error('WebSocket 初始化失败:', error)
}
}
return {
fetchDeviceData,
initWebSocket
}
}
}
全局配置示例
// main.js 中的完整配置
export function createApp() {
const app = createSSRApp(App)
// 全局挂载
app.config.globalProperties.$ddiot = ddiot
app.use(ddiot, {
websocketConf: {
url: "wss://your-server.com/addons",
authUrl: 'wss://your-server.com/auth',
heartRateType: 'heartbeat',
heartRate: 30000,
app_id: 'your_app_id',
app_secret: 'your_app_secret',
},
http: {
successCode: 200,
apiConfig: {
bloc_id: 1,
store_id: 1,
baseUrl: 'https://api.your-domain.com',
siteUrl: 'https://your-domain.com',
uploadImgUrl: 'https://api.your-domain.com/upload',
imgBaseUrl: 'https://your-domain.com/images/',
headerFunc: (config) => {
return {
'bloc-id': uni.getStorageSync('bloc-id') || 1,
'store-id': uni.getStorageSync('store-id') || 1,
'access-token': uni.getStorageSync('access_token') || ''
}
},
beforRequest: (config) => {
// 请求前处理逻辑
return config
},
getToken: () => uni.getStorageSync('access_token'),
getRefToken: () => uni.getStorageSync('refresh_token'),
refTokenCallBack: (res) => {
// 刷新令牌回调
uni.setStorageSync('access_token', res.data.access_token)
}
},
responseSuccessCallBack: (res) => {
// 响应处理逻辑
if (res.code !== 200) {
uni.showToast({
title: res.message,
icon: 'none'
})
}
}
}
})
return { app }
}
注意事项
- 初始化时机: 确保在使用 SDK 功能前已完成初始化
- 错误处理: 始终包含适当的错误处理逻辑
- 资源清理: 在适当的时候清理 WebSocket 连接和其他资源
- 安全性: 敏感信息如 app_secret 应妥善保管
- 平台差异: 注意不同平台间的差异,使用条件编译处理
- 版本兼容性: 关注 SDK 版本更新,及时适配新功能
