本地认证

使用 Flutter 的 local_auth 包，通过生物识别、PIN、密码或图案在设备上对用户进行认证。

如果要存储受生物识别保护的密钥，请参阅 SecureStorage。

平台支持

平台	Windows	macOS	Linux	iOS	Android	Web
支持	✅	✅	❌	✅	✅	❌

设置

iOS 和 macOS

使用 biometric 权限包或 [tool.flet.ios.info] / [tool.flet.macos.info] 添加 Face ID 使用说明：

[tool.flet]
permissions = ["biometric"]

Android

USE_BIOMETRIC 由 local_auth 插件声明并自动合并。Flet 应用默认使用 FlutterFragmentActivity 以及 AppCompat 的 LaunchTheme / NormalTheme。

用法

将 flet-local-auth 添加到项目依赖中：

uv

uv add flet-local-auth

pip

pip install flet-local-auth  [^1]

[^1]: 完成上述操作后，你还需要手动将此包添加到你的 requirements.txt 或 pyproject.toml 中。

示例

import flet as ft
import flet_local_auth as auth


def main(page: ft.Page):
    status = ft.Text(theme_style=ft.TextThemeStyle.TITLE_MEDIUM)
    local_auth = auth.LocalAuthentication()

    async def refresh_capabilities(_):
        supported = await local_auth.is_device_supported()
        can_check = await local_auth.can_check_biometrics()
        biometrics = await local_auth.get_available_biometrics()
        status.value = (
            f"Device supported: {supported}\n"
            f"Biometric hardware: {can_check}\n"
            f"Enrolled biometrics: {', '.join(b.value for b in biometrics) or 'none'}"
        )

    async def authenticate(_):
        try:
            ok = await local_auth.authenticate(
                "Authenticate to continue",
                android_messages=auth.AndroidAuthMessages(
                    sign_in_title="Unlock",
                    cancel_button="Not now",
                ),
            )
            status.value = f"Authenticated: {ok}"
        except auth.LocalAuthException as e:
            status.value = f"Authentication failed: {e.code.value}"

    page.add(
        ft.SafeArea(
            content=ft.Column(
                spacing=16,
                controls=[
                    ft.Container(
                        bgcolor=ft.Colors.SURFACE_CONTAINER_HIGHEST,
                        border_radius=12,
                        padding=16,
                        content=status,
                    ),
                    ft.Button("Check capabilities", on_click=refresh_capabilities),
                    ft.Button("Authenticate", on_click=authenticate),
                ],
            ),
        )
    )


if __name__ == "__main__":
    ft.run(main)

描述

LocalAuthentication 继承自：Service, BaseControl

使用设备上的生物识别或设备凭据对用户进行认证。

平台支持

支持 Android、iOS、macOS 和 Windows。不支持 Linux 或 Web。

抛出异常： FletUnsupportedPlatformException：如果平台不受支持。 LocalAuthException：如果认证失败。

属性

名称	类型	默认值	说明
data	Any	skip_	任意类型的自定义数据。
key	Optional['KeyValue']	None	用于在更新之间保持控件标识稳定的键。

只读属性

名称	类型	默认值	说明
parent	Optional['BaseControl']	—	此控件的直接祖先（父级）。 默认为 None，只有在此控件被挂载（加入页面树）后才有值。 Page 控件（页面树的根）是个例外 —— 它的 parent 始终为 None。
page	'Page'	—	此控件所属的页面。

方法

名称	类型	默认值	说明
before_update	—	—	—
is_device_supported	bool	—	返回设备是否可以使用生物识别或凭据进行认证。
can_check_biometrics	bool	—	返回设备是否有可用的生物识别硬件。
get_available_biometrics	list[BiometricType]	—	返回设备上当前已录入的生物识别方式。
authenticate	bool	—	提示用户进行本地认证。 参数： reason：系统认证对话框中显示的消息。 biometric_only：是否只允许生物识别认证。 sensitive_transaction：是否将此次交易视为敏感交易。 persist_across_backgrounding：如果认证被中断，是否在应用重新回到 前台后重试。 android_messages：可选的 Android 对话框自定义。 ios_messages：可选的 iOS 对话框自定义。 windows_messages：可选的 Windows 对话框自定义。 返回： 认证成功时返回 True。 抛出异常： LocalAuthException：如果认证失败或被取消。
stop_authentication	bool	—	取消任何正在进行的认证提示。 返回： 如果认证被成功取消则返回 True。
init	—	—	—
is_isolated	—	—	返回此控件是否被标记为隔离。 隔离控件会被排除在父级驱动的更新遍历之外，并需要自行管理更新边界。
build	—	—	在控件初始化期间调用一次，用于定义其子控件。在此方法中 page 属性可用。
before_event	—	—	在事件处理器执行之前拦截事件。 返回 False 可取消分发。返回 True 或 None 则继续正常的事件处理。
did_mount	—	—	在控件挂载到页面树之后调用。 重写此方法以启动需要已挂载页面的资源，例如订阅、定时器或服务监听器。
will_unmount	—	—	在控件从页面树移除之前调用。 重写此方法以释放 did_mount() 中创建的资源，例如订阅、定时器或外部句柄。
get_data_channel	—	—	解析为此 widget 在 Dart 侧分配的 [DataChannel]。模式： on_data_channel_open: Optional[ft.EventHandler[DataChannelOpenEvent]] = None def init(self): self.on_data_channel_open = self._on_open def _on_open(self, e): self._channel = self.get_data_channel(e.channel_id) 幂等 —— 底层的 Connection 会按 id 缓存 DataChannel，因此重复调用会返回同一实例。没有错误路径：该 id 始终来自框架触发的事件，所以当此方法运行时，通道在两端都已存在。
update	None	—	为此控件请求一次 UI 更新。 在更改控件状态或属性后调用。控件必须已挂载到页面且未被标记为冻结。