# 鸿蒙 HarmonyOS 常见问题

# 1. 集成时常见问题

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

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

# 1.2 SDK 收集的信息和涉及申请的权限有哪些？

收集的信息：系统类型、系统版本、手机厂商、手机型号、获取网络信息

涉及申请的权限：app 声明了什么权限就涉及什么权限，sdk 不主动声明权限。如果 app 未声明某个权限而小程序使用了对应的功能，那么会走失败逻辑，不影响其他功能的使用

具体使用的权限：可以参考文档

# 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() {
    // ...
  }
}

# 2.4 如何将小程序添加快捷方式到桌面

答：由于鸿蒙系统机制，该功能无法由 SDK 内部实现，宿主应用可以参考下面的方式实现

添加一个自定义更多菜单的按钮,参考文档
根据文档 (opens new window)给自定义按钮绑定快捷方式加桌的方法
在对应的 Ability 的生命周期做好 SDK 初始化操作，然后根据传入的事件调用打开小程序的方法

示例代码：

// 省略部分代码
export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // 如果应用是冷启动，点击快捷方式不会走 onNewWant 而是在这里接受 want 数据，需要处理好 SDK 初始化再调用打开小程序的方法
  }

  onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    const shortCutKey = want.parameters?.shortCutKey as string
    if (shortCutKey === 'startApplet') {
      this.startApplet(want);
    }
  }

  startApplet(want: Want) {
    const appId = want.parameters?.appId as string
    const apiServer = want.parameters?.apiServer as string

    if (appId && apiServer) {
      FinAppClient.getInstance()?.startApplet({
        appId,
        apiServer
      })
    }
  }
}

# 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()

# 4.适配方面

# 4.1 鸿蒙 PC 端需要如何适配？

答：无需额外的处理，建议使用 Ability 方式启动，让小程序可以在独立的窗口运行。由于在 PC 端胶囊按钮的位置会多最大化和最小化的两个按钮，uiConfig.capsuleConfig 里的 capsuleWidth 会默认*2。比如 capsuleWidth 设置了 88，在手机和 PAD 端是展示两个按钮的宽度，在 PC 端无须改动，SDK 会使用 88 * 2 的宽度展示4个按钮

# 4.2 鸿蒙 PC 端想对小程序窗口尺寸等做一些调整应该怎么处理？

答：如果是使用的不是 Ability 方式启动，由于系统机制问题，无法做到只控制小程序而不影响宿主应用。如果是使用 Ability 方式启动，可以在对应 Ability 的 onWindowStageCreate 拿到窗口对象。可以参考下表做调整，具体可以参考文档 (opens new window)

功能	window 对象的方法
设置窗口比例	setAspectRatio
隐藏默认导航栏	setWindowDecorVisible
隐藏控制按钮	setWindowTitleButtonVisible
禁止拖拽方式缩放	setResizeByDragEnabled