README

注意：从 Kirby 4 开始，内置了链接字段。考虑使用它代替！

kirby-link-field

Kirby 4 字段，适用于任何类型的链接 - 外部链接、页面、文件、电子邮件、电话。提供文本、弹出框（真/假）和哈希设置。

该插件使用原生 Kirby 字段来处理页面、文件、URL、电子邮件和电话。

如果链接字段在结构字段内部使用，则链接字段将获得一个漂亮的预览。页面和文件的链接将获得原生的页面/文件预览。

贡献

请阅读 CONTRIBUTING.md 了解详细信息。
通过赞助我们支持开发。

安装

使用 Composer 从 oblik/kirby-link-field on packagist 安装。

composer require oblik/kirby-link-field

...或查看其他插件安装方法。

蓝图

添加一个字段并将其类型设置为 legacyLink

fields:
  myfield:
    type: legacyLink
    label: Link

注意：字段类型名称在版本 6.0.1 中从 link 更改为 legacyLink，以防止与 Kirby 4 内置的链接字段冲突。

要定义您想要的链接类型，请使用 linkTypes。可能的值有 url、page、file、email 和 tel

fields:
  myfield:
    type: legacyLink
    label: Link
    linkTypes:
      - page
      - url

注意：由于 Kirby 内部逻辑的问题，此选项在版本 4.0.0 中从 options 更改为 linkTypes。

默认情况下，您也可以指定链接文本、弹出框（真/假）和哈希。您可以通过使用 settings 值禁用这些选项或更改它们的显示方式。

fields:
  myfield:
    type: legacyLink
    label: Link
    settings:
      popup:
        width: 1/3
        label: External Link
        help: Open link in a new tab?
      text:
        width: 2/3
      hash: false

要完全禁用设置，请设置

settings: false

您还可以全局应用此类设置

config/config.php

return [
    'oblik.link-field' => [
        'linkTypes' => [
            'url',
            'page'
        ],
        'settings' => [
            'popup' => [
                'label' => 'External Link'
            ]
        ]
    ]
];

...

return [
    'oblik.link-field.settings' => false
];

页面/文件设置

您可以指定页面/文件字段的设置。例如

fields:
  myfield:
    type: legacyLink
    pages:
      query: page.siblings
      image:
        cover: true
    files:
      query: site.files
      text: "{{ file.id }}"

用法

要渲染链接，请使用提供的 toLinkObject() 方法。它返回 Link 类的实例。

假设您有一个具有以下值的字段

Myfield:

type: page
value: page://hMipdcIiFl53yXdC
text: My Text
popup: true
hash: heading-1

要获取链接对象，您应该调用

$link = $page->myfield()->toLinkObject();

`$link->isEmpty()`

自版本 5.0.0 以来

返回 true 或 false，具体取决于链接是否为空。请注意，当字段为空时，它返回 true，并且当无法生成有效 URL 时也会返回 true。如果您有一个损坏的链接，例如

type: page
value: page://broken-uuid

…链接仍然被认为是空的，因为没有这样的页面。

`$link->isNotEmpty()`

自版本 5.1.0 以来

$link->isEmpty() 的相反。

`$link->url()`

返回链接 URL，包括哈希

http://localhost/home#heading-1

注意：对于 email 和 tel 链接，由于它们不是实际的链接，所以值是 null。

`$link->href()`

返回链接 href

http://localhost/home#heading-1

如果链接类型是 email 或 tel，则具有相应的 mailto: 或 tel:。

注意：当您尝试将类转换为字符串时，会自动调用此方法，这意味着

echo $page->myfield()->toLinkObject();

...与

echo $page->myfield()->toLinkObject()->href();

`$link->attr([$attributes])`

返回链接属性，与可选的 $attributes 合并

href="http://localhost/home#heading-1" rel="noopener noreferrer" target="_blank"

`链接对象->tag([属性])`

返回一个完整的 <a> 标签，包含从可选的 $attributes 合并的属性

<a
  href="http://localhost/home#heading-1"
  rel="noopener noreferrer"
  target="_blank"
>
  My Text
</a>

`链接对象->title()`

返回链接文本、页面标题、文件标题、文件名或最终值。用于为 tag() 方法生成链接文本。

检索属性

您可以通过调用方法来获取链接的属性

echo $link->type();     // page
echo $link->value();    // home
echo $link->text();     // My Text
echo $link->popup();    // true
echo $link->hash();     // heading-1

`字段对象->toValidLink()`

自版本 5.2.0 开始

使用 $field->toLinkObject() 可能有些繁琐，之后总是需要用 $link->isNotEmpty() 检查链接是否有效

<?php $link = page()->myLinkField()->toLinkObject(); ?>
<?php if ($link->isNotEmpty()) : ?>
  <a href="<?= $link->href() ?>">Click here!</a>
<?php endif ?>

在这种情况下，您可以使用 $field->toValidLink()

<?php if ($link = page()->myLinkField()->toValidLink()) : ?>
  <a href="<?= $link->href() ?>">Click here!</a>
<?php endif ?>

toValidLink() 方法返回

如果链接无效或为空，则返回 null
当链接有效且存在时，返回链接对象

从 URL 字段迁移

如果您之前使用过 URL 字段

fields:
  myfield:
    type: url

...您只需将其更改为

fields:
  myfield:
    type: legacyLink

...它就会工作。此外，toLinkObject() 方法可以处理您的 TXT 文件中的两种链接格式。如果您有

Myfield: https://example.com

...

Myfield:

type: url
value: https://example.com

支持

如果您觉得这个插件很有用，并希望获得更好的支持，请考虑赞助我们。谢谢！🙏

oblik / kirby-link-field

维护者

详细信息