HtmlHelper 类
用于轻松使用 HTML 小部件的 Html Helper 类。
HtmlHelper 包含所有在处理 HTML 页面时所需的方法。
属性概览
-
$Url public @property
Cake\View\Helper\UrlHelper
-
$_View protected
Cake\View\View
此助手附加到的 View 实例
-
$_config protected
array<string, mixed>
运行时配置
-
$_configInitialized protected
bool
配置属性是否已使用默认值配置
-
$_defaultConfig protected
array<string, mixed>
此类的默认配置
-
$_includedAssets protected
array<string, array>
已包含一次的脚本 & css 文件名称
-
$_scriptBlockOptions protected
array<string, mixed>
如果存在,则为当前打开的脚本块缓冲区的选项。
-
$_templater protected
Cake\View\StringTemplate|null
StringTemplate 实例。
-
$helperInstances protected
array<string,Cake\View\Helper>
加载的助手实例。
-
$helpers protected
array
此助手使用的助手列表
方法概览
-
__construct() public
默认构造函数
-
__debugInfo() public
返回一个数组,可用于描述此对象的内部状态。
-
__get() public
延迟加载助手。
-
_configDelete() protected
删除单个配置键。
-
_configRead() protected
读取配置键。
-
_configWrite() protected
写入配置键。
-
_confirm() protected
返回一个字符串,用作确认对话框的 onclick 处理程序。
-
_nestedListItem() protected
内部函数,用于从关联数组中构建嵌套列表 (UL/OL)。
-
_renderCells() protected
渲染表格行单元格。
-
addClass() public
将给定的类添加到元素选项中
-
charset() public
返回一个字符集 META 标签。
-
configShallow() public
将提供的配置与现有配置合并。与
config()
对嵌套键执行递归合并不同,此方法执行简单合并。 -
css() public
为 CSS 样式表创建链接元素。
-
div() public
为 HTML 表单返回格式化的 DIV 标签。
-
formatTemplate() public
使用 $data 格式化模板字符串
-
getConfig() public
返回配置。
-
getConfigOrFail() public
返回此特定键的配置。
-
getTemplates() public
获取要使用的模板或特定模板。
-
getView() public
获取此助手绑定的 View 实例。
-
image() public
创建格式化的 IMG 元素。
-
implementedEvents() public
事件监听器。
-
initialize() public
构造函数钩子方法。
-
link() public
创建 HTML 链接。
-
linkFromPath() public
从路由路径字符串创建 HTML 链接。
-
media() public
返回音频/视频元素
-
meta() public
创建指向外部资源的链接并处理基本元标签
-
nestedList() public
从关联数组中构建嵌套列表 (UL/OL)。
-
para() public
返回格式化的 P 标签。
-
script() public
根据给定脚本的数量返回一个或多个
<script>
标签。 -
scriptBlock() public
将 $script 包裹在脚本标签中。
-
scriptEnd() public
结束 JavaScript 捕获的缓冲部分。根据启动 scriptBlock 时使用的设置,生成内联脚本标签或追加到指定视图块
-
scriptStart() public
开始一个脚本块,该块捕获输出,直到调用 HtmlHelper::scriptEnd()。此捕获块将捕获方法之间的所有输出,并从中创建一个脚本块。
-
setConfig() public
设置配置。
-
setTemplates() public
设置要使用的模板。
-
style() public
从 CSS 属性数组构建 CSS 样式数据
-
tableCell() public
渲染单个表格单元格(带属性的 TD)。
-
tableCells() public
返回表格行(带 TD 的 TR)的格式化字符串。
-
tableHeaders() public
返回一行格式化和命名的 TABLE 标题。
-
tableRow() public
渲染单个表格行(带属性的 TR)。
-
tag() public
返回格式化的块标签,即 DIV、SPAN、P。
-
templater() public
返回模板程序实例。
方法详情
__construct() ¶ public
__construct(Cake\View\View $view, array<string, mixed> $config = [])
默认构造函数
参数
-
Cake\View\View
$view 此助手附加到的 View。
-
array<string, mixed>
$config optional 助手的配置设置。
__debugInfo() ¶ public
__debugInfo(): array<string, mixed>
返回一个数组,可用于描述此对象的内部状态。
返回
array<string, mixed>
__get() ¶ public
__get(string $name): Cake\View\Helper|null
延迟加载助手。
参数
-
string
$name 正在访问的属性的名称。
返回
Cake\View\Helper|null
_configDelete() ¶ protected
_configDelete(string $key): void
删除单个配置键。
参数
-
string
$key 要删除的键。
返回
void
抛出
Cake\Core\Exception\CakeException
如果尝试覆盖现有配置
_configRead() ¶ protected
_configRead(string|null $key): mixed
读取配置键。
参数
-
string|null
$key 要读取的键。
返回
mixed
_configWrite() ¶ protected
_configWrite(array<string, mixed>|string $key, mixed $value, string|bool $merge = false): void
写入配置键。
参数
-
array<string, mixed>|string
$key 要写入的键。
-
mixed
$value 要写入的值。
-
string|bool
$merge optional True 表示递归合并,'shallow' 表示简单合并,false 表示覆盖,默认值为 false。
返回
void
抛出
Cake\Core\Exception\CakeException
如果尝试覆盖现有配置
_confirm() ¶ protected
_confirm(string $okCode, string $cancelCode): string
返回一个字符串,用作确认对话框的 onclick 处理程序。
参数
-
string
$okCode 用户选择“确定”后要执行的代码
-
string
$cancelCode 用户选择“取消”后要执行的代码
返回
string
_nestedListItem() ¶ protected
_nestedListItem(array $items, array<string, mixed> $options, array<string, mixed> $itemOptions): string
内部函数,用于从关联数组中构建嵌套列表 (UL/OL)。
参数
-
array
$items 要列出的元素集。
-
array<string, mixed>
$options 列表 (ol/ul) 标签的其他 HTML 属性。
-
array<string, mixed>
$itemOptions 列表项 (LI) 标签的选项和其他 HTML 属性。
返回
string
另请参见
_renderCells() ¶ protected
_renderCells(array $line, bool $useCount = false): list<string>
渲染表格行单元格。
这是 tableCells() 的辅助方法。根据需要重载此方法以更改单元格渲染的行为。
参数
-
array
$line 要渲染的行数据。
-
bool
$useCount optional 将计数渲染到行中。默认值为 false。
返回
list<string>
addClass() ¶ public
addClass(array<string, mixed> $options, string $class, string $key = 'class'): array<string, mixed>
将给定的类添加到元素选项中
参数
-
array<string, mixed>
$options 要添加类的数组选项/属性
-
string
$class 要添加的类名。
-
string
$key optional 要用于类的键。默认值为
'class'
。
返回
array<string, mixed>
charset() ¶ public
charset(string|null $charset = null): string
返回一个字符集 META 标签。
参数
-
string|null
$charset optional 要在 meta 标签中使用的字符集。如果为空,将使用 App.encoding 值。例如:“utf-8”。
返回
string
链接
configShallow() ¶ public
configShallow(array<string, mixed>|string $key, mixed|null $value = null): $this
将提供的配置与现有配置合并。与 config()
对嵌套键执行递归合并不同,此方法执行简单合并。
设置特定值
$this->configShallow('key', $value);
设置嵌套值
$this->configShallow('some.nested.key', $value);
同时更新多个配置设置
$this->configShallow(['one' => 'value', 'another' => 'value']);
参数
-
array<string, mixed>|string
$key 要设置的键,或完整的配置数组。
-
mixed|null
$value optional 要设置的值。
返回
$this
css() ¶ public
css(list<string>|string $path, array<string, mixed> $options = []): string|null
为 CSS 样式表创建链接元素。
用法
包含一个 CSS 文件
echo $this->Html->css('styles.css');
包含多个 CSS 文件
echo $this->Html->css(['one.css', 'two.css']);
将样式表添加到视图块“css”
$this->Html->css('styles.css', ['block' => true]);
将样式表添加到自定义块
$this->Html->css('styles.css', ['block' => 'layoutCss']);
选项
block
设置为 true 以将输出追加到视图块“css”或提供自定义块名称。once
是否应检查 css 文件是否唯一。如果为 true,css 文件将只包含一次,使用 false 允许在每个请求中多次包含相同的 css。plugin
False 值将阻止将路径解析为插件rel
默认值为 'stylesheet'。如果等于 'import',则样式表将被导入。fullBase
如果为 true,则 URL 将获得 css 文件的完整地址。
所有其他选项将被视为 HTML 属性。如果请求包含 cspStyleNonce
属性,则该值将被应用为生成的 HTML 上的 nonce
属性。
参数
-
list<string>|string
$path CSS 样式表名称或包含 CSS 样式表名称的数组。如果
$path
以 '/' 开头,则路径将相对于应用程序的 webroot。否则,路径将相对于 CSS 路径,通常为 webroot/css。-
array<string, mixed>
$options optional 选项和 HTML 参数数组。
返回
string|null
链接
div() ¶ public
div(string|null $class = null, string|null $text = null, array<string, mixed> $options = []): string
为 HTML 表单返回格式化的 DIV 标签。
选项
escape
内容是否应进行 html_entity 转义。
参数
-
string|null
$class optional div 元素的 CSS 类名。
-
string|null
$text optional 将出现在 div 元素内部的字符串内容。如果为 null,则只打印开始标签
-
array<string, mixed>
$options optional DIV 标签的其他 HTML 属性
返回
string
formatTemplate() ¶ public
formatTemplate(string $name, array<string, mixed> $data): string
使用 $data 格式化模板字符串
参数
-
string
$name 模板名称。
-
array<string, mixed>
$data 要插入的数据。
返回
string
getConfig() ¶ public
getConfig(string|null $key = null, mixed $default = null): mixed
返回配置。
用法
读取整个配置
$this->getConfig();
读取特定值
$this->getConfig('key');
读取嵌套值
$this->getConfig('some.nested.key');
使用默认值读取
$this->getConfig('some-key', 'default-value');
参数
-
string|null
$key optional 要获取的键或整个配置的 null。
-
mixed
$default optional 键不存在时的返回值。
返回
mixed
getConfigOrFail() ¶ public
getConfigOrFail(string $key): mixed
返回此特定键的配置。
此键的配置值必须存在,不能为 null。
参数
-
string
$key 要获取的键。
返回
mixed
抛出
InvalidArgumentException
getTemplates() ¶ public
getTemplates(string|null $template = null): array|string
获取要使用的模板或特定模板。
参数
-
string|null
$template optional 用于读取特定模板的字符串,所有模板的 null。
返回
array|string
image() ¶ public
image(array|string $path, array<string, mixed> $options = []): string
创建格式化的 IMG 元素。
如果未提供 alt 属性,此方法将设置一个空 alt 属性。
用法
创建常规图像
echo $this->Html->image('cake_icon.png', ['alt' => 'CakePHP']);
创建图像链接
echo $this->Html->image('cake_icon.png', ['alt' => 'CakePHP', 'url' => 'https://cakephp.com.cn']);
选项
url
如果提供,将生成图像链接,并且链接将指向$options['url']
。fullBase
如果为 true,则 src 属性将获得图像文件的完整地址。plugin
False 值将阻止将路径解析为插件
参数
-
array|string
$path 图像文件的路径,相对于 webroot/img/ 目录。
-
array<string, mixed>
$options optional HTML 属性数组。有关特殊选项,请参见上文。
返回
string
链接
implementedEvents() ¶ public
implementedEvents(): array<string, mixed>
事件监听器。
通过定义回调方法之一,助手将被假定为对相关事件感兴趣。
如果您需要添加非传统事件监听器,或者您希望助手监听非标准事件,请重写此方法。
返回
array<string, mixed>
initialize() ¶ public
initialize(array<string, mixed> $config): void
构造函数钩子方法。
实现此方法以避免覆盖构造函数并调用父级。
参数
-
array<string, mixed>
$config 提供给此助手的配置设置。
返回
void
link() ¶ public
link(array|string $title, array|string|null $url = null, array<string, mixed> $options = []): string
创建 HTML 链接。
如果 $url 以 "http://" 开头,则将其视为外部链接。否则,将其视为控制器/操作的路径,并使用 UrlHelper::build() 方法解析。
如果 $url 为空,则使用 $title 代替。
选项
escape
设置为 false 以禁用标题和属性的转义。escapeTitle
设置为 false 以禁用标题的转义。优先于escape
的值。confirm
JavaScript 确认消息。
参数
-
array|string
$title 要由
<a>
标签包装的内容。如果 $url 为 null,则可以为数组。如果 $url 为 null,则 $title 将用作 URL 和标题。-
array|string|null
$url optional Cake 相对 URL 或 URL 参数数组,或外部链接(以 http:// 开头)
-
array<string, mixed>
$options optional 选项和 HTML 属性数组。
返回
string
链接
linkFromPath() ¶ public
linkFromPath(string $title, string $path, array $params = [], array<string, mixed> $options = []): string
从路由路径字符串创建 HTML 链接。
选项
escape
设置为 false 以禁用标题和属性的转义。escapeTitle
设置为 false 以禁用标题的转义。优先于escape
的值。confirm
JavaScript 确认消息。
参数
-
string
$title 要由
<a>
标签包装的内容。-
string
$path Cake 相对路由路径。
-
array
$params optional 指定任何其他参数的数组。也可以是
Router::url()
支持的任何特殊参数。-
array<string, mixed>
$options optional 选项和 HTML 属性数组。
返回
string
另请参见
链接
media() ¶ public
media(array|string|null $path, array<string, mixed> $options = []): string
返回音频/视频元素
用法
使用音频文件
echo $this->Html->media('audio.mp3', ['fullBase' => true]);
输出
<video src="http://www.somehost.com/files/audio.mp3">Fallback text</video>
使用视频文件
echo $this->Html->media('video.mp4', ['text' => 'Fallback text']);
输出
<video src="/files/video.mp4">Fallback text</video>
使用多个视频文件
echo $this->Html->media(
['video.mp4', ['src' => 'video.ogv', 'type' => "video/ogg; codecs='theora, vorbis'"]],
['tag' => 'video', 'autoplay']
);
输出
<video autoplay="autoplay">
<source src="/files/video.mp4" type="video/mp4">
<source src="/files/video.ogv" type="video/ogv; codecs='theora, vorbis'">
</video>
选项
tag
要生成的媒体元素类型,可以是“audio”或“video”。 如果未提供 tag,则根据文件的 MIME 类型猜测。text
要包含在音频/视频标签内的文本pathPrefix
用于相对 URL 的路径前缀,默认为“files/”fullBase
如果提供,src 属性将获得包含域名在内的完整地址
参数
-
array|string|null
$path 视频文件的路径,相对于 webroot/{$options['pathPrefix']} 目录。 或一个数组,其中每个项目本身可以是一个路径字符串,或一个包含键
src
和type
的关联数组-
array<string, mixed>
$options optional HTML 属性数组和上面的特殊选项。
返回
string
meta() ¶ public
meta(array<string, mixed>|string $type, array|string|null $content = null, array<string, mixed> $options = []): string|null
创建指向外部资源的链接并处理基本元标签
创建一个内联输出的元标签
$this->Html->meta('icon', 'favicon.ico');
将元标签追加到自定义视图块“meta”
$this->Html->meta('description', 'A great page', ['block' => true]);
将元标签追加到自定义视图块
$this->Html->meta('description', 'A great page', ['block' => 'metaTags']);
创建一个自定义元标签
$this->Html->meta(['property' => 'og:site_name', 'content' => 'CakePHP']);
选项
block
- 设置为 true 以将输出追加到视图块“meta”或提供自定义块名称。
参数
-
array<string, mixed>|string
$type 外部资源的标题,或自定义元标签的属性数组。
-
array|string|null
$content 可选 外部资源的地址或内容属性的字符串
-
array<string, mixed>
$options optional 生成的标签的其他属性。 如果 type 属性是 html、rss、atom 或 icon,则返回 MIME 类型。
返回
string|null
链接
nestedList() ¶ public
nestedList(array $list, array<string, mixed> $options = [], array<string, mixed> $itemOptions = []): string
从关联数组中构建嵌套列表 (UL/OL)。
$options
的选项
tag
- 要使用的列表标签类型(ol/ul)
$itemOptions
的选项
even
- 用于偶数行的类。odd
- 用于奇数行的类。
参数
-
array
$list 要列出的元素集
-
array<string, mixed>
$options optional 列表(ol/ul)标签的选项和附加 HTML 属性。
-
array<string, mixed>
$itemOptions 可选 列表项 (LI) 标签的选项和其他 HTML 属性。
返回
string
链接
para() ¶ public
para(string|null $class, string|null $text, array<string, mixed> $options = []): string
返回格式化的 P 标签。
选项
escape
内容是否应进行 html_entity 转义。
参数
-
string|null
$class p 元素的 CSS 类名。
-
string|null
$text 将出现在 p 元素内的字符串内容。
-
array<string, mixed>
$options optional P 标签的附加 HTML 属性
返回
string
script() ¶ public
script(list<string>|string $url, array<string, mixed> $options = []): string|null
根据给定脚本的数量返回一个或多个 <script>
标签。
如果文件名以“/”开头,则路径将相对于应用程序的基路径。 否则,路径将相对于 JavaScript 路径,通常是 webroot/js。
用法
包含一个脚本文件
echo $this->Html->script('styles.js');
包含多个脚本文件
echo $this->Html->script(['one.js', 'two.js']);
将脚本文件添加到自定义块
$this->Html->script('styles.js', ['block' => 'bodyScript']);
选项
block
设置为 true 以将输出追加到视图块“script”或提供自定义块名称。once
脚本是否应该检查唯一性。 如果为 true,脚本将只包含一次,使用 false 允许在每个请求中包含相同的脚本多次。plugin
False 值将阻止将路径解析为插件fullBase
如果为 true,url 将获得脚本文件的完整地址。
所有其他选项都将作为属性添加到生成的脚本标签。 如果当前请求具有 cspScriptNonce
属性,则该值将作为 nonce
属性插入脚本标签中。
参数
-
list<string>|string
$url 要包含的 JavaScript 文件的字符串或数组
-
array<string, mixed>
$options optional 选项数组和 HTML 属性,请参见上面。
返回
string|null
链接
scriptBlock() ¶ public
scriptBlock(string $script, array<string, mixed> $options = []): string|null
将 $script 包裹在脚本标签中。
选项
block
设置为 true 以将输出追加到视图块“script”或提供自定义块名称。
参数
-
string
$script 要包装的脚本
-
array<string, mixed>
$options optional 要使用的选项。 上面未列出的选项将被视为 HTML 属性。
返回
string|null
链接
scriptEnd() ¶ public
scriptEnd(): string|null
结束 JavaScript 捕获的缓冲部分。根据启动 scriptBlock 时使用的设置,生成内联脚本标签或追加到指定视图块
返回
string|null
链接
scriptStart() ¶ public
scriptStart(array<string, mixed> $options = []): void
开始一个脚本块,该块捕获输出,直到调用 HtmlHelper::scriptEnd()。此捕获块将捕获方法之间的所有输出,并从中创建一个脚本块。
选项
block
设置为 true 以将输出追加到视图块“script”或提供自定义块名称。
参数
-
array<string, mixed>
$options optional 代码块的选项。
返回
void
链接
setConfig() ¶ public
setConfig(array<string, mixed>|string $key, mixed|null $value = null, bool $merge = true): $this
设置配置。
用法
设置特定值
$this->setConfig('key', $value);
设置嵌套值
$this->setConfig('some.nested.key', $value);
同时更新多个配置设置
$this->setConfig(['one' => 'value', 'another' => 'value']);
参数
-
array<string, mixed>|string
$key 要设置的键,或完整的配置数组。
-
mixed|null
$value optional 要设置的值。
-
bool
$merge 可选 是否递归合并或覆盖现有配置,默认为 true。
返回
$this
抛出
Cake\Core\Exception\CakeException
尝试设置无效键时。
setTemplates() ¶ public
setTemplates(array<string, string> $templates): $this
设置要使用的模板。
参数
-
array<string, string>
$templates 要添加的模板。
返回
$this
style() ¶ public
style(array<string, string> $data, bool $oneLine = true): string
从 CSS 属性数组构建 CSS 样式数据
用法
echo $this->Html->style(['margin' => '10px', 'padding' => '10px'], true);
// creates
'margin:10px;padding:10px;'
参数
-
array<string, string>
$data 样式数据数组,键将用作属性名称,值将用作属性值。
-
bool
$oneLine 可选 样式块是否应该显示在一行上。
返回
string
链接
tableCell() ¶ public
tableCell(string $content, array<string, mixed> $options = []): string
渲染单个表格单元格(带属性的 TD)。
参数
-
string
$content 单元格的内容。
-
array<string, mixed>
$options optional HTML 属性。
返回
string
tableCells() ¶ public
tableCells(array|string $data, array<string, mixed>|bool|null $oddTrOptions = null, array<string, mixed>|bool|null $evenTrOptions = null, bool $useCount = false, bool $continueOddEven = true): string
返回表格行(带 TD 的 TR)的格式化字符串。
参数
-
array|string
$data 表格数据的数组
-
array<string, mixed>|bool|null
$oddTrOptions 可选 如果使用 true useCount,则奇数 TR 元素的 HTML 选项
-
array<string, mixed>|bool|null
$evenTrOptions 可选 偶数 TR 元素的 HTML 选项
-
bool
$useCount optional 添加类“column-$i”
-
bool
$continueOddEven 可选 如果为 false,将使用非静态的 $count 变量,以便奇偶计数仅针对该调用重置为零。
返回
string
链接
tableHeaders() ¶ public
tableHeaders(array $names, array<string, mixed>|null $trOptions = null, array<string, mixed>|null $thOptions = null): string
返回一行格式化和命名的 TABLE 标题。
参数
-
array
$names 表名的数组。 每个表名可以是字符串,或者是一个包含名称和一个包含其特定标签属性集的数组的数组
-
array<string, mixed>|null
$trOptions 可选 TR 元素的 HTML 选项。
-
array<string, mixed>|null
$thOptions 可选 TH 元素的 HTML 选项。
返回
string
链接
tableRow() ¶ public
tableRow(string $content, array<string, mixed> $options = []): string
渲染单个表格行(带属性的 TR)。
参数
-
string
$content 行的内容。
-
array<string, mixed>
$options optional HTML 属性。
返回
string
tag() ¶ public
tag(string $name, string|null $text = null, array<string, mixed> $options = []): string
返回格式化的块标签,即 DIV、SPAN、P。
选项
escape
内容是否应进行 html_entity 转义。
参数
-
string
$name 标签名称。
-
string|null
$text optional 将出现在 HTML 元素内的字符串内容。 如果为 null,则只打印开始标签
-
array<string, mixed>
$options optional HTML 标签的附加 HTML 属性,请参见上面。
返回
string