Qt 6.5中的权限API

Permission APIs in Qt 6.5

Qt 6.5中的权限API

January 06, 2023 by Tor Arne Vestbø | Comments

2023年1月6日，Tor Arne Vesbø|评论

Many features of today's devices and operating systems can have significant privacy, security, and performance implications, if misused. As a result, it's increasingly common for platforms to require explicit consent from the user before accessing these features.

如果误用，当今设备和操作系统的许多功能可能会对隐私、安全和性能产生重大影响。因此，平台在访问这些功能之前需要用户明确同意的情况越来越普遍。

With Qt 6.5, we've added cross platform permission APIs, that allow the application to check or request permission for such features, with backend implementations for macOS, iOS, Android, and WebAssembly.

在Qt 6.5中，我们添加了跨平台权限API，允许应用程序检查或请求此类功能的权限，并为macOS、iOS、Android和WebAssembly提供后端实现。

Usage

用法

A feature that commonly requires user consent is access to the microphone of the device. An application for recording voice memos would perhaps look something like this initially:

通常需要用户同意的功能是访问设备的麦克风。用于录制语音备忘录的应用程序最初可能看起来像这样：

void VoiceMemoWidget::onRecordingInitiated()
{
    m_microphone->startRecording();
}

To ensure this application works well on platforms that require user consent for microphone access we would extend it like this:

为了确保此应用程序在需要用户同意才能访问麦克风的平台上运行良好，我们将对其进行如下扩展：

void VoiceMemoWidget::onRecordingInitiated()
{
#if QT_CONFIG(permissions)
    QMicrophonePermission microphonePermission;
    switch (qApp->checkPermission(microphonePermission)) {
    case Qt::PermissionStatus::Undetermined:
        qApp->requestPermission(microphonePermission, this
                    &VoiceMemoWidget::onRecordingInitiated);
        return;
    case Qt::PermissionStatus::Denied:
        m_permissionInstructionsDialog->show();
        return;
    case Qt::PermissionStatus::Granted:
        break; // Proceed
    }
#endif
    m_microphone->startRecording();
}

We first check if we already know the status of the microphone permission. If we don't we initiate a permission request to determine the current status, which will potentially ask the user for consent. We connect the result of the request to the slot we're already in, so that we get another chance at evaluating the permission status.

我们首先检查是否已经知道麦克风权限的状态。如果我们不这样做，我们将启动一个权限请求以确定当前状态，这可能会请求用户同意。我们将请求的结果连接到我们已经进入的插槽，这样我们就有机会评估权限状态。

Once the permission status is known, either because we had been granted or denied permission at an earlier time, or after getting the result back from the request we just initiated, we redirect the user to a dialog explaining why we can not record voice memos at this time (if the permission was denied), or proceed to using the microphone (if permission was granted).

一旦知道了权限状态，或者是因为我们在更早的时候被授予或拒绝了权限，或者是在从我们刚刚发起的请求中得到结果后，我们将用户重定向到一个对话框，解释为什么此时无法录制语音备忘录（如果权限被拒绝），或者继续使用麦克风（如果权限已被授予）。

The use of the QT_CONFIG(permissions) macro ensures that the code will work as before on platforms where permissions are not available.

QT_CONFIG（permissions）宏的使用确保代码在权限不可用的平台上可以像以前一样工作。

Declaring Permissions

声明权限

Some platforms require that the permissions you request are declared up front at build time.

某些平台要求在构建时预先声明请求的权限。

On Apple platforms each permission you request must be accompanied by a so called usage description string in the application's Info.plist file. For example:

在苹果平台上，您请求的每个权限都必须在应用程序的Info.plist文件中附带一个所谓的用法描述字符串。例如：

<key>NSMicrophoneUsageDescription</key>
<string>The microphone is used to record voice memos.</string>

While on Android the permission you request must be accompanied by a uses-permission entry in the application's AndroidManifest.xml file. For example:

在Android上，您请求的权限必须在应用程序的AndroidManifest.xml文件中附带使用权限条目。例如：

<manifest ...>
    <uses-permission android:name="android.permission.RECORD_AUDIO"/>
</manifest>

The relevant permission requirements are described in the documentation for each permission type.

每种权限类型的文档中都描述了相关的权限要求。

Available Permissions

可用权限

The following permissions types are available in Qt 6.5:

Qt 6.5中提供了以下权限类型：

• QBluetoothPermission to access Bluetooth peripherals

• QBluetoothPermission访问蓝牙外围设备的权限

• QCalendarPermission to access the user's calendar

• QCalendarPermission 访问用户日历的权限

• QContactsPermission to access the user's contacts

• QContactsPermission访问用户联系人的权限

• QCameraPermission to access the camera for taking pictures or video

• QCameraPermission访问相机以拍摄照片或视频的权限

• QMicrophonePermission to access the microphone for monitoring or recording sound

• QMicrophonePermission麦克风访问以及监控或录制声音的权限

• QLocationPermission to access the user's location

• QLocationPermission访问用户位置的权限

Best Practices

最佳做法

To ensure the best possible user experience for the end user we recommend adopting the following best practices for managing application permissions:

为了确保最终用户获得最佳用户体验，我们建议采用以下最佳做法来管理应用程序权限：

• Request the minimal set of permissions needed. For example, if you only need access to the microphone, do not request camera permission just in case. Use the properties of individual permission types to limit the permission scope even further, for example QContactsPermission::setReadOnly() to request read only access.

• 请求所需的最小权限集。例如，如果您只需要访问麦克风，请不要请求相机许可，以防万一。使用各个权限类型的属性进一步限制权限范围，例如QContactsPermission:：setReadOnly（）请求只读访问。

• Request permissions in response to specific actions by the user. For example, defer requesting microphone permission until the user presses the button to record audio. Associating the permission request to a specific action gives the user a clearer context of why the permission is needed. Do not request all needed permission on startup.

• 请求权限以响应用户的特定操作。例如，在用户按下按钮录制音频之前，请延迟请求麦克风许可。将权限请求与特定操作相关联，可以让用户更清楚地了解为什么需要权限。不要在启动时请求所有需要的权限。

• Present extra context and explanation if needed. Sometimes the action by the user is not enough context. Consider presenting an explanation-dialog after the user has initiated the action, but before requesting the permission, so the user is aware of what's about to happen when the system permission dialog subsequently pops up.

• 如果需要，提供额外的背景和解释。有时用户的操作不够上下文。考虑在用户启动操作之后，但在请求权限之前，显示一个解释对话框，这样用户就知道当系统权限对话框随后弹出时会发生什么。

• Be transparent and explicit about why permissions are needed. In explanation dialogs and usage descriptions, be transparent about why the particular permission is needed for your application to provide a specific feature, so users can make informed decisions.

• 对需要权限的原因保持透明和明确。在解释对话框和使用说明中，对应用程序提供特定功能需要特定权限的原因保持透明，这样用户就可以做出明智的决定。

• Account for denied permissions. The permissions you request may be denied for various reasons. You should always account for this situation, by gracefully degrading the experience of your application, and presenting clear explanations the user about the situation.

• 拒绝权限的帐户。您请求的权限可能因各种原因而被拒绝。您应该始终考虑这种情况，优雅地降低应用程序的体验，并向用户提供关于这种情况的清晰解释。

• Never request permissions from a library. The request of permissions should be done as close as possible to the user, where the information needed to make good decisions on the points above is available. Libraries can check permissions, to ensure they have the prerequisites for doing their work, but if the permission is undetermined or denied this should be reflected through the library's API, so that the application in turn can request the necessary permissions.

• 不要在库里请求权限。权限请求应尽可能靠近用户，在那里可以获得对上述要点做出正确决策所需的信息。库可以检查权限，以确保它们具备完成工作的先决条件，但如果权限未确定或被拒绝，则应通过库的API反映，以便应用程序依次请求必要的权限。

Future work

下一步工作

For now this API are C++ only, but we're investigating QML APIs that provide the same functionality. We are also looking into adding more permission types down the line.

目前，该API仅为C++，但我们正在研究提供相同功能的QML API。我们也在考虑增加更多的权限类型。

Please try these APIs out in the Qt 6.5 betas, and let us know of any issues you might encounter!

请在Qt 6.5测试版中试用这些API，并告诉我们您可能遇到的任何问题！