页面内容

Flash

class Cake\Controller\Component\FlashComponent(ComponentCollection $collection, array $config = [])

FlashComponent 提供了一种设置一次性通知消息的方式，这些消息将在处理表单或确认数据后显示。CakePHP 将这些消息称为“闪存消息”。FlashComponent 将闪存消息写入 $_SESSION，以便使用 FlashHelper 在视图中渲染。

设置闪存消息

FlashComponent 提供了两种设置闪存消息的方法：其 __call() 魔术方法及其 set() 方法。为了使您的应用程序更具表达力，FlashComponent 的 __call() 魔术方法允许您使用一个方法名称，该名称映射到位于 templates/element/flash 目录下的元素。按照惯例，驼峰式方法将映射到小写和下划线的元素名称。

// Uses templates/element/flash/success.php
$this->Flash->success('This was successful');

// Uses templates/element/flash/great_success.php
$this->Flash->greatSuccess('This was greatly successful');

或者，为了设置一个纯文本消息而无需渲染元素，您可以使用 set() 方法。

$this->Flash->set('This is a message');

闪存消息在内部追加到一个数组中。对同一个键的 set() 或 __call() 的后续调用将在 $_SESSION 中追加消息。如果您想在设置闪存消息时覆盖现有消息，请在配置组件时将 clear 选项设置为 true。

FlashComponent 的 __call() 和 set() 方法可选地接受第二个参数，一个选项数组。

  • key 默认值为 ‘flash’。会话中 Flash 键下的数组键。

  • element 默认值为 null，但在使用 __call() 魔术方法时会自动设置。要使用的渲染元素名称。

  • params 一个可选的键/值数组，作为变量在元素中可用。

  • clear 期望一个 bool，允许您删除当前堆栈中的所有消息并开始一个新的堆栈。

使用这些选项的示例

// In your Controller
$this->Flash->success('The user has been saved', [
    'key' => 'positive',
    'clear' => true,
    'params' => [
        'name' => $user->name,
        'email' => $user->email,
    ],
]);

// In your View
<?= $this->Flash->render('positive') ?>

<!-- In templates/element/flash/success.php -->
<div id="flash-<?= h($key) ?>" class="message-info success">
    <?= h($message) ?>: <?= h($params['name']) ?>, <?= h($params['email']) ?>.
</div>

请注意，在使用 __call() 时，参数 element 将始终被覆盖。为了从插件中检索特定元素，您应该设置 plugin 参数。例如

// In your Controller
$this->Flash->warning('My message', ['plugin' => 'PluginName']);

上面的代码将使用 plugins/PluginName/templates/element/flash 下的 warning.php 元素来渲染闪存消息。

注意

默认情况下，CakePHP 会转义闪存消息中的内容以防止跨站点脚本。闪存消息中的用户数据将进行 HTML 编码，并且可以安全地打印。如果您想在闪存消息中包含 HTML，您需要传递 escape 选项，并调整您的闪存消息模板以允许在传递 escape 选项时禁用转义。

闪存消息中的 HTML

可以使用 'escape' 选项键在闪存消息中输出 HTML。

$this->Flash->info(sprintf('<b>%s</b> %s', h($highlight), h($message)), ['escape' => false]);

确保您手动转义输入。在上面的示例中，$highlight 和 $message 是非 HTML 输入，因此被转义。

有关渲染闪存消息的更多信息，请参阅 FlashHelper 部分。