README

Yii 视图扩展

该包是Yii 视图渲染库的扩展。它增加了WEB特定的功能以及与PSR-7接口的兼容性。

要求

PHP 8.0或更高版本。

安装

该包可以使用Composer安装。

composer require yiisoft/yii-view

通用用法

渲染视图有两种方式

返回带有延迟渲染的Yiisoft\DataResponse\DataResponse类的实例。
立即渲染并返回渲染结果作为字符串。

将渲染结果作为PSR-7响应

Yiisoft\DataResponse\DataResponse类是Psr\Http\Message\ResponseInterface的实现。有关此类的更多信息，请参阅yiisoft/data-response包。您可以通过以下方式获取具有延迟渲染的响应实例

/**
 * @var \Yiisoft\Aliases\Aliases $aliases
 * @var \Yiisoft\DataResponse\DataResponseFactoryInterface $dataResponseFactory
 * @var \Yiisoft\View\WebView $webView
 */

$viewRenderer = new \Yiisoft\Yii\View\ViewRenderer(
    $dataResponseFactory,
    $aliases,
    $webView,
    '/path/to/views', // Full path to the directory of view templates or its alias.
    'layouts/main', // Default is null, which means not to use a layout.
);

// Rendering a view with a layout.
$response = $viewRenderer->render('site/page', [
    'parameter-name' => 'parameter-value',
]);

在调用Yiisoft\DataResponse\DataResponse的getBody()或getData()方法时，将直接执行渲染。如果设置了布局，但您需要渲染不带布局的视图，则可以使用不可变的setter withLayout()

$viewRenderer = $viewRenderer->withLayout(null);

// Rendering a view without a layout.
$response = $viewRenderer->render('site/page', [
    'parameter-name' => 'parameter-value',
]);

或者使用renderPartial()方法，该方法将调用withLayout(null)

// Rendering a view without a layout.
$response = $viewRenderer->renderPartial('site/page', [
    'parameter-name' => 'parameter-value',
]);

将渲染结果作为字符串

要立即渲染并将渲染结果作为字符串返回，请使用renderAsString()和renderPartialAsString()方法

// Rendering a view with a layout.
$result = $viewRenderer->renderAsString('site/page', [
    'parameter-name' => 'parameter-value',
]);

// Rendering a view without a layout.
$result = $viewRenderer->renderPartialAsString('site/page', [
    'parameter-name' => 'parameter-value',
]);

更改视图模板路径

您可以在运行时按以下方式更改视图模板路径

$viewRenderer = $viewRenderer->withViewPath('/new/path/to/views');

您可以指定视图目录的完整路径或其别名。有关路径别名的更多信息，请参阅yiisoft/aliases包的说明。

在控制器中使用

如果在控制器中使用视图渲染器，您可以使用withControllerName()显式指定控制器名称，或者通过将控制器实例传递给withController()来自动确定名称。在这种情况下，名称的确定方式如下

App\Controller\FooBar\BazController -> foo-bar/baz
App\Controllers\FooBar\BazController -> foo-bar/baz
Path\To\File\BlogController -> blog

使用这种方法，您不需要在每次渲染视图模板时指定目录名称

use Psr\Http\Message\ResponseInterface;
use Yiisoft\Yii\View\ViewRenderer;

class SiteController
{
    private ViewRenderer $viewRenderer;

    public function __construct(ViewRenderer $viewRenderer)
    {
        // Specify the name of the controller:
        $this->viewRenderer = $viewRenderer->withControllerName('site');
        // or specify an instance of the controller:
        //$this->viewRenderer = $viewRenderer->withController($this);
    }

    public function index(): ResponseInterface
    {
        return $this->viewRenderer->render('index');
    }
    
    public function contact(): ResponseInterface
    {
        // Some actions.
        return $this->viewRenderer->render('contact', [
            'parameter-name' => 'parameter-value',
        ]);
    }
}

如果控制器中有许多方法（操作），这非常方便。

向视图注入额外数据

除了在渲染视图模板时直接传递的参数外，您还可以设置额外的参数，这些参数将在所有视图中可用。为了执行此操作，您需要一个实现至少一个注入接口的类

use Yiisoft\Yii\View\CommonParametersInjectionInterface;
use Yiisoft\Yii\View\LayoutParametersInjectionInterface;

final class MyParametersInjection implements
    CommonParametersInjectionInterface,
    LayoutParametersInjectionInterface
{
    // Pass both to view template and to layout
    public function getCommonParameters(): array
    {
        return [
            'common-parameter-name' => 'common-parameter-value',
        ];
    }
    
    // Pass only to layout
    public function getLayoutParameters(): array
    {
        return [
            'layout-parameter-name' => 'layout-parameter-value',
        ];
    }
}

链接标签和元标签应该以相同的方式进行组织。

use Yiisoft\Html\Html;
use Yiisoft\View\WebView;
use Yiisoft\Yii\View\LinkTagsInjectionInterface;
use Yiisoft\Yii\View\MetaTagsInjectionInterface;

final class MyTagsInjection implements
    LinkTagsInjectionInterface,
    MetaTagsInjectionInterface
{
    public function getLinkTags(): array
    {
        return [
            Html::link()->toCssFile('/main.css'),
            'favicon' => Html::link('/myicon.png', [
                'rel' => 'icon',
                'type' => 'image/png',
            ]),
            'themeCss' => [
                '__position' => WebView::POSITION_END,
                Html::link()->toCssFile('/theme.css'),
            ],
            'userCss' => [
                '__position' => WebView::POSITION_BEGIN,
                'rel' => 'stylesheet',
                'href' => '/user.css',
            ],
        ];
    }
    
    public function getMetaTags(): array
    {
        return [
            Html::meta()
                ->name('http-equiv')
                ->content('public'),
            'noindex' => Html::meta()
                ->name('robots')
                ->content('noindex'),
            [
                'name' => 'description',
                'content' => 'This website is about funny raccoons.',
            ],
            'keywords' => [
                'name' => 'keywords',
                'content' => 'yii,framework',
            ],
        ];
    }
}

您可以在创建视图渲染器时将此类实例作为第六个可选参数传递给构造函数，或使用withInjections()和withAddedInjections方法。

$parameters = new MyParametersInjection();
$tags = new MyTagsInjection();

$viewRenderer = $viewRenderer->withInjections($parameters, $tags);
// Or append it:
$viewRenderer = $viewRenderer->withAddedInjections($parameters, $tags);

传递给render()方法的参数具有更高的优先级，如果它们的名称匹配，将覆盖注入的内容参数。

注入的延迟加载

您可以为注入使用延迟加载。注入将由实现Yiisoft\Yii\View\InjectionContainerInterface的容器创建。默认情况下，它可用在基于PSR-11兼容容器的InjectionContainer中。

将注入容器添加到ViewRenderer构造函数中

use Yiisoft\Yii\View\ViewRenderer;
use Yiisoft\Yii\View\InjectionContainer\InjectionContainer;

/**
 * @var Psr\Container\ContainerInterface $container
 */

$viewRenderer = new ViewRenderer(
    injectionContainer: new InjectionContainer($container)
)

请使用注入类名而不是实例。

$viewRenderer->withInjections(MyParametersInjection::class, MyTagsInjection::class);

本地化视图文件

您可以使用 withLocale() 方法设置用于本地化视图文件的具体区域设置。

$viewRenderer = $viewRenderer->withLocale('de_DE');

有关本地化的更多信息，请参阅本地化部分，该部分位于 yiisoft/view 包中。

文档

内部

如果您需要帮助或有问题，可以在 Yii 论坛上找到。您还可以查看其他 Yii 社区资源。

许可证

Yii 视图扩展是免费软件。它根据 BSD 许可证的条款发布。有关更多信息，请参阅 LICENSE。

由 Yii 软件维护。

rossaddison / yii-view

维护者

详细信息