Expo イメージピッカー: 2026 年の完全ガイド

あなたはUIが完成し、プロフィール画面に「アップロード・フォト」ボタンが表示され、簡単な部分が突然簡単ではないようになったところでしょう。実際の画像選択フローはネイティブの権限、OSが制御するインターフェイス、多くの開発者が期待するよりも異なる戻り値の形状、そしてビルド時詳細が実際にビルドされた実際のビルドでしか表示されないものです。

エクスポ・イメージ・ピッカーはその役割を果たします。エクスポの公式ライブラリで、デバイスのライブラリから画像や動画を選択したり、カメラで写真を撮ったりするためのシステムUIを開くことができます。エクスポパッケージリポジトリで説明されているように。実際には、信頼できるネイティブメディア入力への橋渡しを提供しますが、カスタムメディアエクスペリエンスを提供するのではなく、デバイスごとに同じように動作するものではありません。このガイドは、デモではなく最初の実装に焦点を当てています。生産性に影響を与える決定に焦点を当てています。マネージドワークフローとベアワークフローのセットアップ、後で驚かれないようにするパーミッションハンドリング、安全な結果の解釈、ユーザーがファイルを選択した後、実際のアップロードパターンです。カスタムネイティブセットアップで働いている場合は、このエクスポ開発クライアントワークフローよりも異なる点を理解することも役立ちます。

はじめにエクスポ・イメージ・ピッカーの使い方.

context

context
インストールと基本設定
- マネージドワークフローの設定
- Bare React Nativeの設定詳細
カメラとメディアライブラリへのアクセス
ピッカー結果とオプションのハンドリング
高度なパターンとプラットフォームの差異
一般的な問題のトラブルシューティング
- 高速な一般的なエラーのチェック
- 短い生産チェックリスト

Expo Image Pickerの使用開始

製品マネージャーがプロフィール写真を要求します。 1 週間後、同様の機能も受け取ります。画像入力は、ユーザーが許可を拒否した場合にリトライする必要があるため、カメラキャプチャのインシデントレポート、OS所有のUI、テンポラリファイルハンドリング、バックエンドアップロードフローなど、ネイティブパーミッション、OS所有のUI、テンポラリファイルハンドリング、バックエンドアップロードフローなど、迅速に拡大します。

expo-image-picker Expo SDKモジュールはその仕事に適しています。プラットフォームピッカーまたはカメラUIを開き、選択されたメディアをReact Native codeが扱える形で返します。 JavaScript APIは小さく、主な課題は、両方のマネージドと裸のプロジェクトでネイティブのセットアップ、パーミッションフロー、結果ハンドリングを正しく行うことです。

主なトレードオフは簡単です。 iOSとAndroidが独自のメディアUIを提示するのを許可するのではなく、カスタムピッカーを構築します。通常、ユーザーはシステムスクリーンを理解しているため、結果は良くなります: パーミッションプロンプトはOSの期待どおりに動作し、チームはJavaScriptでギャラリーコードを維持する必要がありません。

この機能をネイティブの統合機能とReactインターフェイスとして扱ってください。

その考え方は、ピッカーを呼び出すボタンにない失敗モードがまれだからです。通常は、次の3つの場所のいずれかから来ます:

ネイティブ設定: プラグインのセットアップが欠落している、iOSの場合の不正な権限文字列、またはconfigを変更した後で古いビルドが古いビルドである:
実行時挙動: ユーザーがアクセスを拒否したり、iOSの場合のライブラリへの制限されたアクセスを許可したり、または選択肢を選択せずにフローをキャンセルしたりします。
結果の解析: 現在のAPIは配列を返します。古い例が直接読み取るように書かれている場合、失敗します。 assets array result.uri その分割は、ガイドの残りの部分で重要です。ハッピーパスは、両方のワークフローで機能し、プラットフォーム固有の権限の奇妙さをユーザーに驚かせずに処理し、アップロード層に使えるファイルを渡し、ローカルプレビューで止まらないようにするピッカー実装が堅固です。

Workflow choice also changes the setup path. In a managed Expo app, most of the native work lives in app config and requires a rebuild when that config changes. In a bare app, you still get the Expo module API, but you need to verify the underlying iOS and Android project settings more directly. If your team is using a custom client instead of Expo Go, this guide pairs well with Capgo’s explanation of Japanese.

protectedTokens

インストールと基本的な設定

インストールには 1 つのコマンドが必要です。ネイティブの設定を正しく行うことは、実機、カスタム開発クライアント、およびプロダクションビルドでピッカーが正常に動作するかどうかを決定します。

expo-image-picker gives a React-facing API over the platform pickers for photos, videos, and camera capture. The JavaScript call is simple. The setup is not, because photo access and camera access are controlled by iOS and Android, not by React Native.

エクスポイメージピッカー実装を実施している開発者が、ノートパソコンの画面にcodeを入力している。

Expo のバージョンに合わせたインストーラーから始めます。

npx expo install expo-image-picker

使用 expo install 代わりに npm install または yarn add. Expo matches the package version to your SDK, which avoids a common class of native compatibility problems. If you are comparing how Expo modules fit into your release process, this アプリケーションフローキャパウェーソン

キャパウェーソン

In managed workflow, declare plugin in app config so Expo can apply native changes at build time.

例えば app.json:

{
  "expo": {
    "plugins": ["expo-image-picker"]
  }
}

最小限の設定です。実際には、iOS ではシステムのプロンプトがアクセス権の理由を説明する必要があるため、チームは許可テキストを追加することが多いです。ユーザーが実行するアクションに合わせて言葉を選ぶことが重要です。例えば、「プロフィール写真をアップロードする」は「メディアアクセスが必要です」というよりも良いでしょう。

一つの運用上の詳細が多くの時間を浪費しています。変更 pluginsReact Native の基本設定

バレアプリでは、パッケージ __CAPGO_KEEP_0__ は同じですが、ネイティブのプロジェクトを自分で確認する必要があります。iOS の使用説明文は最初に確認するべきです。ライブラリを開く、カメラを開く、または音声付きのビデオを記録するフローがあれば、アプリには対応する許可テキストが必要です。

In a bare app, the package API is the same, but you need to verify more of the native project yourself. iOS usage descriptions are the first thing to check. If your flow can open the library, launch the camera, or record video with audio, your app needs the corresponding permission strings in Info.plist インストール

例えば

Install expo-image-picker Install npx expo install expo-image-picker.
with
iOSの使用説明を確認してください。使用説明は、機能を公開する機能と一致していることを確認してください。
iOSおよびAndroidアプリを再構築してください。ネイティブの構成が変更された場合。

Missing permission text often looks like a runtime bug because the UI code is fine and the button handler runs. The failure is lower in the stack. I usually check Info.plistアプリの設定、そして、現在のビルドが最新のネイティブの変更を含んでいるかどうかを確認する前に、コンポーネント code をタッチする。

設定を予測可能にする習慣がいくつかあります:

実際のアクションのために許可のテキストを書きます。 ユーザーは、提示される画面の理由を理解する必要があります。
カメラとライブラリを個別に設定します。 一方が機能しない場合でももう一方が機能する可能性があります。
ネイティブの変更後、再構築してください。 ホットリロードとファストリフレッシュはネイティブの許可を更新しません。
デバイス上でテストしてください: シミュレーターの動作は、パーミッションやカメラの問題を隠す可能性があります。

開発環境ではピッカーが正常に動作する場合でも、テストフライトまたはPlayストアのビルドで機能が途切れる場合は、まず設定問題として扱ってください。ほとんどの場合、それが正解です。

カメラとメディアライブラリへのアクセス

ユーザーが「写真をアップロードする」ボタンをタップすると、カメラまたはライブラリが開くことを期待し、ユーザーがその時点でアプリに1つの仕事しかありません。正しいシステムUIを開き、拒否またはキャンセルを処理することなく画面を破壊せずに、プレビューまたはアップロード用に利用可能なローカルファイル参照を返します。

That sounds simple until you test both managed and bare builds across iOS and Android. The JavaScript API stays compact, but the runtime behavior still depends on OS prompts, device hardware, and how your native permissions were configured earlier.

最小限の安全なコンポーネント

コアフローは、Expo管理されたワークフローと裸のワークフロー両方のプロジェクトで一貫しています。関連するパーミッションを要求し、ピッカーを起動し、ユーザーがキャンセルしたかどうかを確認し、最初のアセットを読み取る

ベースラインコンポーネントは次のようになります。 result.assets.

ここで3つの重要な点があります。

import { useState } from 'react';
import { View, Button, Image, Alert } from 'react-native';
import * as ImagePicker from 'expo-image-picker';

export default function PhotoInput() {
  const [imageUri, setImageUri] = useState<string | null>(null);

  const pickFromLibrary = async () => {
    const permission = await ImagePicker.requestMediaLibraryPermissionsAsync();

    if (!permission.granted) {
      Alert.alert('Permission required', 'Please allow photo library access.');
      return;
    }

    const result = await ImagePicker.launchImageLibraryAsync({
      mediaTypes: ['images'],
      allowsEditing: true,
      quality: 1,
    });

    if (result.canceled) return;

    const asset = result.assets?.[0];
    if (!asset?.uri) return;

    setImageUri(asset.uri);
  };

  const takePhoto = async () => {
    const permission = await ImagePicker.requestCameraPermissionsAsync();

    if (!permission.granted) {
      Alert.alert('Permission required', 'Please allow camera access.');
      return;
    }

    const result = await ImagePicker.launchCameraAsync({
      allowsEditing: true,
      quality: 1,
    });

    if (result.canceled) return;

    const asset = result.assets?.[0];
    if (!asset?.uri) return;

    setImageUri(asset.uri);
  };

  return (
    <View>
      <Button title="Choose from library" onPress={pickFromLibrary} />
      <Button title="Take photo" onPress={takePhoto} />
      {imageUri ? (
        <Image
          source={{ uri: imageUri }}
          style={{ width: 200, height: 200 }}
        />
      ) : null}
    </View>
  );
}

ライブラリとカメラのパーミッションを個別に要求することが重要です。独立して失敗する可能性があります。

キャンセルを正常なユーザーアクションとして扱うことが重要です。エラー状態ではありません。
キャンセルを正常なユーザー操作として扱い、エラーステートとして扱わない。
読み込む assets[0], というのはピッカーがアセット配列を返すのではなく、トップレベル uri.

Library とカメラフロー

Library フローから始めて、機能が動作する最速のパスを得たい場合は、最も簡単にテストできる。シミュレーターの設定で動作することも多く、カメラハードウェアのエッジケースを回避できる。結果の処理パスが安定したらカメラサポートを追加する。

カメラパスは開発時には失敗の方法が多くある。iOS シミュレーターのサポートは限られている。Android エミュレータでは、実機と同じカメラの動作を表現できないことがある。バレプロジェクトでは、実際の問題はネイティブの設定やテスト環境である可能性があるが、コンポーネント code を確認することになる。

ユーザーからソースを要求するUIパターンは、ピッカー API を呼ぶ前にユーザーに質問することである。

const showPickerOptions = () => {
  Alert.alert('Upload image', 'Choose a source', [
    { text: 'Camera', onPress: takePhoto },
    { text: 'Photo Library', onPress: pickFromLibrary },
    { text: 'Cancel', style: 'cancel' },
  ]);
};

それぞれの機能が集中しやすく、分析、機能フラグ、バックエンド固有のルールを後から追加することも容易になる。例えば、プロフィール画像のアップロードはライブラリから許可するが、身元確認の場合には新しいカメラキャプチャを要求するチームもある。

アプリがExpo以外のファイルアクセスパターンをサポートしている場合、またはネイティブスタック間でコンヴェンションを比較している場合、この Capacitor 画像ライブラリのリファレンスは参考になる。

短いデモは、チームメンバーやQAにこのフローを紹介する際に役立つ。

システムUIで期待されるもの

expo-image-picker iOSでは、ユーザーは完全なアクセス権限の代わりに、限定されたライブラリへのアクセスを許可することができます。 Androidでは、ピッカーの動作はOSバージョンとベンダースキンによって異なります。マネージドワークフロープロジェクトでは、エクスポはより多くのネイティブのワイヤリングを取り扱います。バーレスワークフロープロジェクトでは、ネイティブの許可変更が含まれるように、ビルドされたアプリを確認する必要があります。 JavaScriptの呼び出しサイトは両方のケースで同じままですが、実行時結果は異なります。

iOSでは、ユーザーは完全なアクセス権限の代わりに、限定されたライブラリへのアクセスを許可することができます。 Androidでは、ピッカーの動作はOSバージョンとベンダースキンによって異なります。マネージドワークフロープロジェクトでは、エクスポはより多くのネイティブのワイヤリングを取り扱います。バーレスワークフロープロジェクトでは、ネイティブの許可変更が含まれるように、ビルドされたアプリを確認する必要があります。 JavaScriptの呼び出しサイトは両方のケースで同じままですが、実行時結果は異なります。

通常、次のケースをテストすることから始めます:

最初の許可要求
許可が拒否された
ユーザーのキャンセル
ライブラリの選択が成功した
物理デバイス上のカメラのキャプチャが成功した
返されたローカルURIの即時プレビュー

これらのケースは直接実際の生産動作にマップされます。また、必要に応じてファイルをサーバー、モデレーションパイプライン、または公開エンドポイントであるインスタグラムのメディア出版API.

ピッカーの結果とオプションの取り扱い

ピッカーの結果は、通常、実際の生産ロジックが必要な部分です。システムUIは構造化されたオブジェクトを返しますが、ファイルパスだけではありません。ここで小さな間違いが原因で、プレビューが破損したり、ユーザーがキャンセルした後アップロードが空になったり、クラッシュしたりします。

結果オブジェクトを正しく読む

現在のExpoアプリでは重要なのは結果の形状です result.assets[0].uri、トップレベル result.uriJavaScript APIは、管理されたワークフローと裸のワークフロー両方のプロジェクトに影響します。

guard-firstパターンを使用します:

const result = await ImagePicker.launchImageLibraryAsync({
  mediaTypes: ['images'],
  allowsEditing: true,
  quality: 1,
});

if (result.canceled) {
  return;
}

const asset = result.assets?.[0];
if (!asset) {
  return;
}

const { uri } = asset;
setImageUri(uri);

これは、キャンセルされたピッカーがアセットを提供しない場合と、codeが常に存在すると仮定してしまう場合の2つの失敗ケースをハンドルします。 result.assets[0] URIが得られたら、プレビューのレンダリングは簡単です:

アップロードする予定の場合、URIだけでなく、結果オブジェクト全体を保持しておきましょう。実際には、

<Image source={{ uri: imageUri }} style={{ width: 240, height: 240 }} />

、 asset 、 fileName, mimeType, width, height、 fileSize は、検証、ログ、またはクリアな多部要件の作成に便利です。

下流の動作を変更するオプション

いくつかのピッカーオプションは、選択画面に影響を与えるだけでなく、ファイルサイズ、編集の動作、バックエンドが受け入れる必要があるものもあります。

オプション	種類	変更すること	一般的な使用方法
`mediaTypes`	配列	ユーザーが選択できるものを制限します。	画像のみを選択できるように制限するには、API が画像のみを受け入れるように設定します。
`allowsEditing`	ブール値	OSがサポートする場合に、クロップまたは編集UIを提供します。	アイコン、正方形のカバー、領収書のキャプチャ
`quality`	数値	サポートされている画像出力の圧縮	モバイルネットワークのアップロードサイズを削減
`base64`	ブール値	結果にエンコードされた画像データを追加	明示的にインライン画像データを必要とする統合のみに適用

いくつかの取引は簡単に見過ごされる:

allowsEditing 画像スロットが固定形状またはサイズを持つ場合に便利です。サーバーが独自のクロップパイプラインを実行し、元のファイルを取得したい場合は、こちらはあまり役に立ちません。
quality アップロード時間、メモリ圧力、サーバーストレージに影響します。 quality: 1 自動的に正解ではありません。
mediaTypes バックエンドのルールと一致するようにしてください。サーバーが動画を拒否する場合、ピッカーが動画を返さないようにしてください。
base64 メモリ内でのパイロットサイズを増やす。受信サービスがそれを必要とする場合を除いて避けること。

その最後の点は、メモリが少ないデバイスでは重要です。ローカルファイルURIは、プレビューとマルチパートアップロードのためのよりよいハンドオフです。Base64は有効な使用例がありますが、ファイル参照を渡すことと比較して高価です。

URIとBase64

ほとんどのアプリでは、ルールは簡単です:

Use URI Base64
Use URI URI
Use base64 受け取るシステムがエンコードされたコンテンツを明示的に要求する場合にのみ使用します。

このパターンは、ピッカーをcode小さく、テストしやすくするのに役立ちます。また、多くのバックエンドメディアフローが構築されているように、サービスが最終的に外部プラットフォームに公開するサービスも含まれます。 Instagramのメディア出版API.

チームが頻繁にOTA更新を配信したり、画像重いアセットをアプリ配信で移動したりする場合、この決定はパイプラインの残りの部分に影響を与える可能性があります。このガイドはアプリ更新用の画像の最適化の設定と組み合わせることが役立ちます。

実用的なアプリ用の安全な結果パターン

デモcodeの場合、ストレージに保存する必要があるのは imageUri のみです。生産環境では、次のステップであるプレビュー、検証、アップロード、またはリトライのために、ピッカーの元のレスポンスを再解釈する必要がなくなるように、正規化されたオブジェクトを保存することをお勧めします。

const result = await ImagePicker.launchImageLibraryAsync({
  mediaTypes: ['images'],
  allowsEditing: true,
  quality: 0.8,
});

if (result.canceled || !result.assets?.length) {
  return;
}

const asset = result.assets[0];

setSelectedImage({
  uri: asset.uri,
  fileName: asset.fileName ?? 'upload.jpg',
  mimeType: asset.mimeType ?? 'image/jpeg',
  width: asset.width,
  height: asset.height,
  fileSize: asset.fileSize ?? null,
});

これにより、1つの予測可能な形状がアプリ内に保たれ、ネイティブの差異を他の場所で処理しながら、管理されたプロジェクトと裸のプロジェクトを同期しやすくなります。アプリcodeは安定し続けます。

最後のチェックも役立ちます。追加の結果フィールドを有効にしないでください。必要なデータを要求し、ピッカーを選択に集中させ、一般的なファイル処理ステップに変えるのではなく、ピッカーを集中させます。

高度なパターンとプラットフォームの差異

A picker feature is usually not simple when the first selected image must survive retries, auth headers, native permission differences, and a real upload endpoint. expo-image-picker selection is handled well. The rest of the feature is up to your app.

サーバーストレージの利点と欠点を比較検討するグラフィックのタイトル「画像のアップロード：ローカルストレージとサーバーストレージの考慮事項」

実用的なアップロードパターン

APIがファイルアップロードを期待する場合、 FormData separate upload and transport is still the safest default. It works across common Rails, Node, Laravel, Django, and Go backends, and it keeps the picker separate from transport concerns.

async function uploadImage(imageUri: string) {
  const formData = new FormData();

  formData.append('file', {
    uri: imageUri,
    name: 'upload.jpg',
    type: 'image/jpeg',
  } as any);

  const response = await fetch('https://your-api.example.com/uploads', {
    method: 'POST',
    body: formData,
    headers: {
      Accept: 'application/json',
    },
  });

  if (!response.ok) {
    throw new Error('Upload failed');
  }

  return response.json();
}

Derive code では十分ですが、実用的なアプリではさらに１層が必要です。 name and type context:Capgo marketing website. Role:Short UI label or navigation item. Seen in:page trust.astro. Message key `and` (And).

レビューでよく見る一般的なエラーを防ぐために、いくつかのチェックが実行されます。

A few checks prevent the common failures I see in review: uri リクエストの作成前に存在する
アップロード前にプレビューを表示することで、ユーザーが間違ったファイルを早期に検出できるようにする
リクエストが送信中の間、繰り返しタップを防ぐ
ネットワークエラー、ピッカーのキャンセル、またはパーミッションエラーを別々に処理する
バックエンドの検証で大きいファイル、サポートされていないMIMEタイプ、または認証情報の欠如を拒否することを期待する

バックエンドがbase64代わりにmultipartを要求する場合、それは通常サーバーの制約であり、ピッカーの要件ではない。Multipartはメモリのコストが安く、モバイルで推論しやすい。

プラットフォームの違いが実際に重要な場合

ピッカーのUIはネイティブなので、ネイティブの動作を継承する。ユーザーが見るものと、codeが仮定するものの両方に影響を与える。

iOSでは、編集フローとパーミッションプロンプトはAppleの規範に従う。Photosに制限されたアクセスを返すと、完全に許可されたデバイスでテストアカウントが見たよりも狭いアセットのセットが返される。Androidでは、ピッカーの動作はOSバージョンとメーカーのスキンによってより多く異なる。特にアルバム、ファイル名、カメラキャプチャが返される方法について。 Bare React Nativeアプリでは、これらの差異を直接感じるが、管理されたExpoアプリでも、ピッカーをプラットフォームに合わせたものとして扱うcodeが必要である。

実用的なルールは簡単だ。検証できるフィールドに依存するのではなく、デバイス間でUIやメタデータが同一であることを期待するのではなく。

実際のアプリケーションでは、以下の例が重要である。

編集とクロップ: UIとクロップの動作はiOSとAndroidで同一ではない
取得されたメタデータ: fileName, mimeType, and fileSize が欠如または不一致になる可能性があるため、代替値を追加します
権限: iOSの写真アクセスは選択されたアイテムに制限できる一方、Androidの動作はOSバージョンとシステムピッカーのサポートに依存する
カメラ出力: キャプチャされた画像はライブラリアセットと異なる名前、向き、圧縮特性を持って戻ってくる可能性がある

あなたのチームもExpo外で作業している場合、この DesignStackアプリ開発ガイドは、メディアハンドリングの決定を示すAndroidのコンテキストを提供する

管理されたワークフローと裸のワークフローの違い

この時点で、セットアップの選択肢は実行上の意味を持ち始める

管理ワークフローでは、許可文字列とプラグイン設定は通常アプリ設定内にあり、ネイティブの変更はビルドを作成するたびに適用されます。JavaScriptの表面面積がきれいになるため、ですが、設定の修正は次のネイティブのビルドまで視認できません。OTAの更新は欠落しているネイティブの許可を修正しません。

バーレスワークフローでは、同じ機能にはより多くの要素が存在します。iOSのネイティブの使用説明、Androidのマニフェストの動作、パッケージのインストール、ビルドのタイミングを自分で確認する必要があります。コントロールが得られるのは良いことですが、ピッカーの問題はネイティブの設定によっても起こり得ます。

チームは、ExpoとCapacitorの間で頻繁に切り替わることが多いが、抽象化レイヤー間の違いを十分に理解していないことが多い。 Capgoは、以下の説明を提供している。 how Capacitor handles platform differences一般的な問題のトラブルシューティング

My preference is consistent across both workflows. Keep picker code narrow, normalize the result once, upload through a dedicated API layer, and treat platform-specific behavior as something to configure and test explicitly rather than smooth over with assumptions.

__CAPGO_KEEP_0__

__CAPGO_KEEP_1__

A mobile development projectでexpo-image-pickerライブラリを使用する際の一般的な問題のトラブルシューティングチェックリスト。

一般的なエラーの高速チェック

ピッカーが開かないか、パーミッションが失敗した場合、まずネイティブの設定を確認してください。特にバーレスアプリでは、iOSの使用説明文が欠けていることが一般的な原因です。

ユーザーがピッカーを閉じた後、アプリがクラッシュした場合、結果の処理を確認してください。多くの実装では、直接URIを想定し、結果のチェックをスキップしています。 canceled check.

パーミッションが拒否されたエラー:

アプリの設定とネイティブのパーミッション文字列を確認し、再構築してください。 image URI:
undefined 結果から読み取る 、ではなく result.assets?.[0]?.uri, not result.uri.
キャンセル後に何も起こらない: 正しくありませんか。キャンセルを無視する状態として扱います。
画像が表示されません: URIが保存された状態と渡されたことを確認します。 <Image source={{ uri }} />.
シミュレータでカメラが奇妙に動作する場合: 物理デバイスでテストする前にライブラリのバグを追跡するのをやめましょう。

短い本番用チェックリスト

本番用に使用する最後のチェック:

Expoツールを使用してインストール: 使用: npx expo install expo-image-picker.
ネイティブの部分を設定: プラグインと必要なパーミッションの説明を追加します。
意図的にパーミッションを要求します: カメラとメディアライブラリのフローを分離する。
結果を守る: チェック result.canceled 安全に読み取る assets[0].
URIベースのアップロードを優先する: 特殊なケースのみにbase64を残す。
実機でテストする: 特にカメラキャプチャとパーミッションのプロンプトの場合。

チームがReact Nativeプロジェクトと並行してCapacitorまたはElectronアプリをリリースする場合、 Capgo Capgo

2026年のためのエクスポイメージピッカー完全ガイド