TypeScriptのmap()で発生する「key」エラーとその適切な解決策🛠️

はじめに (対象読者・この記事でわかること)

この記事は、ReactとTypeScriptを用いて開発を行っているエンジニア、特にJSX内で配列のmap()メソッドを使ってリスト要素をレンダリングする際に、コンソールにkeyに関するWarningが表示されて困った経験がある方を対象としています。

この記事を読むことで、Reactにおけるリストレンダリングの仕組みとkeyプロパティの重要性について深く理解できます。また、map()使用時に発生する「keyエラー」の原因とその具体的な解決策、さらにはkeyとしてどのような値を選択すべきか、避けるべき選択肢は何かを明確に把握し、より堅牢でパフォーマンスの高いReactアプリケーションを構築できるようになります。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。 - Reactの基本的な知識 (コンポーネント、JSX、状態管理の概念) - TypeScriptの基本的な知識 (型定義、インターフェース) - JavaScriptの配列メソッド (map())

Reactのリストレンダリングにおけるkeyの重要性

Reactアプリケーションにおいて、複数の要素をリストとして表示することは非常に一般的です。例えば、ユーザーリスト、商品一覧、ToDoリストなどがこれに該当します。これらのリストをレンダリングする際、JavaScriptのArray.prototype.map()メソッドを使用して、配列の各要素をReact要素に変換し、表示することが多いでしょう。

しかし、このとき、Reactはリスト内の各要素に対して一意な識別子であるkeyプロパティを要求します。もしkeyが指定されていないか、適切でない場合、以下のようなコンソール警告が表示されます。

Warning: Each child in a list should have a unique "key" prop.

このkeyは、Reactがリスト内のどのアイテムが変更、追加、削除されたかを効率的に識別するために非常に重要です。Reactは仮想DOM（Virtual DOM）という概念を用いてUIの更新を最適化していますが、リストのような動的な要素の場合、keyがないと各アイテムの識別が困難になります。

具体的に何が問題になるかというと、keyがないとReactはリストのアイテムの順序が変更されたり、途中でアイテムが追加・削除されたりした場合に、どの要素が変更されたのかを正確に追跡できません。その結果、不要なDOM操作が発生し、アプリケーションのパフォーマンスが低下したり、状態が正しく引き継がれずに意図しないバグが発生したりする可能性があります。例えば、入力フォームを含むリストでkeyが不適切だと、リストの並び替えを行った際にユーザーが入力した内容が別の要素に紐付いてしまう、といった問題が起こりえます。

したがって、リストをレンダリングする際には、必ず一意かつ安定したkeyを各リストアイテムに割り当てることが、Reactのパフォーマンスと正確性を保証する上で不可欠なのです。

TypeScriptとReactにおけるmap()使用時のkeyエラーの具体的な解決策

ReactとTypeScriptを用いてmap()でリストをレンダリングする際に直面するkeyエラーは、適切なkeyの選び方と指定方法を理解することで解決できます。ここでは、具体的なコード例を交えながら、その解決策を詳しく見ていきましょう。

ステップ1: keyエラーの再現と発生原因の理解

まずは、keyエラーがどのように発生するかをシンプルな例で確認します。 以下は、keyプロパティを指定せずにリストをレンダリングするReactコンポーネントの例です。

Tsx

import React from 'react';

// アイテムの型定義
interface Item {
  id: number; // 通常、一意なIDを持つことを想定
  name: string;
}

const items: Item[] = [
  { id: 1, name: 'Apple' },
  { id: 2, name: 'Banana' },
  { id: 3, name: 'Orange' },
];

function ItemListBroken() {
  return (
    <div>
      <h2>Keyエラーが発生する例</h2>
      <ul>
        {items.map(item => (
          // ここでkeyプロパティが指定されていないため、警告が発生
          <li>{item.name}</li>
        ))}
      </ul>
    </div>
  );
}

export default ItemListBroken;

このコードを実行すると、ブラウザの開発者ツールのコンソールに次のような警告が表示されます。 Warning: Each child in a list should have a unique "key" prop.

この警告は、Reactがリスト内の各<li>要素を識別するために必要なkeyプロパティが欠落していることを示しています。Reactは、map()などで繰り返しレンダリングされる要素に対して、それぞれに紐づくユニークなkeyを要求します。これにより、要素の追加、削除、並び替えが発生した際に、どの要素が変更されたかを効率的に追跡し、DOMの更新を最適化するのです。keyがないと、Reactは要素を識別できず、無駄な再レンダリングや、特にリストが動的に変化する場合に予期しない動作を引き起こす可能性があります。

ステップ2: keyの正しい指定方法

keyプロパティの最も理想的な値は、リスト内の各アイテムに存在する一意で安定したIDです。これは通常、データベースの主キーや、UUID（Universally Unique Identifier）などが該当します。

例えば、上記のItemインターフェースにidプロパティがある場合、それをkeyとして利用するのが最適です。

Tsx

import React from 'react';

interface Item {
  id: number; // 各アイテムに一意なIDがある
  name: string;
}

const items: Item[] = [
  { id: 101, name: 'Apple' },
  { id: 102, name: 'Banana' },
  { id: 103, name: 'Orange' },
];

function ItemListCorrect() {
  return (
    <div>
      <h2>Keyを正しく指定した例</h2>
      <ul>
        {items.map(item => (
          // item.id は各アイテムに一意であり、変更されないため、最適なkeyとなる
          <li key={item.id}>{item.name}</li>
        ))}
      </ul>
    </div>
  );
}

export default ItemListCorrect;

このようにkey={item.id}と指定することで、Reactは各<li>要素をidで一意に識別できるようになり、上記の警告は解消されます。また、リストアイテムの並び替えや追加・削除が発生しても、ReactはDOMを効率的かつ正確に更新できます。

indexをkeyに使う場合の注意点

稀に、データに一意なIDが存在しない場合や、単に簡単に済ませたいという理由で、map()メソッドの第2引数として渡されるindex（配列のインデックス）をkeyとして使用する例が見られます。

Tsx

import React from 'react';

const itemsWithoutId: string[] = ['Apple', 'Banana', 'Orange'];

function ItemListWithIndexKey() {
  return (
    <div>
      <h2>indexをkeyに使った例（注意が必要）</h2>
      <ul>
        {itemsWithoutId.map((name, index) => (
          // indexをkeyとして使用
          <li key={index}>{name}</li>
        ))}
      </ul>
    </div>
  );
}

export default ItemListWithIndexKey;

この方法でもコンソールの警告は消えますが、これは推奨されません。 indexをkeyとして使うべきではない主な理由は以下の通りです。

1. リストの並び替え、追加、削除に弱い: リスト内のアイテムが並び替えられたり、途中で新しいアイテムが追加されたり、既存のアイテムが削除されたりすると、それぞれのアイテムに割り当てられていたindexが変わってしまいます。Reactはkeyが変更された要素を「新しい要素」として扱ってしまうため、本来は変更がなかったDOM要素も再構築されてしまい、パフォーマンスの低下や、入力フィールドの状態が予期せず変わるといったバグの原因となります。

2. パフォーマンスの低下: keyが不安定なため、Reactはアイテムの移動を正確に追跡できず、古いDOM要素を破棄して新しいDOM要素を作成するといった非効率な操作を行うことがあります。

indexをkeyとして使用しても許容される唯一のケース:

• リストとそのアイテムが静的であり、将来にわたって変更（追加、削除、並び替え）されないことが保証されている場合。
• リスト内のアイテムに安定したIDが存在しない場合で、かつ上記のようなリストの変更が発生しないことが確実な場合。

これらの条件を満たさない限り、indexをkeyとして使用することは避けるべきです。

ハマった点やエラー解決

多くの開発者がkeyエラーに遭遇する典型的なケースは、以下のような状況です。

1. indexを安易にkeyとして使用していた: Reactの公式ドキュメントや多くの記事で「keyは一意であるべき」と書かれているものの、「とりあえず警告を消すためにindexを使えばいい」と誤解してしまうケースです。しかし前述の通り、indexはリストが動的に変化する場合には適しません。

2. データに一意なIDがない: バックエンドから取得したデータや、フロントエンドで生成したデータに、一意なIDプロパティが最初から含まれていない場合、どの値をkeyとして使えばよいか迷うことがあります。この場合、item.nameのような表示名をkeyにしようとするかもしれませんが、名前が重複する可能性があったり、変更される可能性があったりするため、これも安定したkeyとは言えません。

3. Warningメッセージを見落とす/無視する: 開発中にWarningが大量に出ていると、つい見落としてしまったり、「Warningだから大丈夫だろう」と無視してしまったりすることがあります。しかし、keyに関するWarningは、後々のバグやパフォーマンス問題の温床となるため、決して無視してはいけません。

解決策

上記のハマりどころに対する解決策は以下の通りです。

1. データに一意なIDを付与する:

   • 最も推奨される方法: サーバーサイドでデータを生成する際に、データベースの主キー（例: id）やUUIDなどのユニークな識別子を必ず含めて返してもらうように設計します。
   • クライアントサイドでIDを生成: もしサーバーから取得したデータにIDがない場合や、フロントエンドで動的に生成するデータの場合、クライアントサイドでUUID生成ライブラリ（例: uuidパッケージ）を利用して、各アイテムに一意なIDを付与してからレンダリングします。

   ```tsx import React from 'react'; import { v4 as uuidv4 } from 'uuid'; // uuidパッケージをインストールして使用

   interface Item { id: string; // UUIDを想定してstring型に name: string; }

   // IDがない元データ const rawItems: { name: string }[] = [ { name: 'Red Pen' }, { name: 'Blue Pen' }, { name: 'Red Pen' }, // 名前が重複する可能性もある ];

   // レンダー前にIDを付与する例 const processedItems: Item[] = rawItems.map(item => ({ ...item, id: uuidv4(), // 各アイテムに一意なUUIDを付与 }));

   function ItemListWithGeneratedKey() { return (

   UUIDをkeyに使った例

   {processedItems.map(item => (
   • {item.name}
   ))}
   ); }

   export default ItemListWithGeneratedKey; `` この方法であれば、元データにIDがなくても、安定した一意なkey`を確保できます。

2. keyの必要性を理解し、Warningを積極的に解消する: keyは単なる警告ではなく、アプリケーションの安定性とパフォーマンスに直結する重要な要素であるという認識を持つことが重要です。コンソールにkeyに関するWarningが表示されたら、必ずその場で適切なkeyを指定し、解消するように努めましょう。

これらの解決策を実践することで、Reactのリストレンダリングにおけるkeyエラーを効果的に防ぎ、より堅牢でパフォーマンスの高いアプリケーション開発が可能になります。

まとめ

本記事では、ReactとTypeScriptを用いた開発において、map()メソッドでリスト要素をレンダリングする際に発生する「keyエラー」の原因と、その適切な解決策について詳しく解説しました。

• keyはReactがリストアイテムを効率的に識別するために不可欠なプロパティです。 keyがないと、パフォーマンスの低下や予期せぬバグの原因となります。
• keyは一意かつ安定した値であるべきです。 最も理想的なのは、データのユニークなID（データベースの主キーやUUIDなど）を使用することです。
• indexをkeyとして使うのは避けるべきです。 特に、リストのアイテムが追加、削除、または並び替えられる可能性がある場合には、indexは不安定なkeyとなり、バグを引き起こすリスクがあります。どうしてもIDがない場合は、UUIDなどを生成して割り当てるのがより良いアプローチです。

この記事を通して、Reactのkeyプロパティの重要性を深く理解し、今後の開発でkeyエラーに遭遇することなく、より効率的で堅牢なリストレンダリングを実装できるようになることを願っています。

今後は、Reactのパフォーマンス最適化においてkeyがどのように寄与するか、またReact.memoなどの他の最適化手法との組み合わせについても記事にする予定です。

参考資料

• React 公式ドキュメント: リストと Key
• MDN Web Docs: Array.prototype.map()
• npm: uuid (UUID生成ライブラリ)