README

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

要求

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

安装

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

打开您的终端并导航到您的Craft项目
```
cd /path/to/project
```

然后告诉Composer加载插件

composer require towardstudio/linkfield

最后，安装并启用插件

./craft plugin/install linkfield
./craft plugin/enable linkfield

使用

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

模板化

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

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

字段值实际上是towardstudio\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 = '')

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

链接的自定义文本。
字段设置中定义的默认文本。
传递给函数的备用文本。

{{ 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 = "了解更多")

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

链接的自定义文本。
链接元素定义的内在文本。
字段设置中定义的默认文本。
传递给函数的备用文本。

{{ 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 towardstudio\linkfield\Plugin as LinkPlugin;
use towardstudio\linkfield\events\LinkTypeEvent;
use towardstudio\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);
      }
    );
  }
}

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

备注

从Fruit Link It升级

如果您想迁移使用"Fruit Link It"创建的字段，请遵循此处讨论和说明。

sebastian-lenz/craft-linkfield#51 (评论)

towardstudio / linkfield

维护者

详细信息