FinClip为企业提供小程序生态圈技术产品,开发者可在FinClip小程序开发帮助中心找到相关FinClip小程序指引

文档中心
  • 介绍
  • 开发
  • 小程序 SDK
  • 常见问题
  • 数据
  • 设计
  • 运营

# 鸿蒙 HarmonyOS 常见问题

# 1. 集成时常见问题

# 1.1 使用系统地图时，地图组件和 chooseLocation 等页面地图显示空白

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

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

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

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

# 2. 使用时常见问题

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

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

  1. 只是打开原生页面，不需要接受返回参数
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 !!' })
}
  1. 跳转到原生页面，并且需要接受返回数据返回给小程序
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 页承载隐私确认流程。

CustomLayoutHandler.onInitCompletion 从 1.5.4 版本开始新增，负责在隐私确认完成前阻塞小程序继续加载。

onLoadingLayoutReady 只负责控制 loading 页的关闭时机，不负责阻塞小程序加载。

# 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.5 如何将小程序添加快捷方式到桌面

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

  1. 从 1.5.2 版本开始，通过设置 IUIConfig.hideAddToDesktopMenu 为 false 来显示添加到桌面按钮，参考文档
  2. 然后根据文档实现 MoreMenuHandler.addToDesktop 代理方法
  3. 在对应的 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
      })
    }
  }
}

# 2.6 支持真机调试吗？应该如何使用？

答：在 1.3.5 版本的 SDK 中已支持真机调试。可以参考文档，选择 Android 系统生成真机调试二维码，调用扫码打开小程序的 API 即可。注意需要至少 API20 的版本才能开启真机调试，如果 API 版本低于 20 则会当作普通的预览小程序。

# 2.7 引入分享SDK或者实现了分享代理后，分享面板没有展示出来

答：由于分享面板默认隐藏，所以在引入分享sdk后，还需要配置 UIConfig 的 hideShareAppletMenu 参数为 false，展示分享面板。

# 2.8 输入框在聚焦时键盘上推位置不正确或者光标位置不正确

答：在鸿蒙端的输入框使用的是同层渲染，且 SDK 内部适配了沉浸式布局，在某些场景下可能会出现键盘上推位置不正确或者光标位置不正确等问题。该问题已与鸿蒙方沟通，反馈规格如此，建议宿主 APP 使用 setWindowLayoutFullScreen() (opens new window) 开启沉浸式布局来规避

# 2.9 小程序页面内容未规避下方导航条

答：由于小程序 SDK 整体适配了沉浸式布局。如果小程序、webview 的 H5 内容（比如自定义 TabBar）想规避下方导航条可以在对应容器添加样式适配。

.page {
  padding-bottom: env(safe-area-inset-bottom);
}

# 2.10 如何给SDK做国际化？

答：SDK已支持国际化，目前支持中文和英文两种语言。如果需要SDK支持其他语言，可以通过如下方式实现：

  1. 根据下图找到项目中的核心SDK @finclip/sdk-core 的所有英文资源文件，如图所示：

  1. 把需要替换的 key 在宿主工程里对应的资源文件里声明可以进行覆盖。

  2. 如果需要扩展其他语言，复制一份资源文件，修改对应的语言，然后把文件放在对应的语言目录下。然后在初始化时，通过 IFinAppConfig 中的 locale 参数指定语言。locale 可以参考 官方文档 (opens new window)。

# 3. 调试方面

# 3.1 如何调试小程序？

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

# 3.2 如何开启vConsole?

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

三种方式开启vConsole:

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

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

appletDebugMode的各个枚举值的作用：

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

注意

  1. 小程序的debug模式会持久化存储，即调用ft.setEnableDebug开启vConsole后，下次打开同一个小程序也会开启vConsole。
  2. 同一个小程序的debug模式一致，即体验版调用ft.setEnableDebug开启vConsole后，打开相同小程序id的正式版，也会开启vConsole。
  3. 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文件、从应用中获取。

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

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

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

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

  1. 从应用中可以通过以下代码来获取 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

# 4.3 兼容 OpenHarmony 吗？需要做什么适配？

答：HarmonyOS 是基于 OpenHarmony 开发，多了些华为提供的服务，比如地图服务、定位服务等。目前我们的 SDK 是基于 HarmonyOS 开发的，无法直接使用。如果您希望在 OpenHarmony 的设备上运行小程序，请联系我们的工作人员，我们可以提供移除依赖华为服务的 SDK（对应功能会不可用）。我们测试过在标准的 OpenHarmony 5.0 以上的版本可以运行（建议 5.1 以上），但由于设备硬件不同、 OpenHarmony 系统可能有做定制化改动等原因，可能会涉及到需要硬件联调的问题。

© FinClip with ❤ , Since 2017