HarmonyOSBaseLibs

徐勤民 93242a7c82 docs(basic): 更新 README 文档 3 days ago
src dbca937b2d refactor(app): 重构应用初始化和窗口处理逻辑 1 week ago
.gitignore 6ef4ef6d27 init 1 year ago
BuildProfile.ets 55e3dc9bc4 refactor(authorize): 优化授权时长选项并注释错误提示 4 days ago
CHANGELOG.md 07d1e906df build:切换到调试模式并更新版本号 1 week ago
Index.ets 67a57048ad 备份 3 months ago
LICENSE 096507cc42 接口请求 1 year ago
README.md 93242a7c82 docs(basic): 更新 README 文档 3 days ago
UTILS.md 6ef4ef6d27 init 1 year ago
build-profile.json5 5abdbe53de release包 10 months ago
consumer-rules.txt 5491db7726 sdk_ywx.1.0.1 10 months ago
hvigorfile.ts 6ef4ef6d27 init 1 year ago
obfuscation-rules.txt 6ef4ef6d27 init 1 year ago
oh-package.json5 c8289cee7e build(version): 更新版本号并调整依赖 3 months ago

README.md

基础开发工具包

ohpm install @szyx/sdk_base

0.初始化

在UIAbility的onWindowStageCreate方法中初始化该方法

// 初始化
import { GlobalContext } from '@szyx/sdk_base';
export default class AppAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {

    GlobalContext.setContext(this.context)

    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        LogHelper.error(`Failed to load the content. Cause: ${JSON.stringify(err) ?? ''}`);
        return;
      }
      hilog.info(0x0000, 'testTag', 'Succeeded in loading the content.');
      WindowHelper.windowClass = windowStage.getMainWindowSync()
    });
  }
}

1.utils

1.1.AppStorageHelper

缓存工具类,运行时存储,应用停止运行后清空

import { AppStorageHelper } from '@szyx/sdk_base/Index'

// 存储string数据
AppStorageHelper.save(StorageKeys.CLIENT_ID, d)

// 获取存储的strign数据
let d = AppStorageHelper.get(StorageKeys.CLIENT_ID)
// 删除指定存储
AppStorageHelper.delete(StorageKeys.CLIENT_ID)

1.2.PreferencesHelper

永久存储类,应用停止后也不会清空 需要验证,更新应用会不会被清理 可存储类型 number | string | boolean | Array<number> | Array<string> | Array<boolean> | Uint8Array

import { PreferencesHelper } from '@szyx/sdk_base/Index'

// 存储数据
PreferencesHelper.put(StorageKeys.CLIENT_ID, value)

// 获取存储的数据
PreferencesHelper.get(StorageKeys.CLIENT_ID).then(res => {
  console.log('>>>>>', res)
})
// 删除存储的数据
PreferencesHelper.delete(StorageKeys.CLIENT_ID).then(() => {
  console.log('>>>>>')
})

1.3.ToolsHelper

常用方法工具栏 基础方法

1.3.1.弹出Toast提示

import { ToolsHelper } from '@szyx/sdk_base';

ToolsHelper.showMessage('Hello Word!')

1.3.2.打印日志

打印格式:========>${顶层调用栈}::

import { ToolsHelper } from '@szyx/sdk_base';

ToolsHelper.log('Hello Word!')

1.3.3.获取调用栈第一个

import { ToolsHelper } from '@szyx/sdk_base';

ToolsHelper.getStackKey()

1.3.4.获取设备信息

import { ToolsHelper } from '@szyx/sdk_base';

ToolsHelper.getDeviceInfo()

1.3.5.ArrayBuffer转string

import { ToolsHelper } from '@szyx/sdk_base';

ToolsHelper.toString()

1.3.6.获取随机数

import { ToolsHelper } from '@szyx/sdk_base';

ToolsHelper.getUuid()

1.3.7.防抖

import { ToolsHelper } from '@szyx/sdk_base';

ToolsHelper.debounceHold(()=>{},300)

1.3.8.Dialog

import { ToolsHelper } from '@szyx/sdk_base';

ToolsHelper.showConfirmDialog({
  title: '提示',
  msg: '提示信息',
  confirm: {
    text: '确定',
    color: '#18ABFB',
    onClick: () => {

    }
  },
  cancel: {
    text: '取消',
    onClick: () => {

    }
  }
})

ToolsHelper.showAlertDialog({
  title: '提示',
  msg: '提示信息',
  action: {
    onClick: () => {

    }
  }
})

如果需要自定义弹窗UI,可以参考ToolsHelper中以下部分代码

 @Builder
 function customDialogBuilder<T>(option: ListOptions<T>, dialogTag: string) {
 //......
 }

注意,传入参数(options: AlertBean)是固定的

1.4.ValidatorHelper

常用正则

1.4.1.验证手机号

import { ValidatorHelper } from '@szyx/sdk_base';

ValidatorHelper.isPhone('13800000000')

1.4.2.是否为身份证号

import { ValidatorHelper } from '@szyx/sdk_base';

ValidatorHelper.isIdcardNum()

1.5.AlgorithmHelper

计算相关

1.5.1.计算两点间距离

import { AlgorithmHelper } from '@szyx/sdk_base';

AlgorithmHelper.calculateDistance(x1, y1, x2, y2)

1.6.XWebHelper

打开webview页面

import { XWebHelper } from '@szyx/sdk_base';

// 必须先引入,否则无法跳转
const XWebview = import('../pages/XWebview');

XWebHelper.openWeb({
  url: 'https://www.baidu.com',
  title: '百度一下',
})

1.6.1 添加JavaScript交互

主要是用来做H5和原生交互

jsParams 传入相关参数

详见官方文档

// 定义`js`指定名称
export const JSSdkName = 'HarmonyOSWebView'
// 允许调用的方法列表
export const JSSdkMethodList = ['showToast']
export class JSSdkClsManager {
    // 供`HTML`调用的方法
  showToast(msg: string): void {
    ToolsHelper.log('showToast', msg)
  }
}
// 定义控制器
xc: XWebJsController = {} as XWebJsController

// 打开webview
XWebHelper.openWeb({
    url: 'https://www.baidu.com',
    jsParams: {
        obj: new JSSdkClsManager(),
        name: JSSdkName,
        methodList: JSSdkMethodList,
        controller: this.xc,
    }
})
// 交互消息的收发,见官方文档
// 原生向web发送消息
this.xc.sendMessage('发送给html的内容')
// html调用原生方法
window.HarmonyOSWebView.showToast('hello word!')

1.7.PickerDateTimeHelper

时间日期选择弹窗相关

1.7.1 选择日期

import { PickerDateTimeHelper } from '@szyx/sdk_base'

PickerDateTimeHelper.showDateDialog({
  onConfirm: (date) => {
    ToolsHelper.log(date)
  }
}, this)

1.7.TimeHelper

时间日期选择弹窗相关

1.7.1 获取当前时间戳

import { TimeHelper } from '@szyx/sdk_base'

TimeHelper.getTimeMillis()

1.7.2 获取当前时间的指定格式的字符串

import { TimeHelper } from '@szyx/sdk_base'

TimeHelper.getTime()

1.7.3 获取指定时间的指定格式的字符串

import { TimeHelper } from '@szyx/sdk_base'

TimeHelper.formatDate(new Date(), 'yyyy-MM-dd HH:mm:ss')

1.7.4 获取指定时间的指定格式的字符串(时间戳参数)

import { TimeHelper } from '@szyx/sdk_base'

TimeHelper.formatDateForTime(time, 'yyyy-MM-dd HH:mm:ss')

1.7.4 获取指定年月天数

import { TimeHelper } from '@szyx/sdk_base'

TimeHelper.getMonthDays()

1.8.ImageHelper

1.8.1 压缩图片到指定大小

import { ImageHelper } from '@szyx/sdk_base'

ImageHelper.compressedImage(pixelMap, this.maxCompressedImageSize).then((data: ArrayBuffer) => {
  // 压缩后到图片数据
}).catch((err: BusinessError) => {
  ToolsHelper.showMessage(err.message)
})

2.Dialog

2.1.弹出list选中弹窗

import { XDialogController } from '../dialog/XDialogController';
import { XDialogList } from '../dialog/XDialogList';

@Component 
struct MyView{
  // 控制器,控制开关
  dialogController: XDialogController = {} as XDialogController

  build()
  {
    Column()
    {
      Button
      ({ buttonStyle: ButtonStyleMode.TEXTUAL })
      {
        Image($r('sys.media.ohos_ic_public_more'))
          .width(26).height(26)
      }
      .
      width(65)
        .onClick(() => {
        if (this.dialogController != null) {
          this.dialogController.open()
        }
      })

      XDialogList({
        // 控制器
        controller: this.dialogController,
        // 标题(可选)
        title: '选择您的操作',
        // 选择内容列表
        values: ['刷新', '浏览器打开', '分享', '复制地址'],
        // 用户选择事件
        onSelected: (index: number, value: string) => {
          ToolsHelper.showMessage(`用户选择了第${index}个,内容为:${value}`)
        },
        // 用户取消事件
        onCancel: () => {
          ToolsHelper.showMessage('用户取消操作')
        },
        // 是否可取消(点击空白处,或者物理返回键)
        autoCancel: true
      })

    }
    .
    width('100%').height('100%')
  }
}

3.网络请求

使用时建议二次封装

// 参数定义如下
/**
* 
* @param url url地址
* @param data 请求参数
* @param headers 请求头
* @param apiNo 请求标识,取消请求或者去重使用|考虑做自动重试使用
* @returns
  */

3.1.get请求

HttpHelper.get()
    .get<HttpResult<T>>(url,
                        data ? JSON.stringify(data) : undefined, {
    version: ConstantValue.VERSION
}, url.apiNo)
    .then((res: HttpResult<T>) => {
    if (res.status === '0') {
        resolve(res.data as T)
    } else {
        reject(new Error(res.message))
    }

})
    .catch((error: Error) => {
    reject(error)
})

3.2.postJson


HttpHelper.get()
    .post<HttpResult<T>>(url,
                         data ? JSON.stringify(data) : undefined, {
    version: ConstantValue.VERSION
}, apiNo)
    .then((res: HttpResult<T>) => {
    if (res.status === '0') {
        resolve(res.data as T)
    } else {
        reject(new Error(res.message))
    }

})
    .catch((error: Error) => {
    reject(error)
})

3.3.postForm

HttpHelper.get()
        .postForm<HttpResult<T>>({
          url: '',
          data: data,
          headers: {
            version: ConstantValue.VERSION,
            deviceId: GlobalValue.getInstance().deviceId,
          }
        }, apiNo, showLog)
        .then((res: HttpResult<T>) => {
          if (res.status === '0' || res.code === 200) {
            resolve(res.data as T)
          } else {
            reject(new YWXError(res.status ?? res.code?.toString() ?? '-1', res.message))
          }
        })
        .catch((error: Error) => {
          reject(new YWXError(error.name ?? '-1', error.message))
        })

3.4.upload

HttpHelper.get()
        .upload<HttpResult<T>>({
          url: url,
          data: data,
          onProgress,
          headers: {
            'X-Access-Token': HosGlobalValue.getInstance().token,
          }
        }, apiNo, showLog)
        .then((res: HttpResult<T>) => {
          if (res.code === 200) {
            resolve(res.data as T)
          } else if (res.code === 40003) {
            AccountManager.get().logout()
            ToolsHelper.showMessage('登录已过期,请重新登录')
          } else {
            reject(new YWXError(res.code?.toString() ?? '-1', res.message))
          }
        })
        .catch((error: Error) => {
          reject(new YWXError(error.name ?? '-1', error.message))
        })

4.自定义view

4.1.LoadingView

封装了loading的根布局

import { LoadingView } from '@szyx/sdk_base'

@State isLoading: boolean = false

build() {
    Stack() {
        LoadingView({ isLoading: this.isLoading }) {
            Column() {
                Text('正常布局')
            }
            .width('100%')
                .height('100%')
        }
    }
}

4.2.SafeView

基础布局

import { SafeView } from '@szyx/sdk_base'

@State isLoading: boolean = false

build() {
    SafeView({
        isLoading: this.isLoading,
        titleText: '注册',
        onClickLeft:{img:$r("app.media.base_back"),
                     onClick:()=>{}
                    },
        onClickRight:{
            text:'添加',
            color:'#ff1d9999',
            onClick:()=>{}
        }
    }){
        // 自己的布局
    }
}

4.3.RefreshView

下拉刷新,上拉加载更多

import { RefreshView } from '@szyx/sdk_base'

@State isLoading: boolean = false


@Builder
buildItem(item: Item, index: number) {
    Column() {
    }
    .width('100%')
}

build() {
    // ......
    RefreshView({
        isLoading: this.isLoading,
        // 是否自动调用`onRefresh`方法,默认为`true`,加载组件会自动调用一次`onRefresh`
        init: false,
        // 第一次加载完成,是否定位到底部,默认`false`,定位到顶部
        positioningToBottom: true,
        // 控制器,提供跳转到顶部、跳转到底部、是否已经在最底部方法
        controller: this.msgController,
        // 唯一标识,view的key
        keyGenerator: () => {
            return ToolsHelper.getUuid().toString()
        },
        // 每页请求的数据大小,根据这个参数判断是否可以上拉加载更多
        pageSize: 10,
        data: this.list ?? [],
        // 这里要用箭头函数,否则buildItem里面的this指向不对
        customBuilderParam: (item: ImMessage, index: number) => {
            this.buildItem(item, index)
        },
        // 下拉刷新回调
        onRefresh: () => {
            this.getHistory()
        },
        // 上拉加载更多回调
        onLoadMore: (pageNum) => {
            this.refresh(pageNum)
        }
    })
    // ......

}

4.3.SwipeView

左滑删除

    SwipeView({
      onItemClick: () => {
      //item点击事件
      }, onDelete: () => {
        ToolsHelper.showMessage('删除')
      },
    }) {
    // item布局
      Column() {}
      .width('100%')
      .padding({ left: 16, right: 16, bottom: 12 })
    }

5.Windows

5.1.弹出自定义窗口

弹出自定义窗口

import { WindowHelper } from '@szyx/sdk_base'

WindowHelper.open({
    name: '登录弹窗',
    router:'login'
})

WindowHelper.close()

5.2.设置沉浸式相关

// 需要的界面
// 设置是否全屏
WindowHelper.setWindowLayoutFullScreen(true)

// 隐藏状态栏
WindowHelper.hideStatusBar()

// 显示状态栏
WindowHelper.showStatusBar()

// 顶部安全区高度
WindowHelper.topRectHeight()

// 底部安全区高度
WindowHelper.bottomRectHeight()

// 屏幕宽度
WindowHelper.windowsWidth

// 屏幕高度
WindowHelper.windowsHeight

**** 常见问题