0Pricing
React Native Academy · 课时

Linking API 与 URL 解析

使用 Linking API 监听应用运行期间传入的 URL，解析 URL 的路径和查询参数，并分发导航操作。

Linking API 与 URL 解析 是 CoddyKit 上的免费 React Native Academy 课时。 这是第 2 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 React Native Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 React Native Academy 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

The Linking Module Overview

React Native's built-in Linking module is the interface between your app and the operating system's URL handling system. It serves two purposes: outgoing — opening URLs in browsers, maps, email, phone, and other apps; and incoming — receiving URLs that were used to open your app.

For deep linking to work correctly you need to handle both the cold-start case (app launched by a URL) and the warm-start case (URL arrives while the app is already running). The Linking module provides different APIs for each scenario.

import { Linking } from 'react-native';

// Outgoing:
Linking.openURL('https://example.com');

// Check if URL can be opened:
Linking.canOpenURL('myapp://screen').then(Boolean);

// Incoming - cold launch:
Linking.getInitialURL();

// Incoming - while running:
Linking.addEventListener('url', ({ url }) => {});

Comprehensive URL Listener Setup

The recommended pattern handles both cold and warm starts in a single effect. Read getInitialURL() for the cold launch URL and add a listener for warm-start URLs. Both call the same handleURL function to keep routing logic in one place.

Place this effect in your root navigation component or a custom useDeepLink hook so it runs when navigation is available and is properly cleaned up when the component unmounts.

useEffect(() => {
  function handleURL(url) {
    if (url) routeDeepLink(url);
  }

  // Cold launch URL:
  Linking.getInitialURL().then(handleURL);

  // Warm launch URL:
  const sub = Linking.addEventListener('url', ({ url }) => handleURL(url));

  return () => sub.remove();
}, []);

Parsing URL Components

Modern React Native (with Hermes) supports the URL Web API. Construct a URL object from the deep link string to easily access protocol, hostname, pathname, and searchParams. This is far more robust than manual string splitting.

For the scheme myapp://settings/notifications?highlight=push, the hostname is settings, the pathname is /notifications, and searchParams provides the query parameters as a URLSearchParams object.

function parseDeepLink(url) {
  // 'myapp://settings/notifications?highlight=push'
  const parsed = new URL(url);

  return {
    screen: parsed.hostname,          // 'settings'
    path: parsed.pathname.slice(1),   // 'notifications'
    params: Object.fromEntries(
      parsed.searchParams.entries()   // { highlight: 'push' }
    ),
  };
}

Route Matching and Navigation

With the parsed URL parts, implement a routeDeepLink function that matches the screen name to a navigation action. Use a lookup object or switch statement to map URL screens to navigator screen names and param shapes.

Always guard against invalid or malformed URLs — if the screen is unknown, navigate to the home screen rather than throwing an error. Deep links from external sources should be treated as untrusted input.

function routeDeepLink(url) {
  const { screen, path, params } = parseDeepLink(url);

  switch (screen) {
    case 'profile':
      navigation.navigate('Profile', { userId: path, ...params });
      break;
    case 'product':
      navigation.navigate('Product', { productId: path });
      break;
    case 'settings':
      navigation.navigate('Settings', { section: path });
      break;
    default:
      navigation.navigate('Home');
  }
}

Waiting for Navigation to Be Ready

A common bug: the deep link handler calls navigation.navigate() before the navigation container has mounted and initialized. The navigation ref may be null or the stack may not be set up yet, causing the navigate call to be silently ignored.

Use the onReady callback of NavigationContainer with a ref to detect when navigation is ready. Store pending deep link URLs and process them in onReady and after each navigation state change.

const navigationRef = useNavigationContainerRef();
const pendingUrl = useRef(null);

function handleURL(url) {
  if (navigationRef.isReady()) {
    routeDeepLink(url);
  } else {
    pendingUrl.current = url; // queue it
  }
}

<NavigationContainer
  ref={navigationRef}
  onReady={() => {
    if (pendingUrl.current) {
      routeDeepLink(pendingUrl.current);
      pendingUrl.current = null;
    }
  }}
>

Custom URL Scheme vs HTTPS URLs

The Linking API works with both custom scheme URLs (myapp://) and HTTPS universal links (https://yoursite.com/path). For universal links the URL structure is cleaner — the hostname is your domain and the path is the content path — but they require web server configuration to work.

When testing HTTPS deep links locally, use custom scheme URLs in development and universal links in production. The same routeDeepLink function can handle both if you normalize the parsed result to a common structure.

function parseDeepLink(url) {
  const parsed = new URL(url);

  if (parsed.protocol === 'https:') {
    // Universal link: https://myapp.com/profile/123
    const parts = parsed.pathname.split('/').filter(Boolean);
    return { screen: parts[0], path: parts[1], params: {} };
  } else {
    // Custom scheme: myapp://profile/123
    return {
      screen: parsed.hostname,
      path: parsed.pathname.slice(1),
      params: Object.fromEntries(parsed.searchParams.entries()),
    };
  }
}

Outgoing Links: openURL

Linking.openURL() opens any URL outside your app. Pass HTTPS URLs to open in the browser, tel: URLs to open the dialer, mailto: to open the email client, and third-party app schemes to open specific apps. It returns a Promise — always await and catch errors in case the URL is not supported.

For email links, encode the subject and body in the URL using standard mailto: formatting. On iOS the Phone app handles tel: links; on Android the default dialer handles them.

// Open website:
await Linking.openURL('https://example.com');

// Call a phone number:
await Linking.openURL('tel:+15555551234');

// Compose email:
const subject = encodeURIComponent('Support Request');
const body = encodeURIComponent('Hi, I need help with...');
await Linking.openURL('mailto:support@example.com?subject=' + subject + '&body=' + body);

// Open Twitter profile:
await Linking.openURL('twitter://user?screen_name=reactnative');

canOpenURL Safety Checks

Before calling openURL, use Linking.canOpenURL() to verify the device can handle the scheme. On iOS 9+ you must whitelist external schemes in LSApplicationQueriesSchemes in Info.plist, or canOpenURL returns false even if the app is installed.

Expo managed workflow lets you add these whitelist entries via the ios.infoPlist key in app.json. Always provide a fallback (like an HTTPS URL) for when the native app is not installed.

async function openTwitterProfile(username) {
  const twitterAppUrl = 'twitter://user?screen_name=' + username;
  const twitterWebUrl = 'https://twitter.com/' + username;

  const canOpen = await Linking.canOpenURL(twitterAppUrl);
  await Linking.openURL(canOpen ? twitterAppUrl : twitterWebUrl);
}

// app.json (iOS whitelist):
// 'ios': {
//   'infoPlist': {
//     'LSApplicationQueriesSchemes': ['twitter', 'instagram']
//   }
// }

Deep Link URL Sanitization

Deep links from external sources should never be trusted blindly. A malicious link could pass arbitrary values as parameters and attempt navigation to unintended screens or inject data. Always sanitize and validate URL parameters before using them.

For IDs, verify they match expected format (UUID, integer). For screen names, use a whitelist lookup — never navigate to a screen name taken directly from the URL. Log and discard invalid URLs rather than crashing.

const ALLOWED_SCREENS = new Set(['profile', 'product', 'settings', 'home']);

function routeDeepLink(url) {
  try {
    const { screen, path, params } = parseDeepLink(url);

    if (!ALLOWED_SCREENS.has(screen)) {
      console.warn('Deep link to unknown screen:', screen);
      navigation.navigate('Home');
      return;
    }

    // Validate ID format:
    if (path && !/^[a-z0-9-]+$/i.test(path)) {
      throw new Error('Invalid path: ' + path);
    }

    navigation.navigate(capitalize(screen), { id: path, ...params });
  } catch (e) {
    navigation.navigate('Home');
  }
}

Tracking Deep Link Sources

Marketing campaigns and notifications often need attribution — knowing which link drove which user behavior. Add UTM parameters or a custom source parameter to deep link URLs, extract them in the handler, and log them to your analytics system.

For example, myapp://product/42?source=email_campaign&campaign=summer_sale tells you the user came from an email campaign. Log this event to Amplitude, Firebase Analytics, or Mixpanel in the routeDeepLink function before navigating.

function routeDeepLink(url) {
  const { screen, path, params } = parseDeepLink(url);

  // Log attribution:
  if (params.source || params.campaign) {
    analytics.track('deep_link_opened', {
      screen,
      source: params.source,
      campaign: params.campaign,
    });
  }

  // Then navigate:
  navigation.navigate(capitalize(screen), { id: path });
}

Testing Deep Links in Production Builds

Deep links behave differently in development (Expo Go) and production builds. Always test deep linking in a production or release build installed on a real device or emulator. Expo Go has its own URL scheme (exp://) which conflicts with custom schemes.

Use TestFlight (iOS) or internal testing track (Android) for end-to-end deep link verification before releasing to the public. Document your URL scheme and all supported paths in a README for QA teams to test every route.

// Supported deep links (document these for QA):
// myapp://home
// myapp://profile/{userId}
// myapp://product/{productId}?highlight={feature}
// myapp://settings/{section}
// myapp://order/{orderId}

// Test with:
// iOS: xcrun simctl openurl booted 'myapp://profile/abc123'
// Android: adb shell am start -a android.intent.action.VIEW -d 'myapp://profile/abc123'

Quick Check

Test your understanding of React Native Mobile Development concepts from this lesson.

Lesson Recap

In this lesson you learned: the Linking API handles both outgoing URL opens and incoming deep link URLs via getInitialURL and addEventListener, the URL Web API parses deep link components like hostname, pathname, and searchParams cleanly, and deep link routes must be whitelisted and sanitized before navigating to prevent security issues. Next up we configure React Navigation's built-in deep linking support to automatically route URLs to screens.

常见问题解答

「Linking API 与 URL 解析」课时是免费的吗？

是的 — 「Linking API 与 URL 解析」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 React Native Academy 课程的其余内容，请升级到 CoddyKit PRO。 React Native Academy 课程共包含 4 节课。

「Linking API 与 URL 解析」这节课中我会学到什么？

使用 Linking API 监听应用运行期间传入的 URL，解析 URL 的路径和查询参数，并分发导航操作。 你通过在浏览器中直接运行的动手代码来练习 React Native Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 React Native Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 React Native Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 2 节课，共 4 节。

「Linking API 与 URL 解析」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 React Native Academy 课中编写并运行代码吗？

能。每节 React Native Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. 配置自定义 URL 方案
  2. Linking API 与 URL 解析
  3. React Navigation 深层链接配置
  4. iOS 与 Android 上的通用链接（HTTPS 深层链接）
← 返回 React Native Academy