# 鸿蒙 HarmonyOS 常见问题

# 1. 集成时常见问题

# 1.1 地图组件和 chooseLocation 等页面地图显示空白

答：请根据文档检查配置是否正确，也可以新建一个鸿蒙工程，使用相同的证书和配置创建一个地图组件，检查是否可以正常显示。

# 2. 使用时常见问题

# 2.1 如何使用自定义 API 打开原生页面？

答：根据场景有不同的实现方式，下面以 Navigation 启动方式举例

只是打开原生页面，不需要接受返回参数

import { router } from '@kit.ArkUI'
function navigateToAPP(args: IApiManager.IInvokeArgs, apiManager: ApiManager) {
  const params = args.params
  const callback = args.callback
  router.pushUrl({
    url:'CustomApiPage'
  })
  callback.onSuccess({ data: 'navigateToAPP success !!' })
}

跳转到原生页面，并且需要接受返回数据返回给小程序

function navigateToAPP(args: IApiManager.IInvokeArgs, apiManager: ApiManager) {
  const params = args.params
  const callback = args.callback
  FinAppClient.getInstance()?.getEntryInfo().routerState?.pushPath({
    name: 'CustomApiPage',
    onPop:(info)=>{
      callback.onSuccess({ data: info.result })
    }
  })
}

# 2.2 如何实现自定义开屏并提前告知用户自定义隐私协议？

答：可以使用自定义 loading 页，参考文档

可以参考以下代码，具体业务逻辑请根据实际需求实现：

import { FinAppProxyHandlerManager, IFinProxyHandlerItem } from '@finclip/sdk'
import { CustomLoadingLayout } from '../customLayout/LoadingLayout'
import { common } from '@kit.AbilityKit'

class CustomLayoutHandler extends IFinProxyHandlerItem.CustomLayoutHandler {
  context:common.UIAbilityContext
  onLoadingLayoutReadyResolve?:()=>void
  agreed:boolean = false

  constructor(context:common.UIAbilityContext) {
    super()
    this.context= context
    this.context.eventHub.on('agree',()=>{
      if( this.onLoadingLayoutReadyResolve){
        this.onLoadingLayoutReadyResolve()
        this.onLoadingLayoutReadyResolve = undefined
      }
      this.agreed = true
    })
  }


  onLoadingLayoutReady(): Promise<void> {
    return new Promise((resolve) => {
      if(this.agreed){
        resolve()
      }else{
        this.onLoadingLayoutReadyResolve = resolve
      }
    })
  }

  getCustomLoadingLayout(): (() => void) | void {
    return CustomLoadingLayout
  }
}

@Builder
export function CustomLoadingLayout() {
  CustomViewComponent()
}

@Component
struct CustomViewComponent {
  context = getContext(this) as common.UIAbilityContext


  aboutToAppear() {
    if(this.getPreferencesFromStorage()){
        this.onAgree()
    }
  }

  // 从缓存库中获取缓存的数据
  async getPreferencesFromStorage() {

  }
  // 将用户点击同意进行缓存
  async putPreference() {

  }
  // 获取缓存数据
  async getPreference(){

  }

  onCancel() {
  }

  //同意隐私政策
  async onAgree() {
    this.context.eventHub.emit('agree')
    this.putPreference()
  }

  build() {
    Column(){
      Button('同意').onClick(()=>{this.onAgree()})
      Button('取消').onClick(()=>{this.onCancel()})
    }
    .width('100%')
    .height('100%')
  }
}

export function initCustomLayoutHandler(context:common.UIAbilityContext) {
  FinAppProxyHandlerManager.customLayoutHandler = new CustomLayoutHandler(context)
}

# 2.3 录音等 API 不生效？

答：请检查对应权限是否声明、证书是否包含对应的权限

# 2.4 使用 Router 方式启动小程序，然后使用 router 跳转页面，返回后小程序无法关闭

答：由于鸿蒙 router 机制问题，页面返回时默认不携带参数导致小程序页面逻辑判断不了，需要在自定义页面添加下面的代码自己处理返回事件

@Entry
@Component
struct Page {

  onBackPress(): boolean | void {
    const uiRouter = this.getUIContext().getRouter()
    const length = parseInt(uiRouter.getLength())
    const lastPageParams = uiRouter.getStateByIndex(length - 1)
    uiRouter.back(length - 1, lastPageParams?.params)
    return true
  }

  build() {
    // ...
  }
}

# 3. 调试方面

# 3.1 如何调试小程序？

在应用在初始化SDK时，初始化配置项 IFinAppConfig 中的 enableWebviewDebug 参数设置为 true。
根据文档 (opens new window)开启调试。
然后可以在浏览器调试页面选择小程序打开的页面列表，选中当前打开的页面，就可以审核页面元素、查看网络调用，以及一些log日志等。

# 3.2 如何开启vConsole?

如果需要调试小程序，目前有多种方式开启vConsole，从而可以看到小程序中的日志。

三种方式开启vConsole:

应用在初始化SDK时，初始化配置项 IFinAppConfig 中的 appletDebugMode 参数设置为 enable
非正式版小程序且appletDebugMode参数为默认值的情况下，从更多面板里的【打开调试】菜单项开启vConsole调试。
小程序里可以调用小程序api(ft.setEnableDebug)来开启vConsole。

开启vConsole后的效果，如下图：

appletDebugMode的各个枚举值的作用：

appletDebugMode	说明
default	默认值，最终效果与微信的vConsole控制一致。非正式版更多菜单里会显示【打开调试】按钮
enable	强制所有小程序(所有版本)均开启vconsole，且无法通过setEnableDebug和更多菜单里的调试菜单关闭。
forbidden	强制所有小程序(所有版本)均关闭vconsole，且无法通过setEnableDebug和更多菜单里的调试菜单开启。
forbiddenRelease	强制所有小程序正式版均关闭vconsole，其他版本效果同 'default'。

注意

小程序的debug模式会持久化存储，即调用ft.setEnableDebug开启vConsole后，下次打开同一个小程序也会开启vConsole。
同一个小程序的debug模式一致，即体验版调用ft.setEnableDebug开启vConsole后，打开相同小程序id的正式版，也会开启vConsole。
appletDebugMode设置为'enable'或'forbidden'，则ft.setEnableDebug接口不生效。

最后，建议在app开发阶段，设置config.appletDebugMode为enable；然后在App提交审核时，修改为default。因为设置为default，正式版小程序不会显示【打开调试】和【关闭调试】按钮，但是依然可以通过api(ft.setEnableDebug)来开启vconsole。非正式版小程序，可以通过【打开调试】和ft.setEnableDebug来开启vconsole。

# 3.3 如何查看 Harmony SDK版本号和基础库版本号？

答：有多种方式：从小程序vConsole、从应用的 oh-package.json5 文件、从集成的har 内的 oh-package.json5文件、从应用中获取。

如果小程序有开启vConsole，那么从vConsole 中可以看到SDK 版本号和基础库版本号。打开vConsole后，Log栏前几行有显示基础库版本号；System栏的userAgent中有显示SDK版本号。

从应用的 oh-package.json5 文件中查看SDK版本号

从集成的 har 内的 oh-package.json5文件查看 SDK 版本号

如果是手动集成 har，则打开 har 内的 FinClipSDK.har 文件，找到 oh-package.json5 文件。

从应用中可以通过以下代码来获取 SDK 版本号

import { FinAppClient } from '@finclip/sdk'
FinAppClient.getSDKVersion()