filter

http://docs.angularjs.org/api/ng.filter:filter

概要
使用方法
デモ

概要

配列から一部を選択し、それを新しい配列として返します。

使用方法

HTMLテンプレート

{{ filter_expression | filter:expression:comparator }}

JavaScript

$filter('filter')(array, expression, comparator)

引数

引数説明

array

引数	説明
array	型：`Array` 対象となる基の配列を指定します。
expression	型：`string`、`Object`、`function` 配列から、項目を選択するのに使用する方法を指定します。下記の中から1つ選ぶことが可能です。 `string` 文字列式の値を使用した、文字列の部分にマッチした結果の事前宣言式です。全ての文字列または配列でこの文字列を含む文字列のプロパティを持つオブジェクトが返されます。文字列のプレフィックスとして`!`を付けると、事前宣言式を否定にすることが出来ます。 `Object` 配列に含まれるオブジェクトの特定のプロパティをフィルタリングするのに使用されるパターンのオブジェクトを指定します。例えば、`{name:"M", phone:"1"}`の事前宣言式は、nameプロパティに"M"が含まれ、 phoneプロパティに"1"が含まれる項目の配列を返します。特別なプロパティ名`$`は、オブジェクトのどのプロパティに対しても、マッチすることを容認する際に使用(`{$:"text"}`として)されます。これは、単純に上述した文字列での部分文字列マッチと等価になります。 `function` 事前宣言式の関数を使用すれば、任意のフィルターを書くことが出来ます。関数は配列の各要素から呼び出されます。最終的に、事前宣言式がtrueを返した要素の配列となります。
comparator	型：`function(expected, actual)`、`true`、`undefined` 期待する(expected)値(フィルター式より)と実際(actual)の値(配列のオブジェクトから)が、どのようにしてマッチしているとみなされるべきかを決定するのに使用される比較のための手段です。下記から1つ、方法を選ぶことが可能です。 `function(expected, actual)` 関数には比較のために、オブジェクトの値と事前宣言式の値が与えられ、もし項目がフィルタリングした結果に含まれているとされた場合には、trueを返すようにします。 `true` これは、下記の略記になります。実際には期待した値と実際の値の厳格な比較になります。 `function(expected, actual){ return angular.equals(expected, actual) }` `false\|undefined` 部分文字列のマッチにおいて大文字・小文字を区別しないで検索をする関数の略記になります。

型：Array

対象となる基の配列を指定します。

expression

型：string、Object、function

配列から、項目を選択するのに使用する方法を指定します。

下記の中から1つ選ぶことが可能です。

string: 文字列式の値を使用した、文字列の部分にマッチした結果の事前宣言式です。全ての文字列または配列でこの文字列を含む文字列のプロパティを持つオブジェクトが返されます。文字列のプレフィックスとして!を付けると、事前宣言式を否定にすることが出来ます。
Object: 配列に含まれるオブジェクトの特定のプロパティをフィルタリングするのに使用されるパターンのオブジェクトを指定します。例えば、{name:"M", phone:"1"}の事前宣言式は、nameプロパティに"M"が含まれ、 phoneプロパティに"1"が含まれる項目の配列を返します。特別なプロパティ名$は、オブジェクトのどのプロパティに対しても、マッチすることを容認する際に使用({$:"text"}として)されます。これは、単純に上述した文字列での部分文字列マッチと等価になります。
function: 事前宣言式の関数を使用すれば、任意のフィルターを書くことが出来ます。関数は配列の各要素から呼び出されます。最終的に、事前宣言式がtrueを返した要素の配列となります。

comparator

型：function(expected, actual)、true、undefined

期待する(expected)値(フィルター式より)と実際(actual)の値(配列のオブジェクトから)が、どのようにしてマッチしているとみなされるべきかを決定するのに使用される比較のための手段です。下記から1つ、方法を選ぶことが可能です。

function(expected, actual)

関数には比較のために、オブジェクトの値と事前宣言式の値が与えられ、もし項目がフィルタリングした結果に含まれているとされた場合には、trueを返すようにします。

true

これは、下記の略記になります。実際には期待した値と実際の値の厳格な比較になります。

function(expected, actual){
  return angular.equals(expected, actual)
}

false|undefined

部分文字列のマッチにおいて大文字・小文字を区別しないで検索をする関数の略記になります。

<!doctype html>
<html ng-app>
  <head>
    <script src="http://code.angularjs.org/1.2.0-rc.2/angular.min.js"></script>
  </head>
  <body>
    <div ng-init="friends = [{name:'John', phone:'555-1276'},
                             {name:'Mary', phone:'800-BIG-MARY'},
                             {name:'Mike', phone:'555-4321'},
                             {name:'Adam', phone:'555-5678'},
                             {name:'Julie', phone:'555-8765'},
                             {name:'Juliette', phone:'555-5678'}]"></div>

    Search: <input ng-model="searchText">
    <table id="searchTextResults">
      <tr><th>Name</th><th>Phone</th></tr>
      <tr ng-repeat="friend in friends | filter:searchText">
        <td>{{friend.name}}</td>
        <td>{{friend.phone}}</td>
      </tr>
    </table>
    <hr>
    Any: <input ng-model="search.$"> <br>
    Name only <input ng-model="search.name"><br>
    Phone only <input ng-model="search.phone"><br>
    Equality <input type="checkbox" ng-model="strict"><br>
    <table id="searchObjResults">
      <tr><th>Name</th><th>Phone</th></tr>
      <tr ng-repeat="friend in friends | filter:search:strict">
        <td>{{friend.name}}</td>
        <td>{{friend.phone}}</td>
      </tr>
    </table>
  </body>
</html>

it('should search across all fields when filtering with a string', function() {
  input('searchText').enter('m');
  expect(repeater('#searchTextResults tr', 'friend in friends').column('friend.name')).
    toEqual(['Mary', 'Mike', 'Adam']);

  input('searchText').enter('76');
  expect(repeater('#searchTextResults tr', 'friend in friends').column('friend.name')).
    toEqual(['John', 'Julie']);
});

it('should search in specific fields when filtering with a predicate object', function() {
  input('search.$').enter('i');
  expect(repeater('#searchObjResults tr', 'friend in friends').column('friend.name')).
    toEqual(['Mary', 'Mike', 'Julie', 'Juliette']);
});
it('should use a equal comparison when comparator is true', function() {
  input('search.name').enter('Julie');
  input('strict').check();
  expect(repeater('#searchObjResults tr', 'friend in friends').column('friend.name')).
    toEqual(['Julie']);
});

<!doctype html>
<html ng-app>
  <head>
    <script src="http://code.angularjs.org/1.2.0-rc.2/angular.min.js"></script>
  </head>
  <body>
    <div ng-init="friends = [{name:'John', phone:'555-1276'},
                             {name:'Mary', phone:'800-BIG-MARY'},
                             {name:'Mike', phone:'555-4321'},
                             {name:'Adam', phone:'555-5678'},
                             {name:'Julie', phone:'555-8765'},
                             {name:'Juliette', phone:'555-5678'}]"></div>

    Search: <input ng-model="searchText">
    <table id="searchTextResults">
      <tr><th>Name</th><th>Phone</th></tr>
      <tr ng-repeat="friend in friends | filter:searchText">
        <td>{{friend.name}}</td>
        <td>{{friend.phone}}</td>
      </tr>
    </table>
    <hr>
    Any: <input ng-model="search.$"> <br>
    Name only <input ng-model="search.name"><br>
    Phone only <input ng-model="search.phone"><br>
    Equality <input type="checkbox" ng-model="strict"><br>
    <table id="searchObjResults">
      <tr><th>Name</th><th>Phone</th></tr>
      <tr ng-repeat="friend in friends | filter:search:strict">
        <td>{{friend.name}}</td>
        <td>{{friend.phone}}</td>
      </tr>
    </table>
  </body>
</html>

このページは、ページトップのリンク先のAngularJS公式ドキュメント内のページを翻訳した内容を基に構成されています。下記の項目を確認し、必要に応じて公式のドキュメントをご確認ください。もし、誤訳などの間違いを見つけましたら、 @tomofまで教えていただければ幸いです。

AngularJSの更新頻度が高いため、元のコンテンツと比べてドキュメントの情報が古くなっている可能性があります。
"訳注:"などの断わりを入れた上で、日本人向けの情報やより分かり易くするための追記を行っている事があります。