String.prototype.includes()

includes() メソッドは、1 つの文字列を別の文字列の中に見出すことができるかどうかを判断し、必要に応じて true か false を返します。

このデモのソースファイルは GitHub リポジトリに格納されています。デモプロジェクトに協力したい場合は、https://github.com/mdn/interactive-examples をクローンしてプルリクエストを送信してください。

構文

str.includes(searchString[, position])

引数

searchString

この str 内で検索される文字列。

position Optional

任意。searchString を検索し始めるこの String 内の位置。(デフォルトは 0 です。)

返値

文字列が検索値を含む場合、true。含まなければ、false。

解説

このメソッドによってある文字列内に別の文字列を含んでいるかどうか判断できます。

大文字・小文字の区別

includes() メソッドは大文字と小文字が区別します。例えば、次のコードでは false を返します:

'Blue Whale'.includes('blue'); // returns false

例

includes() を使う

const str = 'To be, or not to be, that is the question.' 

console.log(str.includes('To be'))        // true
console.log(str.includes('question'))     // true
console.log(str.includes('nonexistent'))  // false
console.log(str.includes('To be', 1))     // false
console.log(str.includes('TO BE'))        // false
console.log(str.includes(''))             // true

ポリフィル

このメソッドは ECMAScript 2015 で追加されました。まだ、すべての JavaScript の実装で利用できるとは限りません。

しかしながら、このメソッドを簡単にエミュレートできます:

if (!String.prototype.includes) {
  String.prototype.includes = function(search, start) {
    'use strict';

    if (search instanceof RegExp) {
      throw TypeError('first argument must not be a RegExp');
    } 
    if (start === undefined) { start = 0; }
    return this.indexOf(search, start) !== -1;
  };
}

仕様書

ブラウザー実装状況

このページの互換性一覧表は構造化データから生成されています。データに協力していただけるのであれば、https://github.com/mdn/browser-compat-data をチェックアウトしてプルリクエストを送信してください。

String.prototype.contains

Firefox 18–39 では、このメソッドの名称は contains() でした。バグ 1102219 で includes() に名称が変更されました。理由は次のとおりです:

MooTools 1.2 を使用したいくつかのウェブサイトは Firefox 17 で壊れたと報告がありました。MooToolsのこのバージョンでは、String.prototype.contains() が存在するかどうか調べ、存在しない場合は追加します。

Firefox 17 でこの関数を紹介して、そのチェックの動作が壊れる MooTools の String.prototype.contains() の実装に基づいたコードの原因となる方法で変更されました。結果として、この変更は Firefox 17 で無効になりました。MooTools への働きかけで MooTools 1.2.6 リリースが出され、String.prototype.contains() は Firefox 18 以降で利用可能となりました。

MooTools 1.3 では String.prototype.contains() の自身のバージョンに強要しました。そのため、これに依存するウェブサイトは壊れませんでした。しかしながら、このメソッドに対する MooTools 1.3 シグニチャと ECMAScript 2015 シグニチャでは (第 2 引数に) 違いがあることに注意して下さい。MooTools 1.5+ は ES2015 仕様に一致させるためにシグニチャを変更しました。

Firefox 48 で、String.prototype.contains() は削除されました。String.prototype.includes() だけ使用できます。

関連情報

• Array.prototype.includes()
• TypedArray.prototype.includes()
• String.prototype.indexOf()
• String.prototype.lastIndexOf()
• String.prototype.startsWith()
• String.prototype.endsWith()