@lazycatcloud/sdk 0.1.141 → 0.1.144

package/docs/contribute.md

@@ -0,0 +1,40 @@
+<!--
+ * @Author: Bin
+ * @Date: 2023-03-06
+ * @FilePath: /lzc-sdk/lang/js/docs/contribute.md
+-->
+# 懒猫云客户端 SDK 部分贡献指南
+
+> 该部分文档主要针对 SDK 开发者（内部）对接沟通使用。 
+
+## 准备开发
+
+1. `lzc sdk` 开发目录 `./extentions`，目前 SDK 主要对象为 `LzcAppSdk`，该对象为一个单例。调用 `LzcAppSdk.getInstance()` 函数即可获得对象实例。
+
+2. `LzcAppSdk` 内置工具函数如下 [更多函数参考 base.ts 代码](../extentions/base.ts):
+    -  isWebShell() 判断是否属于 webshell 环境
+    -  isAndroidWebShell() 是否是android webshell 环境
+    -  isPCWebShell() 是否是pc webshell 环境
+    -  isIosWebShell() 是否是ios webshell 环境
+    -  isControlView() 是否属于 Control webshell 环境
+    -  isContentView() 是否属于 Content webshell 环境
+    -  isInApplication() 是否在客户端内
+
+3. 通过 `LzcAppSdk` 获取原生（Android、iOS、PC）JSBridge 对象引用，由于部分平台（对，没错就是 iOS）特性获取 JSBridge 方式提供了异步和同步获取两种方式。（注: IOS 在调用 `useNative()` 获取到的 JSBridge 引用对象是缓存对象，如果未初始化完就调用可能会出现调用失败情况，所以类似 `GetValue()` 这种需要返回值的实现请一定一定尽量使用 `useNativeAsync()` 来获取 JSBridge 引用对象。）
+    - useNativeAsync(namespaces?: any)
+    - useNative(namespaces?: any)
+
+4. `@native` 装饰器，为了避免跨平台调用函数导致页面异常问题，请实现函数时尽量使用该装饰器声明其支持的平台，对于不支持的平台该装饰器会自动处理替换为空函数实现。平台类型参数如下
+    - LzcAppPlatformType.Android
+    - LzcAppPlatformType.IOS
+    - LzcAppPlatformType.PC
+    - LzcAppPlatformType.Browser
+
+5. 关于如何实现一个支持全平台的 SDK API 最佳实践请参考 [app_common.ts](../extentions/app_common.ts)
+
+6. `LzcAppSdk` 提供回调函数处理实现请参考 [关于如何实现回调函数](#关于如何实现回调函数)
+
+
+## 关于如何实现回调函数
+
+文档整理中（🕊️）…

package/docs/extentions/AppCommon.md

@@ -0,0 +1,30 @@
+<!--
+ * @Author: Bin
+ * @Date: 2023-03-06
+ * @FilePath: /lzc-sdk/lang/js/docs/extentions/AppCommon.md
+-->
+# 懒猫云应用通用能力开发文档
+
+
+## 打开应用能力接口文档
+
+在部分场景下，用户在使用懒猫云应用的时候需要启动其他应用来完成任务。为此我们提供为懒猫云应用了打开应用能力以满足应用打开其他应用处理数据或完成任务的需求。打开应用能力面向开发者提供懒猫云应用唤起功能，通过打开应用能力开发者可安全便捷地使用懒猫云客户端或系统的能力，为懒猫云用户或设备使用者提供良好的用户体验。
+
+### 使用步骤
+
+1. 引入 SDK, 支持使用 CMD 标准模块加载方法加载
+```
+import { AppCommon } from '@lazycatcloud/sdk/dist/extentions';
+```
+
+2. 调用 `AppCommon.LaunchApp` 函数
+```
+AppCommon.LaunchApp("http://settings.pbkbin.heiyu.space/?path=/users/bin/download/", "pbkbin.heiyu.space");
+```
+
+### 调用参数
+
+| 名称 | 必填 | 默认值 | 备注 |
+| --- | --- | --- | --- |
+| url | 是 | | 懒猫云应用 URL，可通过 URL Parameter 方式携带参数
+| appid | 是 | | 懒猫云应用 appid 

package/extentions/app_common.ts

@@ -0,0 +1,63 @@
+import LzcAppSdk, { LzcAppPlatformType, LzcAppSdkManage, native } from './base';
+
+class AppCommon extends LzcAppSdkManage {
+
+    @native(LzcAppPlatformType.IOS)
+    public static async ScriptHandlers(): Promise<string[]> {
+        // const callback = await LzcAppSdk.useNative.ScriptHandlers()
+        // console.log("LzcAppSdk.useNative", LzcAppSdk.useNative);
+        const jsBridge = await LzcAppSdk.useNativeAsync()
+        const call = await jsBridge.ScriptHandlers()
+        // jsBridge.Test()
+        return call
+    }
+
+    /**
+     * @description: 打开应用
+     * @param {string} url
+     * @param {string} appid
+     * @return {Promise<void>}
+     */
+    @native(LzcAppPlatformType.IOS,
+        LzcAppPlatformType.Android,
+        LzcAppPlatformType.PC,
+        LzcAppPlatformType.Browser
+    )
+    public static async LaunchApp(url: string, appid: string): Promise<void> {
+        if (!LzcAppSdk.isInApplication()) {
+            // 判断是否在浏览器中，在浏览器中时或者用户设置为在浏览器打开时，将直接使用 window.open 打开页面
+            window.open(url, '_blank')
+        } else {
+            if(LzcAppSdk.isAndroidWebShell()){
+                const jsBridge = await LzcAppSdk.useNativeAsync(android_launch_service)
+                const openApprequest = {
+                    "appid": appid,
+                    "url": url,
+                }
+                var openAppRequestJsonStr = JSON.stringify(openApprequest);
+                jsBridge.LaunchApp(openAppRequestJsonStr)
+            }else{
+                const jsBridge = await LzcAppSdk.useNativeAsync()
+                jsBridge.LaunchApp(url, appid)
+            }
+        }
+    }
+
+    public static async LaunchNativeApp(filepath: string,appid: string) {
+        // TODO: 待实现
+        if(LzcAppSdk.isAndroidWebShell()){
+            const jsBridge = await LzcAppSdk.useNativeAsync(android_launch_service)
+            const openApprequest = {
+                "appid": appid,
+                "filepath": filepath,
+            }
+            var requestStr = JSON.stringify(openApprequest);
+            jsBridge.LaunchNativeApp(requestStr)
+        }else{
+            console.error("LaunchNativeApp 方法暂未实现。")
+        }
+    }
+
+}
+
+export { AppCommon }

package/extentions/base.ts

@@ -0,0 +1,459 @@
+/*
+ * @Author: Bin
+ * @Date: 2023-03-03
+ * @FilePath: /lzc-sdk/lang/js/extentions/base.ts
+ */
+
+enum PlatformType {
+    Android,
+    IOS,
+    PC,
+    Browser
+}
+
+// 不支持的平台 notSupportPlatform
+function disabled(...platforms: PlatformType[]) {
+    // console.log("PlatformType", list);
+    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
+        if (!(target.constructor === LzcAppSdk)) {
+            console.error("LzcAppSdk:", `notSupportPlatform error ${target.constructor}`)
+            return
+        }
+
+        let notSupport = false;
+        platforms.forEach((item: PlatformType) => {
+            switch (item) {
+                case PlatformType.Android:
+                    notSupport = target.isAndroidWebShell();
+                    return
+                case PlatformType.IOS:
+                    notSupport = target.isIosWebShell();
+                    return
+                case PlatformType.PC:
+                    notSupport = target.isPCWebShell();
+                    return
+                case PlatformType.Browser:
+                    notSupport = !(target.isWebShell());
+                    return
+            }
+        });
+
+        if (notSupport) {
+            descriptor.value = ((...args: any) => {
+                console.error("LzcAppSdk:", `The current platform does not support the ${propertyKey} method`)
+            })
+        }
+
+        // console.log("target", target);
+        // console.log("propertyKey", propertyKey);
+        // console.log("descriptor", descriptor);
+
+        return descriptor;
+    };
+}
+
+/**
+ * @description: 指定函数支持平台函数装饰器
+ * @param {array} platforms
+ * @return {Function}
+ */
+function native(...platforms: PlatformType[]): Function {
+    return function (target: Object, propertyKey: string, descriptor: PropertyDescriptor) {
+        const lzcSdk = LzcAppSdk.getInstance()
+        if (!lzcSdk) {
+            console.error("LzcAppSdk:", `instance is null`)
+            return
+        }
+
+        let support = false;
+        platforms.forEach((item: PlatformType) => {
+            if (support) {
+                return
+            }
+            switch (item) {
+                case PlatformType.Android:
+                    support = lzcSdk.isAndroidWebShell();
+                    return
+                case PlatformType.IOS:
+                    support = lzcSdk.isIosWebShell();
+                    return
+                case PlatformType.PC:
+                    support = lzcSdk.isPCWebShell();
+                    return
+                case PlatformType.Browser:
+                    support = !(lzcSdk.isInApplication());
+                    return
+            }
+        });
+
+        const method = descriptor.value;
+        // console.log("!!method ", method);
+        descriptor.value = new Proxy(descriptor.value, {
+            apply(target, thisArg, argArray) {
+                // console.log("!!method apply", Object.prototype.toString.call(target));
+                if (support) {
+                    // 当前函数支持该平台，调用函数实现
+                    return target.apply(thisArg, argArray)
+                }
+
+                // 当前函数不支持该平台，替换执行空函数体
+                console.warn("LzcAppSdk:", `The current platform does not support the ${propertyKey} method`)
+                if (Object.prototype.toString.call(target) === "[object AsyncFunction]") {
+                    // AsyncFunction
+                    return (async function () { })()
+                } else {
+                    // Function
+                    return (() => { })()
+                }
+            },
+        })
+
+        // if (!support) {
+        //     console.error("LzcAppSdk:", `The current platform does not support the ${propertyKey} method`)
+        //     let fun = method
+
+        //     if (!!method && typeof method.then === 'function') {
+        //         descriptor.value = (...args: any) => { }
+        //         fun = method.then
+        //     } else {
+        //         descriptor.value = async (...args: any) => { }
+        //     }
+
+        //     return descriptor
+        // }
+
+        // TODO: 处理 Native 函数注入拉平
+        // let useNative = {}
+        // useNative = new Proxy(useNative, {
+        //     get(target, prop, receiver) {
+
+        //         let item = target[prop]
+        //         let nativeClient = LzcAppSdk.getInstance().client
+        //         // let nativeClient = {
+        //         //     open: async () => {
+        //         //         console.log("useNative open.....");
+        //         //     },
+        //         //     getValue: async (name: String) => {
+        //         //         console.log("useNative open.....");
+        //         //         return name + ", emmmm"
+        //         //     }
+        //         // }
+
+        //         // console.log("target", target);
+        //         // console.log("prop", prop);
+        //         // console.log("receiver", receiver);
+
+        //         if (nativeClient) {
+        //             // 原生注入对象存在
+        //             let nativeAttribute = nativeClient[prop]
+        //             if (!item && nativeAttribute) {
+        //                 // 原生注入对象包含该属性/方法
+        //                 item = nativeAttribute
+        //                 if (typeof nativeAttribute == "function") {
+        //                     // 原生注入的是函数，准备拦截
+        //                     item = new Proxy<any>(item, {
+        //                         apply(target, thisArg, argArray) {
+        //                             return target(...argArray);
+        //                         },
+        //                     })
+        //                 }
+        //             }
+        //         }
+
+        //         // 拦截不存在的原生函数调用并提示警告
+        //         if (!item && (!nativeClient || !nativeClient[prop])) {
+        //             item = function (...params: any[]) { }
+        //             console.warn("LzcAppSdk:", `The ${String(prop)} method is not implemented on the current platform`)
+        //         }
+
+        //         return item
+        //     },
+        // })
+
+        // lzcSdk.useNative = useNative
+
+        // descriptor.value = Promise.resolve(function (...args: any) {
+        //     // console.log("应用", target);
+        //     const context = Object.assign(target, this instanceof LzcAppSdk ? {} : { LzcApp: lzcSdk })
+        //     method.apply(context, ...args);
+        //     // method(...args)
+        // })
+
+        // console.log("target", target);
+        // console.log("propertyKey", propertyKey);
+        // console.log("descriptor", descriptor);
+        return descriptor
+    };
+}
+
+class LzcAppSdk {
+    private static instance: LzcAppSdk;
+    private static cacheJSBridgeIOS: any; // 缓存 IOS JSBridge
+
+    protected constructor() {
+        // 初始化 JSBridge 回调事件队列
+        this.initCallbackQueue();
+        (async () => {
+            if (this.isIosWebShell()) {
+                // 由于 IOS JSBridge 需要异步获取，构造对象时触发缓存 JSBridgeIOS 对象
+                LzcAppSdk.cacheJSBridgeIOS = await LzcAppSdk.initJSBridgeIOS()
+            }
+        })();
+
+        // 缓存 LzcAppSdk 对象应用到 window 对象
+        if (!window.lzcAppSdk_client || window.lzcAppSdk_client !== this) {
+            window.lzcAppSdk_client = this;
+        }
+
+    }
+
+    /**
+     * @description: 获取 LzcAppSdk 对象实例
+     * @return {LzcAppSdk}
+     */
+    public static getInstance(): LzcAppSdk {
+        if (!LzcAppSdk.instance) {
+            LzcAppSdk.instance = new LzcAppSdk()
+        }
+        return LzcAppSdk.instance
+    }
+
+    /**
+     * @description: 初始化 JSBridge 全局回调队列
+     * @return {void}
+     */
+    private initCallbackQueue(): void {
+        if (!window.lzcAppSdk_responseCallBackFuncDict || !window.lzcAppSdk_responseCallBackFuncUniqueID) {
+            // 初始化回调方法存储器和索引ID
+            window.lzcAppSdk_responseCallBackFuncDict = {}
+            window.lzcAppSdk_responseCallBackFuncUniqueID = 1;
+        }
+
+        if (
+            !window.lzcAppSdk_sendCallBackFunc ||
+            window.lzcAppSdk_sendCallBackFunc != LzcAppSdk.sendCallBackFunc
+        ) {
+            window.lzcAppSdk_sendCallBackFunc = LzcAppSdk.sendCallBackFunc
+        }
+    }
+
+    /**
+     * @description: JS 调用原生函数时，添加回调方法到回调方法存储器，并返回索引ID
+     * @param {Function} responseCallBackFunc
+     * @return {string}
+     */
+    public static addToCallBackFuncDictWith(responseCallBackFunc: Function): string {
+        if (!responseCallBackFunc) return 'unValid_funcUniqueID'
+        var funcUniqueID = `lzc_${window.lzcAppSdk_responseCallBackFuncUniqueID++}_${new Date().getTime()}`
+        window.lzcAppSdk_responseCallBackFuncDict[funcUniqueID] =
+            responseCallBackFunc
+        return funcUniqueID
+    }
+
+
+    /**
+     * @description: 原生接受 JS 调用并处理相关操作后，发送回调给js, js 根据索引ID寻找回调方法来处理数据，然后移除js的回调方法
+     * @param {string} funcUniqueID
+     * @param {any} responseData
+     * @return {void}
+     */
+    public static sendCallBackFunc(
+        funcUniqueID: string,
+        responseData: any
+    ): void {
+        if (!funcUniqueID) return
+        const responseCallBackFunc =
+            window.lzcAppSdk_responseCallBackFuncDict[funcUniqueID]
+        if (!responseCallBackFunc) return
+        responseCallBackFunc(responseData)
+        delete window.lzcAppSdk_responseCallBackFuncDict[funcUniqueID]
+    }
+
+    /**
+     * @description: 注册一个 JS 函数
+     * @param {string} name
+     * @return {Promise<any> | undefined}
+     */
+    private static async _registerCallBackFunc(name: string): Promise<any> | undefined {
+        if (!name) return null
+        return async function (...args: any[]) {
+            let returnData = undefined
+            const funcUniqueID = LzcAppSdk.addToCallBackFuncDictWith(function (
+                data: any
+            ) {
+                returnData = data
+            })
+
+            const func = window.webkit.messageHandlers[name]
+            if (!func) {
+                console.error(
+                    'LzcAppSdk:',
+                    `ios webshell ${name} injection failed.`
+                )
+                return returnData
+            }
+            const value = await func.postMessage({
+                funcUniqueID,
+                params: [...args],
+            })
+            return value || returnData
+        }
+    }
+
+    /**
+     * @description: 获取 IOS 原生 JSBridge 对象
+     * @return {Promise<any>}
+     */
+    // @native(PlatformType.IOS)
+    private static async initJSBridgeIOS(): Promise<any> {
+        let view: any = {}
+        if (LzcAppSdk.cacheJSBridgeIOS) {
+            view = LzcAppSdk.cacheJSBridgeIOS
+        }
+        view['ScriptHandlers'] = await LzcAppSdk._registerCallBackFunc('ScriptHandlers')
+        const handlers = await view.ScriptHandlers()
+        try {
+            const data = typeof handlers == 'string' ? JSON.parse(handlers) : handlers
+            if (!data || data.length < 1) {
+                throw new Error('ios webshell ScriptHandlers handlers error.')
+            }
+        } catch (error) {
+            console.error('LzcAppSdk: ', error)
+            return
+        }
+
+        // 注册全部可用函数
+        for (const key in handlers) {
+            if (!handlers[key]) continue
+            view[handlers[key]] = await LzcAppSdk._registerCallBackFunc(handlers[key])
+        }
+
+        // 缓存 IOS JSBridge 对象
+        if (!LzcAppSdk.cacheJSBridgeIOS || (
+            view &&
+            Object.keys(view).length > 0 &&
+            LzcAppSdk.cacheJSBridgeIOS !== view
+        )) {
+            LzcAppSdk.cacheJSBridgeIOS = view
+        }
+
+        return view
+    }
+
+    /**
+     * @description: 根据原生注入命名空间 异步获取 JSBridge
+     * @param {any} namespaces
+     * @return {Promise<any>}
+     */
+    public async useNativeAsync(namespaces?: any): Promise<any> {
+        namespaces = this.useNative(namespaces)
+        if (this.isIosWebShell()) {
+            // ios JSBridge 是异步注入的，强制使用最新的
+            namespaces = await LzcAppSdk.initJSBridgeIOS();
+        }
+        return namespaces
+    }
+
+    /**
+     * @description: 根据原生注入命名空间 同步获取 JSBridge (如调用原生方法不需要回调值的可以使用该函数获取原生对象否则最好使用 useNativeAsync 函数)
+     * @param {any} namespaces
+     * @return {any}
+     */
+    public useNative(namespaces?: any): any {
+        if (!namespaces) {
+            let defaultNamespaces = {}
+            if (this.isIosWebShell() && LzcAppSdk.cacheJSBridgeIOS) {
+                LzcAppSdk.initJSBridgeIOS(); // 触发刷新缓存 ios JSBridge
+                defaultNamespaces = LzcAppSdk.cacheJSBridgeIOS
+            }
+            if (this.isAndroidWebShell()) {
+                defaultNamespaces = android
+            }
+            if (this.isPCWebShell()) {
+                defaultNamespaces = window.electronAPI
+            }
+            namespaces = defaultNamespaces
+        }
+
+        // TODO: 应该代理 JSBridge 对象函数调用，避免出现异常
+        if (!namespaces) {
+            console.warn("LzcAppSdk", "Does not exist JSBridge namespaces.")
+            namespaces = {}
+        }
+
+        return namespaces
+    }
+
+    /**
+     * @description: 判断是否属于 webshell 环境
+     * @return {boolean}
+     */
+    public isWebShell(): boolean {
+        return navigator.userAgent.indexOf("Lazycat") != -1 && !this.isControlView() && !this.isContentView();
+    }
+
+    /**
+     * @description: 是否是android webshell 环境
+     * @return {boolean}
+     */
+    public isAndroidWebShell(): boolean {
+        return navigator.userAgent.indexOf("Lazycat_101") != -1;
+    }
+
+    /**
+     * @description: 是否是pc webshell 环境
+     * @return {boolean}
+     */
+    public isPCWebShell(): boolean {
+        return navigator.userAgent.indexOf("Lazycat_102") != -1;
+    }
+
+    /**
+     * @description: 是否是ios webshell 环境
+     * @return {boolean}
+     */
+    public isIosWebShell(): boolean {
+        return navigator.userAgent.indexOf("Lazycat_103") != -1;
+    }
+
+    /**
+     * @description: 是否属于 Control webshell 环境
+     * @return {boolean}
+     */
+    public isControlView(): boolean {
+        return navigator.userAgent.indexOf("Lazycat_ControlView") != -1;
+    }
+
+    /**
+     * @description: 是否属于 Content webshell 环境
+     * @return {boolean}
+     */
+    public isContentView(): boolean {
+        return navigator.userAgent.indexOf("Lazycat_ContentView") != -1;
+    }
+
+    /**
+     * @description: 是否在客户端内
+     * @return {boolean}
+     */
+    public isInApplication(): boolean {
+        return navigator.userAgent.indexOf('Lazycat_Client') != -1
+    }
+}
+
+class LzcAppSdkManage {
+    protected static LzcApp: LzcAppSdk
+    protected LzcApp: LzcAppSdk
+}
+
+const LzcApp = LzcAppSdk.getInstance()
+
+/**
+ * @description: 兼容旧的 android 注入的 js 调用（待迁移后删除改引用）
+ * @deprecated: 该 JS 注入引用即将弃用，请尽快适配最新的 LzcAppSdk.useNative() 调用方式
+ * @return {any}
+ */
+const LzcClient: any = LzcApp.useNative()
+
+export default LzcApp
+export { PlatformType as LzcAppPlatformType, LzcAppSdkManage, LzcClient, native }

package/extentions/index.ts

@@ -0,0 +1,27 @@
+import { lzcAPIGateway } from './../index';
+/*
+ * @Author: Bin
+ * @Date: 2023-03-03
+ * @FilePath: /lzc-sdk/lang/js/extentions/index.ts
+ */
+
+import LzcApp from './base';
+
+declare global {
+    interface Window {
+        electronAPI?: any
+        webkit?: any
+        lzcAppSdk_responseCallBackFuncDict?: any
+        lzcAppSdk_responseCallBackFuncUniqueID?: any
+        lzcAppSdk_sendCallBackFunc?: any
+        lzcAppSdk_client?: any
+    }
+    const android: any
+    const android_launch_service: any
+}
+export default LzcApp
+export { LzcAppPlatformType, LzcClient } from './base'
+export { AppCommon } from './app_common'
+
+export { LzcApp }
+

package/extentions/safe_app.ts

@@ -0,0 +1,60 @@
+import App, { LzcClient } from './base';
+
+// 横屏
+const SCREEN_ORIENTATION_SENSOR_PORTRAIT = 1
+// 横向屏幕
+const SCREEN_ORIENTATION_SENSOR_LANDSCAPE = 2
+
+export const SAFE = {
+    // h5调用webview 打开App
+    OpenApp: function (url, isFullScreen) {
+        if (App.isWebShell()) {
+            return
+        }
+        LzcClient.OpenApp(url, isFullScreen)
+    },
+    // 目前只支持android
+    // 设置指定key 对应的value
+    SetValue: function (key, value) {
+        LzcClient.SetValue(key, value)
+    },
+    // 获取指定key的value
+    // 目前只支持android
+    GetValue: function (key) {
+        return LzcClient.GetValue(key)
+    },
+    // 目前只支持android
+    // 方向请使用常量
+    SetScreenOrientation: function (ori) {
+        LzcClient.SetScreenOrientation(ori)
+    },
+    // 最大255的亮度
+    SetScreentBrightness(number) {
+        LzcClient.SetScreentBrightness(number);
+    },
+    // 获取当前屏幕亮度百分比(0~1)
+    GetScreenBrightNess() {
+        return LzcClient.GetScreenBrightNess()
+    },
+    // 获取当前音量
+    GetCurrentVolume() {
+        return LzcClient.GetCurrentVolume();
+    },
+    // 设置指定音量
+    SetVoice(num) {
+        LzcClient.SetVoice(num);
+    },
+    // 增加音量
+    AddVoice() {
+        LzcClient.AddVoice()
+    },
+    SubVoice() {
+        LzcClient.SubVoice();
+    },
+    CloseWindow() {
+        LzcClient.CloseWindow
+    },
+    Minimize() {
+        LzcClient.Minimize();
+    }
+}