Android 14 incluye excelentes funciones y APIs para desarrolladores. La siguiente información te ayudará a obtener información sobre las funciones de tus apps y a comenzar a usar las APIs relacionadas.
Para obtener una lista detallada de las APIs agregadas, modificadas y quitadas, consulta el informe de diferencias de API. Para obtener detalles sobre las APIs agregadas, consulta la referencia de la API de Android. En el caso de Android 14, busca las APIs que se agregaron en el nivel de API 34. Para conocer las áreas en las que los cambios de la plataforma podrían afectar a tus apps, asegúrate de revisar los cambios en el comportamiento de Android 14 para apps orientadas a Android 14 y para todas las apps.
Internacionalización
Preferencias de idioma de las apps
Android 14 扩展了 Android 13(API 级别 33)中引入的按应用设定语言功能,并包含以下额外功能:
自动生成应用的
localeConfig
:从 Android Studio Giraffe Canary 7 和 AGP 8.1.0-alpha07 开始,您可以将应用配置为自动支持各应用语言偏好设定。Android Gradle 插件会根据您的项目资源生成LocaleConfig
文件,并在最终清单文件中添加对该文件的引用,这样您就不再需要手动创建或更新该文件。AGP 使用应用模块的res
文件夹中的资源以及任何库模块依赖项来确定要在LocaleConfig
文件中添加的语言区域。动态更新应用的
localeConfig
:使用LocaleManager
方法中的setOverrideLocaleConfig()
和getOverrideLocaleConfig()
可以在设备的系统设置中动态更新应用的受支持语言列表。有了这种灵活性,您可以按区域自定义支持的语言列表、运行 A/B 实验,或者如果您的应用通过服务器端推送进行本地化,则可以提供更新后的语言区域列表。输入法 (IME) 的应用语言可见性:IME 可以利用
getApplicationLocales()
方法查看当前应用的语言,并将 IME 语言与该语言进行匹配。
API de Grammatical Inflection
Tres mil millones de personas hablan idiomas con género, es decir, idiomas en los que las categorías gramaticales, como sustantivos, verbos, adjetivos y preposiciones, inflexionan según el género de las personas y los objetos con las que te comunicas o sobre los que hablas. Tradicionalmente, muchos idiomas con género usan el género gramatical masculino como el género predeterminado o genérico.
Dirigirse a usuarios con un género gramatical incorrecto, por ejemplo, a mujeres con género gramatical masculino, puede tener un impacto negativo en su rendimiento y actitud. Por el contrario, una IU con un lenguaje que refleja, de forma correcta, el género gramatical del usuario puede mejorar su participación y proporcionar una experiencia más personalizada y más natural.
Para ayudarte a compilar una IU centrada en el usuario para idiomas con inflexión de género, Android 14 introduce la API de Grammatical Inflection, que te permite agregar compatibilidad con el género gramatical sin refactorizar la app.
Preferencias regionales
Regional preferences enable users to personalize temperature units, the first day of the week, and numbering systems. A European living in the United States might prefer temperature units to be in Celsius rather than Fahrenheit and for apps to treat Monday as the beginning of the week instead of the US default of Sunday.
New Android Settings menus for these preferences provide users with a
discoverable and centralized location to change app preferences. These
preferences also persist through backup and restore. Several APIs and
intents—such as
getTemperatureUnit
and
getFirstDayOfWeek
—
grant your app read access to user preferences, so your app can adjust how it
displays information. You can also register a
BroadcastReceiver
on
ACTION_LOCALE_CHANGED
to handle locale configuration changes when regional preferences change.
To find these settings, open the Settings app and navigate to System > Languages & input > Regional preferences.
Accesibilidad
Escalamiento de fuente no lineal al 200%
Starting in Android 14, the system supports font scaling up to 200%, providing low-vision users with additional accessibility options that align with Web Content Accessibility Guidelines (WCAG).
To prevent large text elements on screen from scaling too large, the system applies a nonlinear scaling curve. This scaling strategy means that large text doesn't scale at the same rate as smaller text. Nonlinear font scaling helps preserve the proportional hierarchy between elements of different sizes while mitigating issues with linear text scaling at high degrees (such as text being cut off or text that becomes harder to read due to an extremely large display sizes).
Test your app with nonlinear font scaling
If you already use scaled pixels (sp) units to define text sizing, then these additional options and scaling improvements are applied automatically to the text in your app. However, you should still perform UI testing with the maximum font size enabled (200%) to ensure that your app applies the font sizes correctly and can accommodate larger font sizes without impacting usability.
To enable 200% font size, follow these steps:
- Open the Settings app and navigate to Accessibility > Display size and text.
- For the Font size option, tap the plus (+) icon until the maximum font size setting is enabled, as shown in the image that accompanies this section.
Use scaled pixel (sp) units for text-sizes
Remember to always specify text sizes in sp units. When your app uses sp units, Android can apply the user's preferred text size and scale it appropriately.
Don't use sp units for padding or define view heights assuming implicit padding: with nonlinear font scaling sp dimensions might not be proportional, so 4sp + 20sp might not equal 24sp.
Convert scaled pixel (sp) units
Use TypedValue.applyDimension()
to convert from sp units
to pixels, and use TypedValue.deriveDimension()
to
convert pixels to sp. These methods apply the appropriate nonlinear scaling
curve automatically.
Avoid hardcoding equations using
Configuration.fontScale
or
DisplayMetrics.scaledDensity
. Because font scaling is
nonlinear, the scaledDensity
field is no longer accurate. The fontScale
field should be used for informational purposes only because fonts are no longer
scaled with a single scalar value.
Use sp units for lineHeight
Always define android:lineHeight
using sp units instead
of dp, so the line height scales along with your text. Otherwise, if your text
is sp but your lineHeight
is in dp or px, it doesn't scale and looks cramped.
TextView automatically corrects the lineHeight
so that your intended
proportions are preserved, but only if both textSize
and lineHeight
are
defined in sp units.
Cámara y contenido multimedia
Ultra HDR para imágenes
Android 14 agrega compatibilidad con imágenes de alto rango dinámico (HDR) que retienen más la información del sensor cuando tomas una foto, lo que permite colores y un mayor contraste. Android usa el formato Ultra HDR. que es totalmente retrocompatible con imágenes JPEG, lo que permite que las aplicaciones interoperar con imágenes HDR, mostrándolas en rango dinámico estándar (SDR) como según sea necesario.
El framework renderiza estas imágenes en la IU en HDR automáticamente.
cuando tu app habilita el uso de IU HDR para su ventana de actividad, ya sea mediante una
de registro o durante el tiempo de ejecución llamando a
Window.setColorMode()
También puedes capturar imágenes estáticas Ultra HDR comprimidas en dispositivos compatibles. Con más colores recuperados del sensor, la edición posterior puede ser más flexible. El Gainmap
asociado con las imágenes Ultra HDR se puede usar para renderizarlas con OpenGL o Vulkan.
Zoom, enfoque, vista posterior y mucho más en las extensiones de cámara
Android 14 upgrades and improves camera extensions, allowing apps to handle longer processing times, which enables improved images using compute-intensive algorithms like low-light photography on supported devices. These features give users an even more robust experience when using camera extension capabilities. Examples of these improvements include:
- Dynamic still capture processing latency estimation provides much more
accurate still capture latency estimates based on the current scene and
environment conditions. Call
CameraExtensionSession.getRealtimeStillCaptureLatency()
to get aStillCaptureLatency
object that has two latency estimation methods. ThegetCaptureLatency()
method returns the estimated latency betweenonCaptureStarted
andonCaptureProcessStarted()
, and thegetProcessingLatency()
method returns the estimated latency betweenonCaptureProcessStarted()
and the final processed frame being available. - Support for capture progress callbacks so that apps can display the current
progress of long-running, still-capture processing operations. You can check
if this feature is available with
CameraExtensionCharacteristics.isCaptureProcessProgressAvailable
, and if it is, you implement theonCaptureProcessProgressed()
callback, which has the progress (from 0 to 100) passed in as a parameter. Extension specific metadata, such as
CaptureRequest.EXTENSION_STRENGTH
for dialing in the amount of an extension effect, such as the amount of background blur withEXTENSION_BOKEH
.Postview Feature for Still Capture in camera extensions, which provides a less-processed image more quickly than the final image. If an extension has increased processing latency, a postview image could be provided as a placeholder to improve UX and switched out later for the final image. You can check if this feature is available with
CameraExtensionCharacteristics.isPostviewAvailable
. Then you can pass anOutputConfiguration
toExtensionSessionConfiguration.setPostviewOutputConfiguration
.Support for
SurfaceView
allowing for a more optimized and power-efficient preview render path.Support for tap to focus and zoom during extension usage.
Zoom en el sensor
Cuando REQUEST_AVAILABLE_CAPABILITIES_STREAM_USE_CASE
en CameraCharacteristics
contiene SCALER_AVAILABLE_STREAM_USE_CASES_CROPPED_RAW
, tu app puede usar capacidades avanzadas de sensores para otorgar los mismos píxeles a una transmisión RAW recortada los mismos píxeles que el campo visual completo mediante CaptureRequest
con un objetivo RAW que tenga el caso de uso de transmisión establecido en CameraMetadata.SCALER_AVAILABLE_STREAM_USE_CASES_CROPPED_RAW
.
Cuando se implementan los controles de anulación de solicitudes, la cámara actualizada les brinda a los usuarios control de zoom incluso antes de que estén listos otros controles de la cámara.
Audio USB sin pérdida
Android 14 admite formatos de audio sin pérdida para experiencias de nivel de audiófilo a través de auriculares con cable USB. Puedes consultar un dispositivo USB para obtener sus atributos del mezclador preferidos, registrar un objeto de escucha para los cambios en los atributos preferidos del mezclador y configurar los atributos del mezclador con la clase AudioMixerAttributes
. Esta clase representa el formato, como la máscara de canal, la tasa de muestreo y el comportamiento del mezclador de audio. La clase permite enviar el audio directamente, sin mezclar, ajustar el volumen ni procesar efectos.
Productividad y herramientas para desarrolladores
Credential Manager
En Android 14, se agrega el Administrador de credenciales como una API de la plataforma, con compatibilidad adicional con dispositivos Android 4.4 (nivel de API 19) mediante una biblioteca de Jetpack con los Servicios de Google Play. El Administrador de credenciales tiene como objetivo facilitar el acceso de los usuarios con APIs que recuperan y almacenan credenciales con proveedores de credenciales configurados por el usuario. El Administrador de credenciales admite varios métodos de acceso, incluidos el nombre de usuario y la contraseña, las llaves de acceso y las soluciones de acceso federado (como Acceder con Google) en una sola API.
Las llaves de acceso brindan muchas ventajas. Por ejemplo, las llaves de acceso se compilan según los estándares de la industria, pueden funcionar en diferentes sistemas operativos y ecosistemas de navegador, y se pueden usar con sitios web y apps.
Para obtener más información, consulta la documentación del Administrador de credenciales y las llaves de acceso y la entrada de blog sobre el Administrador de credenciales y las llaves de acceso.
Health Connect
Health Connect es un repositorio integrado en el dispositivo que contiene datos de salud y actividad física de los usuarios. Permite a los usuarios compartir datos entre sus apps favoritas, con un solo lugar para controlar qué datos quieren compartir con estas apps.
En dispositivos con versiones de Android anteriores a Android 14, Health Connect está disponible para descargarse como app en Google Play Store. Primeros pasos con Android 14, Health Connect es parte de la plataforma y recibe actualizaciones a través de Google Reproduce el sistema sin necesidad de realizar una descarga independiente. Con esto, Health Connect se puede actualizar con frecuencia, y tus apps pueden confiar en Health Connect. estén disponibles en dispositivos con Android 14 o versiones posteriores. Los usuarios pueden acceder a Salud Conéctate desde la Configuración de su dispositivo, con controles de privacidad integrados en la configuración del sistema.
Health Connect incluye varias funciones nuevas en Android 14, como el ejercicio de entrenamiento, lo que les permite a los usuarios compartir una ruta de su entrenamiento que se puede visualizar en un mapa. Una ruta se define como una lista de ubicaciones guardadas dentro de una ventana de y tu app puede insertar rutas en sesiones de ejercicio y vincularlas entre sí. Para garantizar que los usuarios tengan control total sobre estos datos sensibles, los usuarios deben permitir compartir rutas individuales con otras apps.
Para obtener más información, consulta la Documentación de Health Connection y la entrada de blog sobre Novedades de Salud de Android.
Actualizaciones de OpenJDK 17
Android 14 continúa la tarea de actualizar las bibliotecas principales de Android para alinearlas con las funciones de las versiones más recientes de LTS de OpenJDK, lo que incluye las actualizaciones de bibliotecas y la compatibilidad con el lenguaje Java 17 para desarrolladores de apps y plataformas.
Se incluyen las siguientes funciones y mejoras:
- Se actualizaron aproximadamente 300 clases
java.base
a la compatibilidad con Java 17. - Bloques de texto, que introducen literales de cadena de varias líneas en el lenguaje de programación Java.
- Pattern Matching for instanceof, que permite que un objeto se trate como si tuviera un tipo específico en una
instanceof
sin variables adicionales. - Clases selladas, que te permiten restringir qué interfaces y clases pueden extenderlas o implementarlas
Gracias a las actualizaciones del sistema de Google Play (Project Mainline), más de 600 millones de dispositivos están habilitados para recibir las actualizaciones más recientes de Android Runtime (ART) que incluyen estos cambios. Esto es parte de nuestro compromiso de proporcionar a las apps un entorno más seguro y coherente en todos los dispositivos, y de ofrecer funciones y capacidades nuevas a los usuarios, independientemente de las versiones de la plataforma.
Java y OpenJDK son marcas o marcas registradas de Oracle o sus afiliados.
Mejoras para tiendas de aplicaciones
Android 14 introduces several PackageInstaller
APIs that
allow app stores to improve their user experience.
Request install approval before downloading
Installing or updating an app might require user approval.
For example, when an installer making use of the
REQUEST_INSTALL_PACKAGES
permission attempts to install a
new app. In prior Android versions, app stores can only request user approval
after APKs are written to the install session and the
session is committed.
Starting with Android 14, the requestUserPreapproval()
method lets installers request user approval before committing the install
session. This improvement lets an app store defer downloading any APKs until
after the installation has been approved by the user. Furthermore, once a user
has approved installation, the app store can download and install the app in the
background without interrupting the user.
Claim responsibility for future updates
The setRequestUpdateOwnership()
method allows an installer
to indicate to the system that it intends to be responsible for future updates
to an app it is installing. This capability enables update ownership
enforcement, meaning that only the update owner is permitted
to install automatic updates to the app. Update ownership enforcement helps to
ensure that users receive updates only from the expected app store.
Any other installer, including those making use of the
INSTALL_PACKAGES
permission, must receive explicit user
approval in order to install an update. If a user decides to proceed with an
update from another source, update ownership is lost.
Update apps at less-disruptive times
App stores typically want to avoid updating an app that is actively in use because this leads to the app's running processes being killed, which potentially interrupts what the user was doing.
Starting with Android 14, the InstallConstraints
API
gives installers a way to ensure that their app updates happen at an opportune
moment. For example, an app store can call the
commitSessionAfterInstallConstraintsAreMet()
method to
make sure that an update is only committed when the user is no longer
interacting with the app in question.
Seamlessly install optional splits
With split APKs, features of an app can be delivered in separate APK files,
rather than as a monolithic APK. Split APKs allow app stores to optimize the
delivery of different app components. For example, app stores might optimize
based on the properties of the target device. The
PackageInstaller
API has supported splits since its
introduction in API level 22.
In Android 14, the setDontKillApp()
method allows an
installer to indicate that the app's running processes shouldn't be killed when
new splits are installed. App stores can use this feature to seamlessly install
new features of an app while the user is using the app.
Paquetes de metadatos de la app
Starting in Android 14, the Android package installer lets you specify app metadata, such as data safety practices, to include on app store pages such as Google Play.
Detecta cuando los usuarios toman capturas de pantalla del dispositivo
Para crear una experiencia más estandarizada para detectar capturas de pantalla, Android 14 presenta una API de detección de capturas de pantalla que preserva la privacidad. Esta API permite que las apps registren devoluciones de llamada por actividad. Estas devoluciones de llamada se invocan, y el usuario recibe una notificación cuando toma una captura de pantalla mientras esa actividad está visible.
Experiencia del usuario
Acciones personalizadas y clasificación mejorada de Sharesheet
Android 14 actualiza la hoja compartida del sistema para admitir acciones personalizadas de la app y resultados informativos de la versión preliminar para los usuarios.
Agrega acciones personalizadas
Con Android 14, tu app puede hacer lo siguiente: agregar acciones personalizadas a la hoja compartida del sistema que invoca.
Mejora la clasificación de los objetivos de Direct Share
Android 14 usa más indicadores de las apps para determinar la clasificación de los objetivos de Direct Share para proporcionarles resultados más útiles al usuario. Para proporcionar los indicadores más útiles para la clasificación, sigue las instrucciones para cómo mejorar las clasificaciones de tus objetivos de Direct Share. Las apps de comunicación también pueden informar el uso de combinaciones de teclas para lo siguiente: los mensajes entrantes y salientes.
Compatibilidad con animaciones integradas y personalizadas para el gesto atrás predictivo
Android 13 在开发者选项背后引入了预测性“返回主屏幕”动画。在已启用开发者选项的受支持应用中使用时,滑回手势会显示动画,表明返回手势会使应用退回到主屏幕。
Android 14 包含针对“预测性返回”的多项改进和新指南:
- 您可设置
android:enableOnBackInvokedCallback=true
,以便为每个 activity 选择启用预测性返回系统动画,而不是为整个应用选择启用。 - 我们添加了新的系统动画,以配合 Android 13 中的“返回主屏幕”动画。新的系统动画是跨 activity 和跨任务的,您可在迁移到预测性返回后自动获得该动画。
- 我们为底部动作条、侧边动作条和搜索添加了新的 Material 组件动画。
- 我们制作了有关如何创建自定义应用内动画和转换的设计指南。
- 我们添加了许多新 API 来支持自定义的应用内转换动画:
在此 Android 14 预览版中,所有预测性返回功能都是位于开发者选项背后。请参阅与将您的应用迁移到预测性返回有关的开发者指南,以及与创建自定义应用内转换有关的开发者指南。
Anulaciones por app del fabricante de dispositivos con pantalla grande
Las anulaciones por app permiten que los fabricantes de dispositivos cambien el comportamiento de las apps en dispositivos con pantallas grandes. Por ejemplo, la anulación FORCE_RESIZE_APP
le indica al sistema que cambie el tamaño de la app para que se ajuste a las dimensiones de la pantalla (evitando el modo de compatibilidad de tamaño) incluso si se configuró resizeableActivity="false"
en el manifiesto de la app.
Las anulaciones están diseñadas para mejorar la experiencia del usuario en pantallas grandes.
Las nuevas propiedades del manifiesto te permiten inhabilitar algunas anulaciones del fabricante de dispositivos para tu app.
Anulaciones por app para usuarios de pantallas grandes
Per-app overrides change the behavior of apps on large screen devices. For example, the OVERRIDE_MIN_ASPECT_RATIO_LARGE
device manufacturer override sets the app aspect ratio to 16:9 regardless of the app's configuration.
Android 14 QPR1 enables users to apply per‑app overrides by means of a new settings menu on large screen devices.
Compartir pantalla de una app
La función para compartir pantalla de la app permite que los usuarios compartan una ventana de la app en lugar de toda la pantalla del dispositivo durante la grabación del contenido de la pantalla.
Cuando se comparte la pantalla de la app, la barra de estado, la barra de navegación, las notificaciones y otros elementos de la IU del sistema se excluyen de la pantalla compartida. Solo se comparte el contenido de la app seleccionada.
La función para compartir pantalla en las apps mejora la productividad y la privacidad, ya que permite que los usuarios ejecuten varias apps, pero limita el uso compartido de contenido a una sola app.
Respuesta inteligente potenciada por LLM en Gboard en el Pixel 8 Pro
En los dispositivos Pixel 8 Pro con la Actualización de funciones de diciembre, los desarrolladores pueden probar respuestas inteligentes de mayor calidad en Gboard con la tecnología de los modelos grandes de lenguaje (LLM) integrados en el dispositivo que se ejecutan en Google Tensor.
Esta función está disponible en una vista previa limitada para inglés de EE.UU. en WhatsApp, Line y KakaoTalk. Requiere el uso de un dispositivo Pixel 8 Pro con Gboard como teclado.
Para probarla, primero habilita la función en Configuración > Opciones para desarrolladores > Configuración de AICore > Habilitar Aicore Persistent.
A continuación, abre una conversación en una app compatible para ver la Respuesta inteligente con tecnología de LLM en la barra de sugerencias de Gboard en respuesta a los mensajes entrantes.
Gráficos
Las rutas de acceso son interpolables y consultables
La API de Path
de Android es un mecanismo potente y flexible para crear y renderizar gráficos vectoriales, con la capacidad de dibujar o rellenar una ruta, construir una ruta a partir de segmentos de línea o curvas cuadráticas o cúbicas, realizar operaciones booleanas para obtener formas aún más complejas o todas estas acciones de forma simultánea. Una limitación es la capacidad de descubrir lo que hay realmente en un objeto Path; los componentes internos del objeto son opacos para los llamadores después de su creación.
Para crear un Path
, debes llamar a métodos como moveTo()
, lineTo()
y cubicTo()
para agregar segmentos de ruta. Sin embargo, no hay forma de preguntarle a esa ruta cuáles son los segmentos, por lo que debes conservar esa información en el momento de la creación.
A partir de Android 14, puedes consultar rutas de acceso para descubrir su contenido.
Primero, debes obtener un objeto PathIterator
con la API de Path.getPathIterator
:
Kotlin
val path = Path().apply { moveTo(1.0f, 1.0f) lineTo(2.0f, 2.0f) close() } val pathIterator = path.pathIterator
Java
Path path = new Path(); path.moveTo(1.0F, 1.0F); path.lineTo(2.0F, 2.0F); path.close(); PathIterator pathIterator = path.getPathIterator();
A continuación, puedes llamar a PathIterator
para iterar a través de los segmentos uno por uno y recuperar todos los datos necesarios de cada segmento. En este ejemplo, se usan objetos PathIterator.Segment
, que agrupan los datos por ti:
Kotlin
for (segment in pathIterator) { println("segment: ${segment.verb}, ${segment.points}") }
Java
while (pathIterator.hasNext()) { PathIterator.Segment segment = pathIterator.next(); Log.i(LOG_TAG, "segment: " + segment.getVerb() + ", " + segment.getPoints()); }
PathIterator
también tiene una versión de next()
no asignable en la que puedes pasar un búfer para contener los datos de puntos.
Uno de los casos de uso importantes para consultar datos de Path
es la interpolación. Por ejemplo, podrías animar (o transformar) entre dos rutas diferentes. Para simplificar aún más ese caso de uso, Android 14 también incluye el método interpolate()
en Path
. Si suponemos que las dos rutas de acceso tienen la misma estructura interna, el método interpolate()
crea un Path
nuevo con ese resultado interpolado. En este ejemplo, se muestra una ruta cuya forma está incompleta (una interpolación lineal de 0.5) entre path
y otherPath
:
Kotlin
val interpolatedResult = Path() if (path.isInterpolatable(otherPath)) { path.interpolate(otherPath, .5f, interpolatedResult) }
Java
Path interpolatedResult = new Path(); if (path.isInterpolatable(otherPath)) { path.interpolate(otherPath, 0.5F, interpolatedResult); }
La biblioteca graphics-path de Jetpack también habilita APIs similares para versiones anteriores de Android.
Mallas personalizadas con sombreadores de vértices y fragmentos
Desde hace mucho tiempo, Android admite el dibujo de mallas triangulares con sombreado personalizado, pero el formato de malla de entrada se limitó a unas pocas combinaciones de atributos predefinidas. En Android 14, se agrega compatibilidad con mallas personalizadas, que se pueden definir como triángulos o rayas triangulares y, de forma opcional, se pueden indexar. Estas mallas se especifican con atributos personalizados, segmentos de vértices, variaciones y sombreadores de vértices y fragmentos escritos en AGSL.
El sombreador de vértices define las variaciones, como la posición y el color, mientras que, de manera opcional, el sombreador de fragmentos puede definir el color del píxel, por lo general, mediante las variaciones creadas por el sombreador de vértices. Si el sombreador de fragmentos proporciona color, este se combina con el color Paint
actual a través del modo de combinación seleccionado cuando dibujes la malla. Se pueden pasar uniformes a los sombreadores de fragmentos y vértices para obtener flexibilidad adicional.
Renderizador de búfer de hardware para Canvas
协助使用 Android 的 Canvas
API 通过
硬件加速至 HardwareBuffer
、Android 14
引入了 HardwareBufferRenderer
。如果您的用例涉及通过 SurfaceControl
与系统合成器通信以实现低延迟绘制,此 API 特别有用。