Ringkasan Fitur dan API

Android 14 memperkenalkan fitur dan API yang hebat untuk developer. Berikut ini bantuan untuk mempelajari fitur-fitur yang tersedia untuk aplikasi Anda, serta mulai menggunakan API yang terkait.

Untuk melihat daftar mendetail tentang API yang ditambahkan, diubah, dan dihapus, baca laporan perbedaan API. Untuk mengetahui detail tentang API yang ditambahkan, buka referensi API Android — untuk Android 14, cari API yang ditambahkan di API level 34. Untuk mempelajari area tempat perubahan platform dapat memengaruhi aplikasi Anda, pastikan untuk memeriksa perubahan perilaku Android 14 untuk aplikasi yang menargetkan Android 14 dan untuk semua aplikasi.

Internasionalisasi

Preferensi bahasa per aplikasi

Android 14 memperluas fitur bahasa per aplikasi yang diperkenalkan di Android 13 (API level 33) dengan kemampuan tambahan berikut:

  • Otomatis membuat localeConfig aplikasi: Mulai dari Android Studio Giraffe Canary 7 dan AGP 8.1.0-alpha07, Anda dapat mengonfigurasi aplikasi untuk mendukung preferensi bahasa per aplikasi secara otomatis. Berdasarkan resource project, plugin Android Gradle menghasilkan file LocaleConfig dan menambahkan referensi ke file tersebut dalam file manifes akhir, sehingga Anda tidak perlu lagi membuat atau memperbarui file secara manual. AGP menggunakan resource dalam folder res modul aplikasi Anda dan dependensi modul library apa pun untuk menentukan lokalitas yang akan disertakan dalam file LocaleConfig.

  • Update dinamis untuk localeConfig aplikasi: Gunakan metode setOverrideLocaleConfig() dan getOverrideLocaleConfig() di LocaleManager untuk memperbarui secara dinamis daftar bahasa yang didukung aplikasi Anda di setelan sistem perangkat. Gunakan fleksibilitas ini untuk menyesuaikan daftar bahasa yang didukung per region, menjalankan eksperimen A/B, atau memberikan daftar lokalitas yang diupdate jika aplikasi Anda menggunakan push sisi server untuk pelokalan.

  • Visibilitas bahasa aplikasi untuk editor metode input (IME): IME dapat menggunakan metode getApplicationLocales() untuk memeriksa bahasa aplikasi saat ini dan mencocokkan bahasa IME dengan bahasa tersebut.

Grammatical Inflection API

Tiga miliar orang menggunakan bahasa bergender: bahasa yang kategori gramatikalnya—seperti kata benda, kata kerja, kata sifat, dan preposisi—diterapkan dengan gender orang dan objek yang Anda ajak bicara atau Anda bicarakan. Secara tradisional, banyak bahasa bergender menggunakan gender gramatikal maskulin sebagai gender default atau generik.

Menjangkau pengguna dalam gender gramatikal yang salah, seperti menyapa perempuan dengan gender gramatikal yang maskulin, dapat memberi dampak negatif pada performa dan sikap mereka. Sebaliknya, UI dengan bahasa yang mencerminkan gender gramatikal pengguna dengan benar dapat meningkatkan interaksi pengguna dan memberikan pengalaman pengguna yang lebih personal dan terdengar alami.

为帮助您针对区分性别的语言构建以用户为中心的界面,Android 14 引入了 Grammatical Inflection API,让您无需重构应用便能添加对语法性别的支持。

Preferensi regional

Preferensi regional memungkinkan pengguna mempersonalisasi satuan suhu, hari pertama dalam seminggu, dan sistem penomoran. Orang Eropa yang tinggal di Amerika Serikat mungkin lebih memilih satuan suhu dalam Celsius, bukan Fahrenheit, dan menginginkan aplikasi memperlakukan Senin sebagai awal minggu, bukan default Minggu seperti di Amerika.

Menu Setelan Android yang baru untuk preferensi ini memberi pengguna lokasi yang dapat ditemukan dan terpusat untuk mengubah preferensi aplikasi. Preferensi ini juga tetap ada melalui pencadangan dan pemulihan. Beberapa API dan intent—seperti getTemperatureUnit dan getFirstDayOfWeek— memberikan pembacaan aplikasi Anda akses ke preferensi pengguna, sehingga aplikasi dapat menyesuaikan cara menampilkan informasi. Anda juga dapat mendaftarkan BroadcastReceiver di ACTION_LOCALE_CHANGED untuk menangani perubahan konfigurasi lokalitas saat preferensi regional berubah.

Untuk menemukan setelan ini, buka aplikasi Settings, lalu buka System > Languages & input > Regional preferences.

Layar Preferensi regional di setelan sistem Android.
Opsi suhu untuk preferensi regional di setelan sistem Android.

Aksesibilitas

Penskalaan font non-linear ke 200%

从 Android 14 开始,系统支持字体放大高达 200%,为弱视用户提供了符合网络内容无障碍指南 (WCAG) 的其他无障碍选项。

为防止屏幕上的大文本元素放大过大,系统会采用非线性放大曲线。这种放大策略意味着大号文本的放大比例不会与较小的文本相同。非线性字体缩放有助于保持不同大小元素之间的比例层次结构,同时缓解高级别线性文本缩放的问题(例如文本被截断或文本因超大显示大小而难以阅读)。

使用非线性字体放大测试应用

在设备的无障碍设置中启用最大字号,以测试应用。

如果您已经使用放大像素 (sp) 单位来定义文本大小,那么这些额外的选项和缩放改进会自动应用于应用中的文本。但是,您仍然应该在启用最大字体大小 (200%) 的情况下执行界面测试,以确保应用正确应用字体大小,并且可以适应更大的字体大小,而不影响易用性。

要启用 200% 字号,请按以下步骤操作:

  1. 打开“设置”应用,然后依次前往无障碍 > 显示大小和文字
  2. 字号选项中,点按加号 (+) 图标,直到启用最大字号设置,如本部分随附的图片所示。

针对文本大小使用放大像素 (sp) 单位

请务必始终以 sp 为单位指定文本大小。当应用使用 sp 单位时,Android 可以应用用户的首选文本大小并相应地缩放。

不要为内边距使用 sp 单位,也不假设隐式内边距定义视图高度:使用非线性字体缩放 sp 尺寸可能不成比例,因此 4sp + 20sp 可能不等于 24sp。

转换放大像素 (sp) 单位

使用 TypedValue.applyDimension() 从 sp 单位转换为像素,并使用 TypedValue.deriveDimension() 将像素转换为 sp。这些方法会自动应用适当的非线性缩放曲线。

避免使用 Configuration.fontScaleDisplayMetrics.scaledDensity 对方程进行硬编码。由于字体缩放是非线性的,因此 scaledDensity 字段不再准确。fontScale 字段应仅用于提供信息,因为字体不再使用单个标量值进行缩放。

对 lineHeight 使用 sp 单位

始终使用 sp 单位(而非 dp)定义 android:lineHeight,以便行高随文本一起缩放。否则,如果您的文本为 sp,而 lineHeight 以 dp 或 px 为单位,则文本无法缩放且看起来狭窄。TextView 会自动更正 lineHeight 以保留您预期的比例,但前提是以 sp 为单位同时定义 textSizelineHeight

Kamera dan media

Ultra HDR untuk gambar

标准动态范围 (SDR) 与高动态范围 (HDR) 图片质量对比示意图。

Android 14 新增了对高动态范围 (HDR) 图片的支持,可在拍摄照片时保留更多来自传感器的信息,从而实现鲜艳的色彩和更高的对比度。Android 使用 Ultra HDR 格式,该格式与 JPEG 图片完全向后兼容,可让应用与 HDR 图片无缝互操作,并根据需要以标准动态范围 (SDR) 显示这些图片。

当您的应用选择为其 activity 窗口使用 HDR 界面(通过清单条目或通过在运行时调用 Window.setColorMode())时,框架会自动在界面中以 HDR 格式渲染这些图片。您还可以在受支持的设备上拍摄压缩的 Ultra HDR 静态图片。从传感器中恢复的颜色越多,后期编辑的灵活性就越高。与 Ultra HDR 图片关联的 Gainmap 可用于使用 OpenGL 或 Vulkan 渲染这些图片。

Zoom, Fokus, Postview, dan lainnya di ekstensi kamera

Android 14 升级并改进了相机扩展程序,让应用能够处理更长的处理时间,从而支持在受支持的设备上使用计算密集型算法(例如弱光摄影)来改善图片。这些功能可让用户在使用相机扩展功能时获得更出色的体验。这些改进的示例包括:

Zoom dalam sensor

CameraCharacteristics 中的 REQUEST_AVAILABLE_CAPABILITIES_STREAM_USE_CASE 包含 SCALER_AVAILABLE_STREAM_USE_CASES_CROPPED_RAW 时,您的应用可以使用高级传感器功能,将剪裁后的 RAW 数据流的像素与全视野范围相同,方法是将 CaptureRequest 与将数据流用例设置为 CameraMetadata.SCALER_AVAILABLE_STREAM_USE_CASES_CROPPED_RAW 的 RAW 目标搭配使用。通过实现请求替换控件,更新后的相机可让用户在其他相机控件准备就绪之前使用缩放控件。

Audio USB lossless

Android 14 支持无损音频格式,可通过 USB 有线耳机提供发烧友级体验。您可以查询 USB 设备的首选混音器属性,注册监听器以监听首选混音器属性的更改,以及使用 AudioMixerAttributes 类配置混音器属性。此类表示音频混音器的格式,例如声道掩码、采样率和行为。该类允许直接发送音频,而无需混音、调节音量或处理效果。

Alat dan produktivitas developer

Credential Manager

Android 14 menambahkan Pengelola Kredensial sebagai API platform, dengan dukungan tambahan kembali ke perangkat Android 4.4 (API level 19) melalui Library Jetpack menggunakan layanan Google Play. Pengelola Kredensial bertujuan untuk mempermudah login bagi pengguna dengan API yang mengambil dan menyimpan kredensial dengan penyedia kredensial yang dikonfigurasi pengguna. Pengelola Kredensial mendukung beberapa metode login, termasuk nama pengguna dan sandi, kunci sandi, dan solusi login gabungan (seperti Login dengan Google) dalam satu API.

Kunci sandi memberikan banyak manfaat. Misalnya, kunci sandi dibuat berdasarkan standar industri, dapat berfungsi di berbagai sistem operasi dan ekosistem browser, serta dapat digunakan dengan situs dan aplikasi.

Untuk informasi selengkapnya, lihat dokumentasi Credential Manager dan kunci sandi serta postingan blog tentang Credential Manager dan kunci sandi.

Health Connect

Health Connect 是用户健康与健身数据的设备端仓库。借助该功能,用户可以在一个位置控制要与这些应用共享哪些数据,并在自己喜爱的应用之间共享数据。

在搭载 Android 14 之前的 Android 版本的设备上,Health Connect 可作为应用从 Google Play 商店下载。从 Android 14 开始,Health Connect 将成为 Android 平台的一部分,并通过 Google Play 系统更新接收更新,而无需单独下载。这样一来,Health Connect 就可以频繁更新,您的应用可以依赖于搭载 Android 14 或更高版本的设备上提供的 Health Connect。用户可以通过设备的“设置”访问 Health Connect,隐私控制功能集成到系统设置中。

用户无需在搭载 Android 14 或更高版本的设备上单独下载应用,即可开始使用 Health Connect。
用户可以通过系统设置控制哪些应用可以访问其健康与健身数据。

Health Connect 在 Android 14 中包含多项新功能,例如锻炼路线,可让用户分享可在地图上直观呈现的锻炼路线。路线定义为在一定时间范围内保存的位置列表,您的应用可以将路线插入锻炼时段,将它们关联起来。为确保用户能够完全控制此类敏感数据,用户必须允许与其他应用共享单个路线。

如需了解详情,请参阅 Health Connect 文档以及有关 Android Health 中的新功能的博文。

Update OpenJDK 17

Android 14 melanjutkan pekerjaan memuat ulang library inti Android agar selaras dengan fitur dalam rilis OpenJDK LTS terbaru, termasuk update library dan dukungan bahasa Java 17 untuk developer aplikasi dan platform.

Fitur dan peningkatan berikut disertakan:

  • Mengupdate sekitar 300 class java.base ke dukungan Java 17.
  • Pemblokiran Teks, yang memperkenalkan literal string multibaris ke bahasa pemrograman Java.
  • Pencocokan Pola untuk instance, yang memungkinkan objek diperlakukan sebagai memiliki jenis tertentu dalam instanceof tanpa variabel tambahan.
  • Class tertutup, yang memungkinkan Anda membatasi class dan antarmuka yang dapat memperluas atau menerapkannya.

Berkat update sistem Google Play (Project Mainline), lebih dari 600 juta perangkat diaktifkan untuk menerima update Android Runtime (ART) terbaru yang menyertakan perubahan ini. Ini adalah bagian dari komitmen kami untuk memberi aplikasi lingkungan yang lebih konsisten dan aman di seluruh perangkat, serta memberikan fitur dan kemampuan baru kepada pengguna, terlepas dari rilis platform.

Java dan OpenJDK adalah merek dagang atau merek dagang terdaftar dari Oracle dan/atau afiliasinya.

Peningkatan untuk app store

Android 14 memperkenalkan beberapa PackageInstaller API yang memungkinkan app store meningkatkan pengalaman pengguna mereka.

Meminta persetujuan penginstalan sebelum mendownload

Menginstal atau mengupdate aplikasi mungkin memerlukan persetujuan pengguna. Misalnya, saat penginstal yang menggunakan izin REQUEST_INSTALL_PACKAGES mencoba menginstal aplikasi baru. Pada versi Android sebelumnya, app store hanya dapat meminta persetujuan pengguna setelah APK ditulis ke sesi penginstalan dan sesi berkomitmen.

Mulai Android 14, metode requestUserPreapproval() memungkinkan penginstal meminta persetujuan pengguna sebelum melakukan sesi penginstalan. Peningkatan ini memungkinkan app store menunda download APK apa pun hingga setelah penginstalan disetujui oleh pengguna. Selain itu, setelah pengguna menyetujui penginstalan, app store dapat mendownload dan menginstal aplikasi di latar belakang tanpa mengganggu pengguna.

Mengklaim tanggung jawab untuk update mendatang

Metode setRequestUpdateOwnership() memungkinkan penginstal memberi tahu sistem bahwa penginstal bermaksud bertanggung jawab atas update mendatang untuk aplikasi yang diinstalnya. Kemampuan ini memungkinkan penerapan kepemilikan update, yang berarti bahwa hanya pemilik update yang diizinkan untuk menginstal update otomatis ke aplikasi. Penerapan kepemilikan update membantu memastikan bahwa pengguna hanya menerima update dari app store yang diharapkan.

Penginstal lainnya, termasuk yang menggunakan izin INSTALL_PACKAGES, harus menerima persetujuan eksplisit pengguna untuk menginstal update. Jika pengguna memutuskan untuk melanjutkan update dari sumber lain, kepemilikan update akan hilang.

Mengupdate aplikasi pada waktu yang tidak terlalu mengganggu

App store biasanya ingin menghindari update aplikasi yang aktif digunakan karena hal ini menyebabkan proses aplikasi yang sedang berjalan dihentikan, yang berpotensi mengganggu aktivitas pengguna.

Mulai Android 14, InstallConstraints API memberi penginstal cara untuk memastikan update aplikasi mereka terjadi pada momen yang tepat. Misalnya, app store dapat memanggil metode commitSessionAfterInstallConstraintsAreMet() untuk memastikan update hanya dilakukan saat pengguna tidak lagi berinteraksi dengan aplikasi yang dimaksud.

Menginstal pemisahan opsional dengan lancar

Dengan APK terpisah, fitur aplikasi dapat dikirimkan dalam file APK terpisah, bukan sebagai APK monolitik. APK terpisah memungkinkan app store mengoptimalkan pengiriman berbagai komponen aplikasi. Misalnya, app store dapat mengoptimalkan berdasarkan properti perangkat target. PackageInstaller API telah mendukung pemisahan sejak diperkenalkan di API level 22.

Di Android 14, metode setDontKillApp() memungkinkan penginstal menunjukkan bahwa proses aplikasi yang sedang berjalan tidak boleh dihentikan saat pemisahan baru diinstal. App store dapat menggunakan fitur ini untuk menginstal fitur baru aplikasi dengan lancar ketika pengguna sedang menggunakan aplikasi.

Paket metadata aplikasi

从 Android 14 开始,Android 软件包安装程序可让您指定应用元数据(例如数据安全做法),以在 Google Play 等应用商店页面上架。

Mendeteksi kapan pengguna mengambil screenshot perangkat

为了打造更加标准化的屏幕截图检测体验,Android 14 引入了可保护隐私的屏幕截图检测 API。借助此 API,应用可以按 activity 注册回调。如果用户在该 activity 可见时截取屏幕截图,系统会调用这些回调并通知用户。

Pengalaman pengguna

Tindakan kustom Sharesheet dan peringkat yang ditingkatkan

Android 14 mengupdate sharesheet sistem untuk mendukung tindakan aplikasi kustom dan hasil pratinjau yang lebih informatif bagi pengguna.

Menambahkan tindakan kustom

Dengan Android 14, aplikasi Anda dapat menambahkan tindakan kustom ke sharesheet sistem yang dipanggilnya.

Screenshot tindakan kustom di panel berbagi.

Meningkatkan peringkat target Berbagi Langsung

Android 14 menggunakan lebih banyak sinyal dari aplikasi untuk menentukan peringkat target langsung berbagi agar memberikan hasil yang lebih bermanfaat bagi pengguna. Untuk memberikan sinyal yang paling berguna untuk peringkat, ikuti panduan untuk meningkatkan peringkat target Berbagi Langsung. Aplikasi komunikasi juga dapat melaporkan penggunaan pintasan untuk pesan keluar dan masuk.

Baris Berbagi Langsung di sharesheet, seperti yang ditunjukkan oleh 1

Dukungan untuk animasi bawaan dan kustom untuk Kembali Prediktif

Video: Animasi kembali prediktif

Android 13 memperkenalkan animasi "kembali ke layar utama" prediktif di balik opsi developer. Saat digunakan pada aplikasi yang didukung dengan opsi developer yang diaktifkan, menggeser kembali akan menampilkan animasi yang menunjukkan bahwa gestur kembali akan menutup aplikasi untuk kembali ke layar utama.

Android 14 menyertakan beberapa peningkatan dan panduan baru untuk Kembali Prediktif:

Dengan rilis pratinjau Android 14 ini, semua fitur Kembali Prediktif tetap berada di balik opsi developer. Lihat panduan developer untuk memigrasikan aplikasi ke kembali prediktif, serta panduan developer untuk membuat transisi kustom dalam aplikasi.

Penggantian per aplikasi produsen perangkat layar besar

借助按应用替换项,设备制造商可以更改应用在大屏设备上的行为。例如,FORCE_RESIZE_APP 替换项会指示系统调整应用大小以适应显示屏尺寸(避免进入尺寸兼容模式),即使在应用清单中设置了 resizeableActivity="false" 也是如此。

替换项旨在改善大屏设备上的用户体验。

借助新的清单属性,您可以为应用停用某些设备制造商替换项。

Penggantian per aplikasi pengguna perangkat layar besar

Penggantian per aplikasi mengubah perilaku aplikasi di perangkat layar besar. Misalnya, penggantian produsen perangkat OVERRIDE_MIN_ASPECT_RATIO_LARGE menetapkan rasio aspek aplikasi ke 16:9, terlepas dari konfigurasi aplikasi.

Android 14 QPR1 memungkinkan pengguna menerapkan penggantian per aplikasi melalui menu setelan baru di perangkat layar besar.

Berbagi layar aplikasi

借助应用界面共享功能,用户可以在录制屏幕内容时共享应用窗口,而不是整个设备屏幕。

在应用屏幕共享模式下,状态栏、导航栏、通知和其他系统界面元素会从共享显示屏中排除。系统只会分享所选应用的内容。

应用屏幕共享功能可让用户运行多个应用,但将内容共享限制为单个应用,从而提高工作效率并保护隐私。

Smart Reply yang didukung LLM di Gboard pada Pixel 8 Pro

Di perangkat Pixel 8 Pro dengan Feature Drop Desember, developer dapat mencoba smart reply berkualitas lebih tinggi di Gboard yang didukung oleh Model Bahasa Besar (LLM) di perangkat yang berjalan di Google Tensor.

Fitur ini tersedia sebagai pratinjau terbatas untuk bahasa Inggris Amerika Serikat di WhatsApp, Line, dan KakaoTalk. Fitur ini memerlukan penggunaan perangkat Pixel 8 Pro dengan Gboard sebagai keyboard Anda.

Untuk mencobanya, aktifkan fitur ini terlebih dahulu di Setelan > Opsi Developer > Setelan AICore > Aktifkan AIcore Persistent.

Selanjutnya, buka percakapan di aplikasi yang didukung untuk melihat Smart Reply yang didukung LLM di bilah saran Gboard sebagai respons terhadap pesan masuk.

Gboard menggunakan LLM di perangkat untuk memberikan balasan pintar berkualitas lebih tinggi.

Grafik

Jalur dapat dikueri dan dapat di-interpola

Android 的 Path API 是一种强大且灵活的机制,可用于创建和渲染矢量图形,能够描边或填充路径、根据线段或二次曲线或立方曲线构建路径、执行布尔运算以获取更复杂的形状,或同时执行所有这些操作。但有一个限制是,您无法了解 Path 对象中实际包含的内容;该对象的内部信息在创建后对调用方是不透明的。

如需创建 Path,您可以调用 moveTo()lineTo()cubicTo() 等方法来添加路径段。但是,无法询问该路径有哪些片段,因此您必须在创建时保留该信息。

从 Android 14 开始,您可以查询路径以了解其内部内容。首先,您需要使用 Path.getPathIterator API 获取 PathIterator 对象:

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();

接下来,您可以调用 PathIterator 逐个遍历片段,并检索每个片段的所有必要数据。以下示例使用了 PathIterator.Segment 对象,它会为您打包数据:

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 还有一个非分配版 next(),您可以在其中传入缓冲区来保存点数据。

查询 Path 数据的一个重要用例是插值。例如,您可能想在两个不同的路径之间添加动画(或变形)。为了进一步简化该用例,Android 14 针对 Path 还包含 interpolate() 方法。假设两个路径具有相同的内部结构,interpolate() 方法会使用该插值结果创建一个新的 Path。以下示例返回了一个形状介于 pathotherPath 之间的一半(线性插值为 0.5)的路径:

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);
}

Jetpack graphics-path 库也为早期版本的 Android 启用了类似的 API。

Mesh kustom dengan shader fragmen dan vertex

Android telah lama mendukung mesh segitiga gambar dengan bayangan kustom, tetapi format mesh input telah dibatasi untuk beberapa kombinasi atribut yang telah ditentukan. Android 14 menambahkan dukungan untuk mesh kustom, yang dapat didefinisikan sebagai segitiga atau strip segitiga, dan dapat, secara opsional, diindeks. Mesh ini ditentukan dengan atribut kustom, langkah vertex, beragam, serta shader vertex dan fragmen yang ditulis dalam AGSL.

Vertex shader menentukan variasi, seperti posisi dan warna, sedangkan fragment shader secara opsional dapat menentukan warna untuk piksel, biasanya dengan menggunakan variasi yang dibuat oleh vertex shader. Jika warna disediakan oleh shader fragmen, warna tersebut akan digabungkan dengan warna Paint saat ini menggunakan mode gabungan yang dipilih saat menggambar mesh. Seragam dapat diteruskan ke shader fragmen dan vertex untuk fleksibilitas tambahan.

Perender buffer hardware untuk Canvas

协助使用 Android 的 Canvas API 通过 硬件加速至 HardwareBuffer、Android 14 引入了 HardwareBufferRenderer。如果您的用例涉及通过 SurfaceControl 与系统合成器通信以实现低延迟绘制,此 API 特别有用。