跳至主内容

迈向稳定的 JavaScript API（0.80 版本中的新变化）

· 1 分钟阅读
Alex Hunt
Alex Hunt
Software Engineer @ Meta
Iwo Plaza
Iwo Plaza
Software Engineer @ Software Mansion
Jakub Piasecki
Jakub Piasecki
Software Engineer @ Software Mansion
Dawid Małecki
Dawid Małecki
Software Engineer @ Software Mansion
非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →

在 React Native 0.80 版本中，我们将对 JavaScript API 进行两项重大变更：弃用深度导入，并推出全新的 Strict TypeScript API。这些举措是我们持续完善 API 定义、为用户和框架提供可靠类型安全性的重要组成部分。

核心变更摘要：

  • 深度导入弃用：从 0.80 版本开始，针对从 react-native 包进行深度导入的操作将触发弃用警告。

  • 可选的 Strict TypeScript API：我们将迁移至基于源代码的 TypeScript 类型定义，并在 TypeScript 下建立新的公共 API 基线。这些改进将提供更强大且面向未来的类型准确性，这是一次性的破坏性变更。您可通过在项目的 tsconfig.json 中配置 compilerOptions 来启用此功能。

在未来的 React Native 版本默认启用 Strict TypeScript API 之前，我们将持续与社区协作，确保这些变更适用于所有开发者。

变更内容与背景​

我们正致力于改进并稳定 React Native 的公共 JavaScript API——即导入 'react-native' 时获取的接口。

长期以来，我们采用近似方案实现这一目标。React Native 使用 Flow 编写，但开源社区早已转向 TypeScript，后者成为消费公共 API 和验证兼容性的主要方式。现有的类型定义（深受喜爱）由社区贡献，后并入我们的代码库统一维护。然而这些类型依赖人工维护且缺乏自动化工具，导致存在准确性缺口。

此外，我们的公共 JS API 在模块边界定义上存在缺陷——例如应用代码可直接访问 'react-native/Libraries/' 等内部深度导入路径，但这些内部实现经常随更新而变动。

0.80 版本通过两项举措解决这些问题：弃用深度导入，并推出用户可选的 TypeScript 生成式 API 基线。我们将其命名为 Strict TypeScript API。这最终将为未来提供稳定的 React Native API 奠定基础。

弃用 react-native 深度导入​

本次 API 变更的核心是弃用深度导入（RFC），ESLint 和 JS 控制台将发出警告。所有值和类型的深度导入都应迁移至 react-native 的根导入。

// Before - import from subpath
import {Alert} from 'react-native/Libraries/Alert/Alert';

// After - import from `react-native`
import {Alert} from 'react-native';

此变更将 JavaScript API 的暴露范围缩减为固定导出集，使我们能在未来版本中控制并稳定这些接口。计划在 0.82 版本彻底移除这些导入路径。

API 反馈

部分 API 未在根目录导出，深度导入弃用后将无法访问。我们开设了**开放反馈讨论帖**，将与社区共同完善公共 API 的导出定义。欢迎分享您的意见！

重要说明

请注意，我们计划在未来版本中从 React Native API 移除深度导入，开发者应将其更新为根导入。

Opting out of warnings

ESLint​

Disable the no-deep-imports rule using overrides.

.eslintrc.js
  overrides: [
    {
      files: ['*.js', '*.jsx', '*.ts', '*.tsx'],
      rules: {
        '@react-native/no-deep-imports': 0,
      },
    },
  ]

Console warnings​

Pass the disableDeepImportWarnings option to @react-native/babel-preset.

babel.config.js
module.exports = {
  presets: [
    ['module:@react-native/babel-preset', {disableDeepImportWarnings: true}]
  ],
};

Restart your app with --reset-cache to clear the Metro cache.

npx @react-native-community/cli start --reset-cache
Opting out of warnings (Expo)

ESLint​

Disable the no-deep-imports rule using overrides.

.eslintrc.js
overrides: [
  {
    files: ['*.js', '*.jsx', '*.ts', '*.tsx'],
    rules: {
      '@react-native/no-deep-imports': 0,
    },
  },
];

Console warnings​

Pass the disableDeepImportWarnings option to babel-preset-expo.

babel.config.js
module.exports = function (api) {
  api.cache(true);
  return {
    presets: [['babel-preset-expo', {disableDeepImportWarnings: true}]],
  };
};

Restart your app with --clear to clear the Metro cache.

npx expo start --clear

Strict TypeScript API（可选启用）​

Strict TypeScript API 是 react-native 包中的新型 TypeScript 类型集，可通过 tsconfig.json 文件选择启用。我们将与现有 TS 类型同时发布，您可在准备就绪时进行迁移。

新类型具有以下特性：

  1. 直接由源代码生成 - 提升覆盖范围与准确性，为您提供更强的兼容性保障。

  2. 严格限定于 react-native 的 index 文件——更精准定义公共 API，确保内部文件变更不会破坏 API 接口。

当社区准备就绪后，Strict TypeScript API 将成为默认 API —— 并与深度导入移除同步实施。建议您尽早启用，以便适配 React Native 未来的稳定 JS API。

tsconfig.json
{
  "extends": "@react-native/typescript-config",
  "compilerOptions": {
    ...
    "customConditions": ["react-native-strict-api"]
  }
}
实现原理

这将指示 TypeScript 从新的 types_generated/ 目录解析 react-native 类型，而非此前手动维护的 types/ 目录。无需重启 TypeScript 或编辑器。

破坏性变更：禁止深度导入​

如前所述，在 Strict TypeScript API 下，类型仅可通过主 'react-native' 导入路径解析，强制执行包封装规范。

// Before - import from subpath
import {Alert} from 'react-native/Libraries/Alert/Alert';

// After - MUST import from `react-native`
import {Alert} from 'react-native';
核心收益

我们将公共 API 严格限定在 React Native index.js 文件的导出范围内，这些接口会得到精心维护。这意味着代码库其他位置的变更将不再引发破坏性变更。

破坏性变更：类型名称/结构更新​

由于类型现在直接从源代码生成（而非手动维护）：

  • 我们统一了社区贡献类型积累的差异——同时提升了源代码的类型覆盖率。

  • 在有简化或消除歧义空间的场景下，我们主动更新了部分类型名称和结构。

核心收益

由于类型直接生成自 React Native 源代码，您可以确信类型检查器始终精确匹配当前 react-native 版本。

示例：更严格的导出符号​

Linking API 现在整合为单一 interface 而非两个独立导出。此模式也适用于其他多个 API（详见文档）。

// Before
import {Linking, LinkingStatic} from 'react-native';

function foo(linking: LinkingStatic) {}
foo(Linking);

// After
import {Linking} from 'react-native';

function foo(linking: Linking) {}
foo(Linking);

示例：修复/更完整的类型​

此前的手动类型定义存在类型缺口。通过 Flow → TypeScript 的自动化生成，这些问题已彻底解决（在源代码层面还受益于 Flow 对多平台代码的额外类型验证）。

import {Dimensions} from 'react-native';

// Before - Type error
// After - number | undefined
const {densityDpi} = Dimensions.get();

其他破坏性变更​

请查阅文档中的专用指南，其中详述了所有破坏性类型变更及代码迁移方案。

发布规划​

我们理解 React Native 的任何破坏性变更都需要开发者投入时间进行应用适配。

现阶段——可选启用（0.80 版本）​

"react-native-strict-api" 选项已在 0.80 稳定版中可用。

  • 这是一次性迁移。我们建议应用和库在后续几个版本中按自身节奏启用。

  • 在任何模式下，您的应用运行时行为都不会改变 —— 此变更仅影响 TypeScript 分析。

  • 同时，我们通过专用反馈讨论帖持续收集关于缺失 API 的意见。

推荐

Strict TypeScript API 将成为未来的默认 API。

如果您有时间，建议立即在 tsconfig.json 中测试启用选项，使您的应用或库面向未来。这将立即评估您的应用在严格 API 下是否出现类型错误。可能完全不存在错误！——若如此，您已准备就绪。

未来——默认启用 Strict TypeScript API​

未来，我们将要求所有代码库使用我们的 Strict API，并移除旧版类型定义。

这一变化的时间表将基于社区反馈。至少在接下来的两个 React Native 版本中，Strict API 将保持为选择启用状态。

常见问题解答​

I'm using subpath imports today. What should I do?

Please migrate to the root 'react-native' import path.

  • Subpath imports (e.g. 'react-native/Libraries/Alert/Alert') are becoming private APIs. Without preventing access to implementation files inside React Native, we can’t offer a stable JavaScript API.
  • We want our deprecation warnings to motivate community feedback, which can be raised via our centralized discussion thread, if you believe we are not exposing code paths that are crucial for your app. Where justified, we may promote APIs to the index export.

I'm a library maintainer. How does this change impact me?

Both apps and libraries can opt in at their own pace, since tsconfig.json will only affect the immediate codebase.

  • Typically, node_modules is excluded from validation by the TypeScript server in a React Native project. Therefore, your package's exported type definitions are the source of truth.

💡 We want feedback! As with changed subpath imports, if you encounter any integration issues with the Strict API, please let us know on GitHub.

Does this guarantee a final API for React Native yet?

Sadly, not yet. In 0.80, we've made a tooling investment so that React Native's existing JS API baseline can be accurately consumed via TypeScript — enabling future stable changes. We're formalizing the existing API you know and love.

In the future, we will take action to finalise the APIs we currently offer in core — across each language surface. API changes will be communicated via RFCs/announcements, and typically a deprecation cycle.

Why isn't React Native written in TypeScript?

React Native is core infrastructure at Meta. We test every merged change across our Family of Apps, before they hit general open source availability.

At this scale and sensitivity, correctness matters. The bottom line is that Flow offers us greater performance and greater strictness than TypeScript, including specific multi-platform support for React Native.

致谢​

这些变更的实现得益于 Iwo Plaza, Jakub Piasecki, Dawid Małecki, Alex Hunt 和 Riccardo Cipolleschi 的贡献。

同时感谢 Pieter Vanderwerff, Rubén Norte 和 Rob Hogan 提供的额外帮助和意见。

了解更多
Watch the talk!We shared a deep dive into our motivations and the work behind the Strict TypeScript API at App.js 2025.

View on YouTube

App.js 2025 Talk