README

此插件为Craft CMS添加了新的链接字段类型。链接字段允许内容编辑器从链接类型列表中进行选择，并为每个类型提供单独的输入字段。

要求

此插件需要Craft CMS 4.0.0或更高版本。

安装

可以通过在集成插件商店中搜索“Typed Link Field”或使用Composer来安装此插件

1. 打开您的终端并导航到您的Craft项目

   cd /path/to/project
   

2. 然后告诉Composer加载插件

   composer require sebastianlenz/linkfield
   

3. 最后，安装并启用插件

   ./craft plugin/install typedlinkfield
   ./craft plugin/enable typedlinkfield
   

用法

插件安装后，可以在控制面板中的字段设置中创建链接字段。所有字段设置都可以在字段管理器中找到。

模板化

链接字段可以直接在Twig中渲染，它们返回链接指向的URL，如果没有设置则为空字符串

<a href="{{ entry.myLinkField }}">Link</a>

字段值实际上是 lenz\linkfield\models\Link 的一个实例，它公开了可以在模板中使用的附加属性和方法。根据链接类型，将返回更具体的子类。

渲染方法

getLink($attributesOrText = null)

使用字段的属性和内容数据渲染完整的HTML链接。

{{ entry.myLinkField.getLink() }}

要修改链接标签的内文本，可以传递所需的内容

{{ entry.myLinkField.getLink('Imprint') }}

要修改链接的属性，可以传递一个对象。特殊属性 text 将用作内文本。

{{ entry.myLinkField.getLink({
  class: 'my-link-class',
  target: '_blank',
  text: 'Imprint',
}) }}

getLinkAttributes($extraAttributes = null)

仅渲染链接属性。可以通过传递一个对象到第一个参数来修改或附加属性。

<a{{ entry.myLinkField.getLinkAttributes() }}>
  <span>Custom markup</span>
</a>

getRawLinkAttributes($extraAttributes = null)

返回链接的属性数组。可以与Craft公开的 attr 或 tag 辅助器结合使用。

{% tag 'a' with entry.myLinkField.getRawLinkAttributes() %}
  <span>Custom markup</span>
{% endtag %}

辅助方法

getAllowCustomText()

返回字段是否允许用户输入自定义文本。

{{ entry.myLinkField.getAllowCustomText() }}

getAllowTarget()

返回字段是否显示在新窗口中打开链接的选项。

{{ entry.myLinkField.getAllowTarget() }}

getAriaLabel()

返回链接的aria标签。

{{ entry.myLinkField.getAriaLabel() }}

getCustomText($fallbackText = '')

返回链接的自定义文本。以下可能性中第一个非空文本将被选择

1. 链接的自定义文本。
2. 字段设置中定义的默认文本。
3. 传递给函数的回退文本。

{{ entry.myLinkField.getCustomText('My fallback text') }}

getDefaultText()

返回链接字段设置中设置的默认文本。

{{ entry.myLinkField.getDefaultText() }}

getElement($ignoreStatus = false)

返回链接元素（条目、资产等）或 NULL 如果没有链接元素。

默认情况下，仅返回已发布的元素。将 $ignoreStatus 设置为 TRUE 以检索未发布的元素。

{{ entry.myLinkField.getElement() }}

getEnableAriaLabel()

返回字段是否允许用户输入aria标签。

{{ entry.myLinkField.getEnableAriaLabel() }}

getEnableTitle()

返回字段是否允许用户输入链接标题。

{{ entry.myLinkField.getEnableTitle() }}

getIntrinsicText()

返回链接自身声明的文本（例如，链接条目或资产的标题）。

{{ entry.myLinkField.getIntrinsicText() }}

getIntrinsicUrl()

返回链接自身声明的URL（例如，链接条目或资产的URL）。考虑自定义查询或哈希，并将它们附加到结果中。

{{ entry.myLinkField.getIntrinsicUrl() }}

getTarget()

返回链接目标（例如：_blank）。

{{ entry.myLinkField.getTarget() }}

getText($fallbackText = "Learn More")

返回链接文本。以下选项中第一个非空文本将被选中：

1. 链接的自定义文本。
2. 链接元素定义的内在文本。
3. 字段设置中定义的默认文本。
4. 传递给函数的回退文本。

{{ entry.myLinkField.getText($fallbackText = "Learn More") }}

getType()

返回表示链接类型的字符串。该插件提供了以下链接类型：asset、category、custom、email、entry、site、tel、url 和 user。

{{ entry.myLinkField.getType() }}

getUrl($options = null)

返回链接的URL。

{{ entry.myLinkField.getUrl() }}

允许通过覆盖php函数parse_url返回的url属性来修改链接。支持以下选项：fragment、host、pass、path、port、query、scheme 和 user。

• 所有选项都需要传入字符串值。
• query 选项接受一个数组或哈希表。如果传递一个数组，默认情况下将合并原始URL的查询参数。要禁用此行为，必须将 queryMode 选项设置为 replace。

此示例强制执行https方案并替换原始URL的所有查询参数。

{{ entry.myLinkField.getUrl({
  scheme: 'https',
  queryMode: 'replace',
  query: {
    param: 'value'
  },
}) }}

hasElement($ignoreStatus = false)

返回链接是否指向一个元素（例如：条目或资产）。

{{ entry.myLinkField.hasElement() }}

isEmpty()

返回链接是否为空。空链接是指没有URL的链接。

{{ entry.myLinkField.isEmpty() }}

属性

属性通常公开链接的底层原始数据。

ariaLabel

在 cp 中输入的 aria 标签。

<a aria-label="{{ entry.myLinkField.ariaLabel }}">...</a>

customText

在 cp 中输入的自定义文本。

<a>{{ entry.myLinkField.customText }}</a>

target

链接目标文本。可以是 _blank 或空字符串。

<a target="{{ entry.myLinkField.target }}">...</a>

title

在 cp 中输入的标题。

<a title="{{ entry.myLinkField.title }}">...</a>

预加载

可以使用Crafts的with查询参数通过链接字段进行预加载。预加载可以在获取许多条目时（例如，在渲染菜单时）显著提高性能。

{% set entries = craft.entries({
  section: 'pages',
  with: 'myLinkField',
}).all() %}

API

您可以通过监听插件的EVENT_REGISTER_LINK_TYPES事件来注册额外的链接类型。如果您只想添加另一个元素类型，可以在您的模块中这样做：

use craft\commerce\elements\Product;
use lenz\linkfield\Plugin as LinkPlugin;
use lenz\linkfield\events\LinkTypeEvent;
use lenz\linkfield\models\element\ElementLinkType;
use yii\base\Event;

/**
 * Custom module class.
 */
class Module extends \yii\base\Module
{
  public function init() {
    parent::init();
    Event::on(
      LinkPlugin::class,
      LinkPlugin::EVENT_REGISTER_LINK_TYPES,
      function(LinkTypeEvent $event) {
        $event->linkTypes['product'] = new ElementLinkType(Product::class);
      }
    );
  }
}

每个链接类型都必须有一个唯一名称和一个扩展lenz\linkfield\models\LinkType的定义对象。请查看捆绑的链接类型ElementLinkType和InputLinkType，以了解如何编写自己的链接类型定义。

备注

从Fruit Link It升级

如果您希望迁移使用“Fruit Link It”创建的字段，请按照此处讨论和说明操作。

#51（评论）