--- title: "メッセージフレームワーク" version: 6.1 locale: ja source: https://docs.djangoproject.com/ja/6.1/ref/contrib/messages/ canonical: https://djangodocs.dev/ja/6.1/ref/contrib/messages/ --- # メッセージフレームワーク Web アプリケーションでは非常に一般的に、フォームやその他のユーザーインプットのプロセスの後、ユーザーに向けて一過性の通知メッセージ ("フラッシュメッセージ" とも言われます) を表示する必要があります。 Django は、anonymous および認証済みユーザーの両方に対して、Cookie とセッションをベースにしたメッセージングを完全にサポートしています。このメッセージフレームワークは、一時的に一つのリクエスト内にメッセージを保管し、その後のリクエスト (通常、直後のリクエスト) 内で表示するために、これらを検索することを可能にします。全てのメッセージは、優先順位 (たとえば `info`、`warning`、`error`) を決定づける特定の `level` でタグづけされます。 ## メッセージを有効にする メッセージは、 [ミドルウェア](/ja/6.1/ref/middleware/) クラスと、それに対応する [コンテキストプロセッサー](/ja/6.1/ref/templates/api/) を通して実行されます。 `django-admin startproject` によって生成されたデフォルトの `settings.py` は、メッセージ機能を有効にするために必要な設定を全て含んでいます: - `'django.contrib.messages'` は、[`INSTALLED_APPS`](/ja/6.1/ref/settings/#std-setting-INSTALLED_APPS) の中にあります。 - [`MIDDLEWARE`](/ja/6.1/ref/settings/#std-setting-MIDDLEWARE) は `'django.contrib.sessions.middleware.SessionMiddleware'` と `'django.contrib.messages.middleware.MessageMiddleware'` を含みます。 デフォルトの [ストレージバックエンド](#message-storage-backends) は [sessions](/ja/6.1/topics/http/sessions/) に依存します。そのため `SessionMiddleware` を有効にして、 [`MIDDLEWARE`](/ja/6.1/ref/settings/#std-setting-MIDDLEWARE) 内で `MessageMiddleware` より前に記述する必要があります。 - [`TEMPLATES`](/ja/6.1/ref/settings/#std-setting-TEMPLATES) 設定で定義した `DjangoTemplates` バックエンドの `'context_processors'` オプションは、`'django.contrib.messages.context_processors.messages'` を含みます。 メッセージを使いたくない場合は、[`INSTALLED_APPS`](/ja/6.1/ref/settings/#std-setting-INSTALLED_APPS) から `'django.contrib.messages'` を、[`MIDDLEWARE`](/ja/6.1/ref/settings/#std-setting-MIDDLEWARE) から `MessageMiddleware` 行を、そして [`TEMPLATES`](/ja/6.1/ref/settings/#std-setting-TEMPLATES) から `messages` コンテキストプロセッサーを削除できます。 ## メッセージエンジンを設定する ### ストレージバックエンド メッセージフレームワークは、一時的なメッセージを保管するために、異なるバックエンドを使うことができます。 Django は、[`django.contrib.messages`](#module-django.contrib.messages) の中で、以下の3つのビルトインのストレージクラスを提供しています: #### `class storage.session.SessionStorage` このクラスは、すべてのメッセージをリクエストのセッション内部に保管します。ゆえに、Django の `contrib.sessions` アプリケーションが必要となります。 #### `class storage.cookie.CookieStorage` このクラスは、複数のリクエストにわたって通知を保持するために、Cookie (改ざんを防ぐため秘密のハッシュで署名されます) にメッセージデータを保管します。古いメッセージは Cookie データのサイズが 2048 バイトを超えると破棄されます。 #### `class storage.fallback.FallbackStorage` このクラスは、まず `CookieStorage` を使い、単一の Cookie に合わないメッセージに対して `SessionStorage` を使います。Django の `contrib.sessions` アプリケーションも必要となります。 この動作は、可能な限りセッションへの書き込みを避けます。一般的なケースでは最高のパフォーマンスを提供するはずです。 [`FallbackStorage`](#django.contrib.messages.storage.fallback.FallbackStorage) はデフォルトのストレージクラスです。もしあなたのニーズに合わないときは、[`MESSAGE_STORAGE`](/ja/6.1/ref/settings/#std-setting-MESSAGE_STORAGE) を完全な import パスに設定することで他のストレージクラスを選べます。次に例を示します。 ``` MESSAGE_STORAGE = "django.contrib.messages.storage.cookie.CookieStorage" ``` #### `class storage.base.BaseStorage` 独自のストレージクラスに書き込むためには、 `django.contrib.messages.storage.base` 内の `BaseStorage` クラスをサブクラス化して、 `_get` と `_store` メソッドを実装してください。 ### メッセージレベル メッセージフレームワークは、Python ロギングモジュールに似た、設定可能なレベルアーキテクチャに基づきます。メッセージレベルは、タイプによるグループメッセージを可能にします。これにより、ビューやテンプレートの中で異なるフィルタおよび表示ができるようになります。 `django.contrib.messages` から直接インポートできるビルトインのレベルは以下の通りです: | 定数 | 目的 | | --- | --- | | `DEBUG` | プロダクション環境では無視 (ないし削除) される、開発に関連したメッセージ | | `INFO` | ユーザーに何か情報を伝えるメッセージ | | `SUCCESS` | あるアクションが成功した、例えば "あなたのプロフィールは無事に更新されました" | | `WARNING` | 問題は起きなかったが、問題になり得る | | `ERROR` | あるアクションが成功 **しなかった** か、他の問題が発生した | [`MESSAGE_LEVEL`](/ja/6.1/ref/settings/#std-setting-MESSAGE_LEVEL) 設定は、最小限の記録されたレベルを変更するため (もしくは [リクエストごとに変更](#changing-the-minimum-recorded-level-per-request) するため)に使うことができます。これ以下のレベルのメッセージを追加しようとしても無視されます。 ### メッセージタグ メッセージタグは、メッセージレベルの表現文字列に加えて、ビューの中で直接付与される追加のタグです (詳しくは、以下の [追加のメッセージタグを付与する](#adding-extra-message-tags) を参照してください )。タグは文字列で保管され、スペースによって区切られます。典型的には、メッセージタグは、メッセージタイプに基いてメッセージのスタイルをカスタマイズするために、CSS のクラスとして利用されます。デフォルトでは、それぞれのレベルは、レベル定数を小文字にした、単一のタグを持っています。 | レベル定数 | タグ | | --- | --- | | `DEBUG` | `debug` | | `INFO` | `info` | | `SUCCESS` | `success` | | `WARNING` | `warning` | | `ERROR` | `error` | メッセージレベル (ビルトインないしカスタムのいずれか) のデフォルトのタグを変更するためには、 [`MESSAGE_TAGS`](/ja/6.1/ref/settings/#std-setting-MESSAGE_TAGS) 設定を、あなたが変更したいと思うレベルを含むディクショナリにセットしてください。これでデフォルトのタグを拡張するので、あなたがすべきことはオーバーライドしようとするレベルに対してタグを提供することだけです: ``` from django.contrib.messages import constants as messages MESSAGE_TAGS = { messages.INFO: "", 50: "critical", } ``` ## ビューとテンプレートでメッセージを使う #### `add_message(request, level, message, extra_tags='', fail_silently=False)` ### メッセージを付与する メッセージを付与するには、以下を呼び出してください: ``` from django.contrib import messages messages.add_message(request, messages.INFO, "Hello world.") ``` いくつかのショートカットメソッドは、一般的に使われるタグ (通常、メッセージのHTMLクラスとして表されます) とともにメッセージを付与する標準的な方法を提供します: ``` messages.debug(request, "%s SQL statements were executed." % count) messages.info(request, "Three credits remain in your account.") messages.success(request, "Profile details updated.") messages.warning(request, "Your account expires in three days.") messages.error(request, "Document deleted.") ``` ### メッセージを表示する #### `get_messages(request)` **テンプレート** では、次のようなものを使ってください: ```html+django {% if messages %} {% endif %} ``` コンテキストプロセッサーを使っている場合、テンプレートは `RequestContext` でレンダリングされる必要があります。もしくは、 `messages` をテンプレートコンテキストに対して有効にしてください。 メッセージが一つしかないとわかっている場合でも、 `messages` 配列をイテレートする必要があります。そうしないとメッセージストレージは次のリクエストのためにクリアされないからです。 コンテキストプロセッサーは、メッセージレベルの名前と数値を対応付ける `DEFAULT_MESSAGE_LEVELS` 変数も提供します: ```html+django {% if messages %} {% endif %} ``` **テンプレート以外では**、 [`get_messages()`](#django.contrib.messages.get_messages) を使うことができます: ``` from django.contrib.messages import get_messages storage = get_messages(request) for message in storage: do_something_with_the_message(message) ``` たとえば、すべてのメッセージを取得して、[`TemplateResponseMixin`](/ja/6.1/ref/class-based-views/mixins-simple/#django.views.generic.base.TemplateResponseMixin) の代わりに [JSONResponseMixin](/ja/6.1/topics/class-based-views/mixins/#jsonresponsemixin-example) で返すことができます。 [`get_messages()`](#django.contrib.messages.get_messages) は設定されたストレージバックエンドのインスタンスを返します。 ### `Message` クラス #### `class Message` テンプレート内のメッセージのリストをループさせると、 `Message` クラスのインスタンスが得られます。これらのインスタンスにはいくつかの属性しかありません: - `message`: メッセージの実際のテキストです。 - `level`: メッセージのタイプを説明する数値です (詳細は上述の [message levels](#message-levels) セクション)。 - `tags`: スペースによって区切られた、全てのメッセージのタグを結合する文字列 (`extra_tags` と `level_tag`) です。 - `extra_tags`: スペースによって区切られた、メッセージのカスタムタグを含む文字列です。空がデフォルトです。 - `level_tag`: レベルを表す文字列です。デフォルトでは定数名の小文字バージョンですが、[`MESSAGE_TAGS`](/ja/6.1/ref/settings/#std-setting-MESSAGE_TAGS) 設定によって変更できます。 ### 独自のメッセージレベルを作成する メッセージレベルは実際には単なる整数なので、独自のレベル定数を定義して、よりカスタマイズされたユーザーフィードバックを作成できます。次に例を示します。 ``` CRITICAL = 50 def my_view(request): messages.add_message(request, CRITICAL, "A serious error occurred.") ``` 独自のメッセージレベルを作成するときには、既存のレベルを上書きしないように気をつけてください。ビルトインのレベルで使われている値は以下の通りです: | レベル定数 | 値 | | --- | --- | | `DEBUG` | 10 | | `INFO` | 20 | | `SUCCESS` | 25 | | `WARNING` | 30 | | `ERROR` | 40 | HTML や CSS の中で独自のレベルを指定する必要がある場合は、[`MESSAGE_TAGS`](/ja/6.1/ref/settings/#std-setting-MESSAGE_TAGS) 設定を通してマップを提供する必要があります。 > **Note** > > 再利用可能なアプリケーションを作成している場合には、ビルトインの [message levels](#message-levels) だけを使い、独自のレベルに依存しないことが推奨されます。 ### リクエストごとの最小記録レベルを変更する 最小記録レベルは、`set_level` メソッドを使用してリクエストごとに設定できます。 ``` from django.contrib import messages # Change the messages level to ensure the debug message is added. messages.set_level(request, messages.DEBUG) messages.debug(request, "Test message...") # In another request, record only messages with a level of WARNING and higher messages.set_level(request, messages.WARNING) messages.success(request, "Your profile was updated.") # ignored messages.warning(request, "Your account is about to expire.") # recorded # Set the messages level back to default. messages.set_level(request, None) ``` 同様に、現在の有効レベルは `get_level` を使って取得できます。 ``` from django.contrib import messages current_level = messages.get_level(request) ``` 最小記録レベルが機能する仕組みについての詳細は、上記の [Message levels](#message-levels) を参照してください。 ### 追加のメッセージタグを追加する メッセージタグをより直接的に制御したい場合は、追加メソッドのいずれかに、追加のタグを含む文字列を任意で指定できます: ``` messages.add_message(request, messages.INFO, "Over 9000!", extra_tags="dragonball") messages.error(request, "Email box full", extra_tags="email") ``` 追加タグは、そのレベルのデフォルトタグの前に追加され、スペースで区切られます。 ### メッセージフレームワークが無効になっているときのエラーを隠す 再利用可能なアプリ (または他のコード) を書いており、メッセージング機能を含めたいが、利用者に無理に有効化させたくない場合は、任意の `add_message` ファミリーのメソッドに `fail_silently=True` という追加のキーワード引数を渡すことができます。たとえば: ``` messages.add_message( request, messages.SUCCESS, "Profile details updated.", fail_silently=True, ) messages.info(request, "Hello world.", fail_silently=True) ``` > **Note** > > `fail_silently=True` を設定すると、メッセージフレームワークが無効になっており、`add_message` メソッドのいずれかを使用しようとした際に発生するはずの `MessageFailure` を隠します。それ以外の理由で発生する失敗は隠されません。 ### クラスベースのビューにメッセージを追加する #### `class views.SuccessMessageMixin` [`FormView`](/ja/6.1/ref/class-based-views/generic-editing/#django.views.generic.edit.FormView) をベースにしたクラスに、成功メッセージ属性を追加します。 #### `get_success_message(cleaned_data)` `cleaned_data` はフォームからのクリーンなデータであり、文字列フォーマットに使用されます。 **Example views.py**: ``` from django.contrib.messages.views import SuccessMessageMixin from django.views.generic.edit import CreateView from myapp.models import Author class AuthorCreateView(SuccessMessageMixin, CreateView): model = Author success_url = "/success/" success_message = "%(name)s was created successfully" ``` `form` からのクリーン済みデータは、 `%(field_name)s` 構文を使用して文字列補完に利用できます。ModelForms の場合、保存された `object` からフィールドにアクセスが必要な場合は、 [`get_success_message()`](#django.contrib.messages.views.SuccessMessageMixin.get_success_message) メソッドをオーバーライドしてください。 **ModelForms 用の views.py の例**: ``` from django.contrib.messages.views import SuccessMessageMixin from django.views.generic.edit import CreateView from myapp.models import ComplicatedModel class ComplicatedCreateView(SuccessMessageMixin, CreateView): model = ComplicatedModel success_url = "/success/" success_message = "%(calculated_field)s was created successfully" def get_success_message(self, cleaned_data): return self.success_message % dict( cleaned_data, calculated_field=self.object.calculated_field, ) ``` ## メッセージの有効期限 メッセージは、ストレージインスタンスがイテレートされる際にクリアされるようにマークされています (そして、応答が処理される際にもクリアされます)。 メッセージがクリアされるのを避けるために、イテレートの後にメッセージストレージを `False` に設定できます: ``` storage = messages.get_messages(request) for message in storage: do_something_with(message) storage.used = False ``` ## 並列リクエストの動作 クッキー (そしてセッション) の仕組みから、同じクライアントが複数の要求を並行して行い、メッセージを設定または取得する場合、クッキーやセッションを使用するバックエンドの動作は定義されていません。たとえば、クライアントが1つのウィンドウ (またはタブ) でメッセージを作成する要求を開始し、別のウィンドウで未読メッセージを取得する要求を開始するとき、最初のウィンドウがリダイレクトされる前に、そのメッセージが最初ではなく、代わりに2番目のウィンドウに表示されることがあります。 要するに、同じクライアントからの複数の同時リクエストが関わると、メッセージがそれらを作成した同じウィンドウに必ず届くわけではなく、場合によっては全く届かないことがあります。ほとんどのアプリケーションでは通常問題とならず、HTML5では各ウィンドウ/タブが独自の閲覧コンテキストを持つため、これは問題にならなくなります。 ## 設定 いくつかの [設定](/ja/6.1/ref/settings/#settings-messages) を使用して、メッセージの動作を制御できます。 - [`MESSAGE_LEVEL`](/ja/6.1/ref/settings/#std-setting-MESSAGE_LEVEL) - [`MESSAGE_STORAGE`](/ja/6.1/ref/settings/#std-setting-MESSAGE_STORAGE) - [`MESSAGE_TAGS`](/ja/6.1/ref/settings/#std-setting-MESSAGE_TAGS) Cookiesを使用するバックエンドでは、Cookieの設定はセッションCookieの設定から取得されます。 - [`SESSION_COOKIE_DOMAIN`](/ja/6.1/ref/settings/#std-setting-SESSION_COOKIE_DOMAIN) - [`SESSION_COOKIE_SECURE`](/ja/6.1/ref/settings/#std-setting-SESSION_COOKIE_SECURE) - [`SESSION_COOKIE_HTTPONLY`](/ja/6.1/ref/settings/#std-setting-SESSION_COOKIE_HTTPONLY) ## テスト このモジュールは、[`HttpResponse`](/ja/6.1/ref/request-response/#django.http.HttpResponse) に添付されたメッセージをテストするためのカスタマイズされたテストアサーションメソッドを提供しています。 このアサーションを利用するには、クラス階層に `MessagesTestMixin` を追加してください。 ``` from django.contrib.messages.test import MessagesTestMixin from django.test import TestCase class MsgTestCase(MessagesTestMixin, TestCase): pass ``` 次に、テストで `MsgTestCase` を継承してください。 #### `MessagesTestMixin.assertMessages(response, expected_messages, ordered=True)` [`response`](/ja/6.1/ref/request-response/#django.http.HttpResponse) に追加された [`messages`](#module-django.contrib.messages) が `expected_messages` と一致することをアサートします。 `expected_messages` は [`Message`](#django.contrib.messages.Message) オブジェクトのリストです。 デフォルトでは、比較は順序に依存します。これを無効にするには、 `ordered` 引数を `False` に設定します。