This page is translated by Google Cloud Translation API

Switch to Chinese

iOS native app configuration files and resources

App packaging provides configuration Info.plist and Bundle Resources in iOS native development. Common items are encapsulated in uni-app, and manifest.json is provided.

But manifest.json cannot contain all iOS configuration.

Before HBuilderX 3.6.5, developers could only package or develop [App native language plug-ins](https://nativesupport.dcloud .net.cn/NativePlugin/README).

Starting from HBuilderX3.6.5, it supports directly configuring the Info.plist and resource files (Bundle Resources) of the iOS platform in the application project.

配置文件 Info.plist

Info.plist文件是 XCode 工程配置文件，可在HBuilderX中项目中添加Info.plist文件，云端打包后将会合并到 XCode 工程生成 ipa。

Edit and add the required content according to the application requirements, as shown in the following example:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>My_Custom_String_Key</key>
    <string>My_Custom_String_Value</string>
    <key>My_Custom_Array_Key</key>
    <array>
      <dict>
        <key>My_Custom_Array_Item_Key</key>
        <string>My_Custom_Array_Item_Value</string>
        <key>My_Custom_Array_Item_Key2</key>
        <string>My_Custom_Array_Item_Value2</string>
      </dict>
    </array>
  </dict>
</plist>

Notice

• The plist file must conform to the standard xml format
• The plist file must conform to the Apple Information Property List specification, refer to Details
  • The file header needs to add <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
  • The root node must be a plist, and the secondary node must be a dict
• The content of Info.plist and the content of manifest.json should avoid conflict, that is, the content that has been configured in the manifest should not be configured. When packaged in the cloud, it will be merged into the Info.list file in the app. When there is a conflict, the content of the Info.plist will overwrite the configuration in manifest.json
• The plist file configuration can only take effect after submitting the cloud package. Please use the [custom debugging base] when the real machine is running (https://ask.dcloud.net.cn/article/35115)

iOS隐私信息访问描述配置

如果应用需要修改隐私信息访问的许可描述，可根据需求在Info.plist文件中添加，如下示例：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>NSPhotoLibraryUsageDescription</key>
    <string>读取相册的许可描述</string>
    <key>NSPhotoLibraryAddUsageDescription</key>
    <string>读写相册的许可描述</string>
    <key>NSCameraUsageDescription</key>
    <string>使用摄像头的许可描述</string>
    <key>NSMicrophoneUsageDescription</key>
    <string>使用麦克风的许可描述</string>
    <key>NSLocationWhenInUseUsageDescription</key>
    <string>运行期访问位置信息的许可描述</string>
    <key>NSLocationAlwaysUsageDescription</key>
    <string>后台运行期访问位置信息的许可描述</string>
    <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
    <string>访问位置信息的许可描述</string>
    <key>NSUserNotificationsUsageDescription</key>
    <string>使用推送通知的许可描述</string>
    <key>NSCalendarsUsageDescription</key>
    <string>访问日历的许可描述</string>
    <key>NSContactsUsageDescription</key>
    <string>访问通讯录的许可描述</string>
    <key>NSBluetoothPeripheralUsageDescription</key>
    <string>使用蓝牙的许可描述</string>
    <key>NSBluetoothAlwaysUsageDescription</key>
    <string>持续使用蓝牙的许可描述</string>
    <key>NSSpeechRecognitionUsageDescription</key>
    <string>使用系统语音识别的许可描述</string>
    <key>NSRemindersUsageDescription</key>
    <string>访问提醒事项的许可描述</string>
    <key>NSMotionUsageDescription</key>
    <string>访问运动与健身的许可描述</string>
    <key>NSHealthUpdateUsageDescription</key>
    <string>更新健康数据的许可描述</string>
    <key>NSHealthShareUsageDescription</key>
    <string>分享健康数据的许可描述</string>
    <key>NSAppleMusicUsageDescription</key>
    <string>访问媒体资料库的许可描述</string>
    <key>NFCReaderUsageDescription</key>
    <string>使用NFC的许可描述</string>
    <key>NSHealthClinicalHealthRecordsShareUsageDescription</key>
    <string>访问临床记录信息的许可描述</string>
    <key>NSHomeKitUsageDescription</key>
    <string>访问HomeKit数据的许可描述</string>
    <key>NSSiriUsageDescription</key>
    <string>访问Siri的许可描述</string>
    <key>NSFaceIDUsageDescription</key>
    <string>使用FaceID的许可描述</string>
    <key>NSLocalNetworkUsageDescription</key>
    <string>使用本地网络的许可描述</string>
    <key>NSUserTrackingUsageDescription</key>
    <string>跟踪用户活动的许可描述</string>
  </dict>
</plist>

注意
uni-app x项目manifest.json中没有提供iOS隐私信息访问许可描述的配置，需在此Info.plist中添加。
配置许可描述时需根据应用实际情况准确描述用途，否则提交AppStore审核可能被拒。

• NSUserNotificationsUsageDescription
  使用消息推动通知的许可描述是可选配置，不配置此字段（不包含NSUserNotificationsUsageDescription）也可以通过AppStore审核；如果配置了此字段则需正确描述应用使用消息通知的用途才能通过AppStore审核。

相关参考

• iOS隐私信息访问列表，参考：https://developer.apple.com/documentation/bundleresources/information_property_list/protected_resources

iOS url scheme配置

如果应用需要向系统注册url scheme，以便在浏览器中通过scheme打开App，可根据需求在Info.plist文件中添加CFBundleURLTypes数据，如下示例：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>CFBundleURLTypes</key>
    <array>
      <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>scheme</string>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>myappuniappx</string>
        </array>
      </dict>
    </array>
  </dict>
</plist>

uni-app/uni-app x项目都支持通过此方式配置url scheme，uni-app项目还可通过manifest.json的可视化界面配置，参考iOS设置url scheme

注意

• CFBundleURLSchemes字段下的字符串数组项是需要注册的scheme值，上面示例配置了myappuniappx，请根据应用实际需求修改，array可添加多个string项配置多个scheme值。为了避免与其他应用产生冲突，请配置自己应用特有的字符串来避免冲突。
• CFBundleURLName字段下的字符串是这组url scheme的标识，建议按上面示例的默认值配置即可，如需修改请参考苹果官方文档。
• CFBundleTypeRole字段下的字符串是固定值，不要修改。

相关参考

• iOS Property List Key ‘CFBundleURLTypes’，参考：https://developer.apple.com/documentation/bundleresources/information_property_list/cfbundleurltypes/

应用可支持横竖屏列表配置

应用默认可支持的横竖列表：

• uni-app 项目由 manifest.json 中的 screenOrientation 字段配置决定
• uni-app x 项目默认可支持横竖屏列表为横屏和竖屏，但运行期在 iPhone 设备默认为竖屏，在 iPad 设备根据系统设置自动感应适配横竖屏，HBuilderX4.25版本iPhone设备支持screenOrientation 字段配置

如果希望自定义配置应用可支持的横竖屏列表，可根据需求在Info.plist文件中添加UISupportedInterfaceOrientations数据，如下示例：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>UISupportedInterfaceOrientations~iphone</key>
    <array>
      <string>UIInterfaceOrientationPortrait</string>
      <string>UIInterfaceOrientationLandscapeLeft</string>
      <string>UIInterfaceOrientationLandscapeRight</string>
    </array>
    <key>UISupportedInterfaceOrientations~ipad</key>
    <array>
      <string>UIInterfaceOrientationPortrait</string>
      <string>UIInterfaceOrientationPortraitUpsideDown</string>
      <string>UIInterfaceOrientationLandscapeLeft</string>
      <string>UIInterfaceOrientationLandscapeRight</string>
    </array>
  </dict>
</plist>

uni-app 项目同时也支持在 manifest.json 中配置 screenOrientation，云端打包会与 Info.plist 中配置的值合并
uni-app x 项目仅支持 Info.plist 中配置，需 HBuilderX4.22+ 版本，提交云端打包后才能生效

注意

• UISupportedInterfaceOrientations~iphone 字段下配置的是 iPhone 设备可支持的横竖屏
• UISupportedInterfaceOrientations~ipad 字段下配置的是 iPad 设备可支持的横竖屏
• 字段值为字符串数组，其中字符串可取值：
  • UIInterfaceOrientationPortrait 竖屏主方向
  • UIInterfaceOrientationPortraitUpsideDown 竖屏反方向，仅 iPad 设备支持
  • UIInterfaceOrientationLandscapeLeft 横屏主方向
  • UIInterfaceOrientationLandscapeRight 横屏反方向
• iPhone 和 iPad 设备可分别单独设置，可支持的横竖屏列表会限制应用能支持的横竖屏状态，如设置应用支持的横竖屏列表值为竖屏（UIInterfaceOrientationPortrait），则应用在任何状态下都无法横屏。

应用资源

Enter the name nativeResources (note that it is case-sensitive), confirm and create a directory.

• Resources，用于保存Bundle资源的目录
• UniApp.entitlements，用于配置工程Capabilities的文件

配置文件UniApp.entitlements

在 XCode 中可以通过项目可视化界面编辑应用的Capabilities，实际上是操作项目的 entitlements 和 Info.plist 文件保存数据。在 HBuilderX 中暂未提供Capabilities可视化界面操作，需手动编辑UniApp.entitlements和Info.plist文件来实现相关配置。

在 nativeResources/ios 目录下创建UniApp.entitlements文件，用于配置 XCode 原生工程的Capabilities，如下示例：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
  </dict>
</plist>

uni-app/uni-app x 项目可以通过编辑UniApp.entitlements文件配置Capabilities，需确保此entitlements文件格式正确，可以在 XCode 中编辑验证此文件。

注意

• plist文件必须符合标准的xml格式
• plist文件必须符合Apple Information Property List规范，参考详情
  • 文件头需加<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
  • 根节点必须是plist，二级节点必须是dict
• UniApp.entitlements的内容只能用于配置 Capabilities，不能添加自定义数据

相关参考

• Adding capabilities to your app，参考：https://developer.apple.com/documentation/xcode/adding-capabilities-to-your-app

配置Associated Domains

在UniApp.entitlements添加com.apple.developer.associated-domains节点数据开启Associated Domains能力

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>com.apple.developer.associated-domains</key>
	<array>
		<string>applinks:demo.dcloud.net.cn</string>
	</array>
</dict>
</plist>

注意

• com.apple.developer.associated-domains字段值类型必须是字符串数组
• 上面示例中applinks:demo.dcloud.net.cn配置的是通用链接域名，其中applinks:表示此域名用于通用链接，demo.dcloud.net.cn是域名，请修改为应用自己使用的域名
• array节点下可添加多个关联域名
• iOS平台完整配置通用链接参考文档：配置通用链接（Universal Link）

相关参考

• Configuring an associated domain，参考：https://developer.apple.com/documentation/xcode/configuring-an-associated-domain

配置文件PrivacyInfo.xcprivacy

PrivacyInfo.xcprivacy用于配置应用隐私清单文件，详情参考uni-app/uni-app x如何配置隐私清单。

Bundle资源目录 （Bundle Resources）

将需要添加的iOS原生资源文件拷贝到Resources目录，云端打包时将会合并到安装包的.app中。

Notice

• ios目录下不支持放Object-C/Swift源码文件，需要开发源码建议使用UTS插件或uni原生语言插件
• resources目录中的资源文件不能通过uni API使用，需通过 iOS 原生 API 访问，参考Accessing a Bundle's Contents。也就是在uni-app/uni-app x项目中这些资源需要通过uts代码访问，uni-app项目也可编写uni原生语言插件访问
• resources目录中已经保留使用以下文件，需注意避免冲突
  • uni-app/5+ App 项目
    
    ├─Pandora //uni-app资源目录 │ └─apps //应用资源目录 │ └─[AppID] //使用DCloud AppID作为目录名称 ├─PandoraApi.bundle //uni-app SDK内置资源目录 ├─control.xml //uni-app模块配置文件 ├─dcloud_logo@2x.png //应用logo图片 ├─dcloud_logo@3x.png //应用logo图片 ├─uni-jsframework.js //uni-app vue2框架 ├─uni-jsframework-vue3.js //uni-app vue3框架 ├─uni-jsframework-dev.js //uni-app vue2框架（开发模式） ├─uni-jsframework-vue3-dev.js //uni-app vue3框架（开发模式） ├─unincomponents.ttf //uni-app内置字体图标 └─userPosition@2x.png //地图模块当前位置图标
  • uni-app x 项目
    
    ├─uni-app-x //uni-app x 项目资源 ├─DCUniVideo //video组件目录 ├─uni_uts_toast_error.png //uni.showToast 使用的图标 └─uni_uts_toast_success.png //uni.showToast 使用的图标
• 应用资源目录配置需提交云端打包后才能生效，真机运行时请使用自定义调试基座

Watch 目录

HBuilderX 4.71 及以上版本新增支持嵌入 Watch App

uni-app/uni-app x 本身还不支持直接用于开发 Watch App。如果已经存在使用 XCode 开发完成的 Watch App，可以将其添加到使用 uni-app/uni-app x 开发的主应用中，提交云端打包即可嵌入到 ipa 中提交。

在 uni-app/uni-app x 项目原生资源目录 “nativeResources” 的 “ios” 目录下创建 “Watch”子目录，并添加 Watch App 二级制文件，结构如下：

  
├─nativeResources       // App原生资源目录
│  └─ios                  // iOS平台目录
│    ├─Resources            //资源文件存放目录，可选
│    ├─Watch                //Watch App目录，可选
│    │  └─myWatchApp.app      //需要添加的 Watch App 二进制文件
│    ├─ios-watch.json       //Watch App 配置文件，可选
│    └─info.plist           //应用主 info.plist 配置文件，可选
└─manifest.json         // uni-app/uni-appx 项目清单文件  

myWatchApp.app

uni-app/uni-app x 中要添加的 Watch App 可执行文件。
需在原生 XCode 环境中添加 Watch Target，选择 “Watch App for Existing iOS App”，并在 XCode 中完成开发调试后编译并以发布方式导出包含此 Watch App 的 ipa 包，将 ipa 解压后在 Payload/XXX.app/Watch/ 目录下可以找到对应的 .app 文件。
将此 .app 文件添加到如上所示 uni-app/uni-app x 项目的 nativeResources -> ios -> Watch 目录中。

ios-watch.json

可选配置文件，仅在需要配置 Watch App 的包名和profile文件时使用，格式如下：

{
  "myWatchApp.app": {
    "identifier": "com.my.app.watch",
    "profile": "embedded.mobileprovision"
  }
}

• myWatchApp.app
  Watch App 文件名称，与添加到 nativeResources -> ios -> Watch 目录中的 .app 文件名称一致
• identifier
  打包时 Watch App 使用的 Bundle identifier，如不设置则默认使用 profile 文件中的绑定的 Bundle identifier，如果 profile 绑定的值使用了通配符则使用 Watch app 中配置的值
  注意：Watch App 的 Bundle identifier
• profile
  打包时使用的 Provisioning Profile，相对于ios-watch.json文件所在目录的路径

Offline packaging

When packaging offline, the application manifest file and resources need to be manually merged into the XCode native project by the developer.