迁移

将现有 UIkit 网站迁移到最新版本。

从 UIkit 3.17 迁移到 3.18

如果您创建了自定义 UIkit 样式并覆盖了 *-color-mode 变量，请确保将其设置为 light 或 dark。它不再可以设置为 none 或为空。

UIkit 3.18 为 Section、Tile、Card 和 Overlay 组件中的默认和静音样式修饰符引入了新的 *-color-mode Less 变量，就像对于主要和次要样式修饰符一样。由于默认的 UIkit 样式具有浅色背景，因此它们的色调变量默认设置为深色。如果您有一个深色自定义 UIkit 样式，其中色调变量更改为相反的颜色，那么您也必须将新的色调变量更改为浅色。

// For dark UIkit styles only 

@card-default-color-mode: light;

@overlay-default-color-mode: light;

@section-default-color-mode: light;
@section-muted-color-mode: light;

@tile-default-color-mode: light;
@tile-muted-color-mode: light;

从 UIkit 3.16 迁移到 3.17

Scroll 组件 现在会自动添加粘性元素（例如粘性导航栏）的高度作为滚动目标的偏移量，这样它就不会被粘性元素覆盖。如果已经为粘性元素设置了偏移量，则会累加 offset 选项。这意味着您不再需要设置 offset 选项来防止导航栏覆盖滚动目标。

Grid 组件 现在有一个新的砌体 pack 模式，它会将项目排序到空间最大的列中。为了保持向后兼容性，将砌体设置为 true 将只使用新的 pack 模式。要像以前一样以自然顺序显示项目，请使用 next 模式。

从 UIkit 3.15 迁移到 3.16

UIkit 3.16 简化了 Drop 组件 中的某些类。通过替换以下类来更新您的标记。

下拉菜单、下拉栏和导航栏下拉菜单 CSS 现在基于 Drop 组件。因此，它们不再拥有单独的 z-index Less 变量。如果您在自定义 UIkit 主题中使用了其中一个变量，则必须替换它们。

从 UIkit 3.14 迁移到 3.15

UIkit 3.15 中的 Nav 组件 现在使用 JavaScript 组件来创建导航项目父级图标，而不是将父级图标编译到 CSS 中。只需搜索 .uk-nav-parent-icon 类并将其从标记中删除即可。只需为每个带有子项的导航项目使用带有 uk-nav-parent-icon 属性的 span 即可。以下是一个快速示例。

<ul class="uk-nav-default" uk-nav>
    <li class="uk-parent">
        <a href="#">Parent <span uk-nav-parent-icon></span></a>
        <ul class="uk-nav-sub">…</ul>
    </li>
</ul>

Drop、Dropdown 和 Navbar Dropdown

Drop 组件、Dropdown 组件 和 Navbar 组件 组件从 pos 选项中删除了对齐方式 *-justify。搜索 pos: top-justify、pos: bottom-justify、pos: left-justify 和 pos: right-justify，并改用新的 stretch 选项。

boundary-align 选项也被删除。搜索 boundary: SELECTOR 与 boundary-align: true 的组合，并改用 target 选项，该选项使用 boundary 中的相同选择器。

flip 选项被拆分为两个选项 flip 和 shift。按如下方式更新选项。

如果位置是 top-* 或 bottom-*

如果位置是 left-* 或 right-*

display 选项已删除。改用 auto-update。

Navbar Dropbar

我们删除了 Navbar 组件中下拉栏的样式，现在改用新的 Dropbar 组件。这就是为什么 Navbar 组件除了 .uk-navbar-dropbar 类之外还设置了 .uk-dropbar 和 .uk-dropbar-top 的原因。如果您手动放置下拉栏标记，则需要自己添加这些类。

在 Less 中，我们删除了 @navbar-dropbar-background 变量，因此要设置背景，请改用 @dropbar-background 变量。确保添加您应用于导航栏下拉栏的任何其他样式。

Less 变量

以下 Less 变量也被重命名。如果您使用的是自定义 Less 主题，只需查找并替换这些 Less 变量。

从 UIkit 3.13 迁移到 3.14

UIkit 3.14 在 Sticky 组件 中将 top 和 bottom 选项重命名为 start 和 end。

它还弃用了 Sticky 组件 中的 position: auto 选项。只需改用新的 overflow-flip: true 选项。

从 UIkit 3.11 迁移到 3.12

UIkit 3.12 弃用了 Image 组件 中 <img> 元素的 uk-img。只需改用原生的 loading="lazy" 属性即可。这也适用于 uk-img 用于定位幻灯片或滑块中相邻幻灯片的情况。幻灯片和滑块这两种组件都开箱即用地支持延迟加载图像。

重要提示 此更改还要求 <img> 元素具有 width 和 height 属性，以防止布局发生偏移。

从 UIkit 3.10 迁移到 3.11

UIkit 3.11 向 Parallax 组件 添加了新的 start 和 end 选项，并弃用了 viewport 选项。用 end 选项替换 viewport 选项。只需计算您的视口值减 1，然后将其乘以 100vh + 100% 即可。以下是一些示例

从 UIkit 3.4 迁移到 3.5

在 UIkit 3.5 中，所有名称中包含 xxlarge 的 Less 变量和类名都被重命名为 2xlarge，以提高一致性。如果您使用的是自定义 Less 主题，只需查找并替换这些 Less 变量即可。在 Width 组件 中只有一个类需要在您的标记中更新。

从 UIkit 3.2 迁移到 3.3

UIkit 3.3 向 Container 组件 添加了一个新的 uk-container-xlarge 类，其宽度默认值为 1600px。这就是为什么 uk-container-large 类将其宽度从 1600px 更改为 1400px 的原因。通过替换以下类来更新您的标记。

从 UIkit 3.1 迁移到 3.2

文本组件

由于 UIkit 3.2 向 Text 组件 添加了一个新的 uk-text-bolder 类，因此 uk-text-bold 类现在应用了字体的 bold 粗细，而不是 bolder。@text-bold-font-weight 变量（以前设置为 bolder）已被删除。

从 UIkit 3.0 迁移到 3.1

UIkit 3.1 添加了 @deprecated Less 变量。默认情况下，它设置为 false，并且已弃用的类不会编译到 CSS 中。

如果您想稍后更新您的标记并使用已弃用的类以及新的类，请在您的自定义 UIkit 主题中将该变量设置为 true。

@deprecated: true;

标题组件

Heading 组件 中的主要和英雄类已弃用。通过替换以下类来更新您的标记。

从 UIkit 2 迁移到 3

Uikit 3 提供了一个迁移工具，该工具在您的浏览器中运行并列出从现有 Uikit 2 网站 进行的所有必要更改。有两种选项可用于运行该工具：通过书签或通过包含单个 JavaScript 文件。然后，必要的迁移更改将在您的浏览器控制台中列出。

浏览器书签

使用迁移工具的最简单方法是通过浏览器中的书签。然后，您可以通过单击书签来在您导航到的任何页面上运行该脚本。只需将以下链接拖动到您的浏览器书签部分。

拖动到您的书签栏 UIkit 3 迁移

或者，您可以手动创建一个书签，其 URL 为以下代码。

javascript: (function () {
    var script = document.createElement('script');
    script.setAttribute('src', 'https://uikit.cn/migrate.min.js');
    document.body.appendChild(script);
}());

HTML 集成

您还可以通过在您的网站上加载所需的 JavaScript 来运行迁移工具。这样，迁移脚本将始终在您的网站上加载。请记住，在完成迁移后删除它。在 </body> 标签关闭之前添加以下行。

<script src="https://uikit.cn/migrate.min.js"></script>

使用方法

要开始迁移，请将网站的 UIkit 2 文件替换为其 UIkit 3 等效文件（包括 JS 和 CSS），并使用上面列出的解决方案之一运行迁移工具。要了解如何更改标记，请打开浏览器的开发者控制台。您会看到一个警告和通知列表，告诉您需要更改什么。您可以单击任何消息旁边的箭头以查看有关必要更改的更多详细信息。

每个通知或警告消息都会告诉您要更改什么，包括所有受影响的 HTML 元素的列表。更复杂的更改将通过易于理解的示例进行解释。迁移的最佳方法是逐个修复组件。这样，您就可以在页面重新加载后查看错误消息是否消失，以及在您的网站上查看更改。

警告

警告突出显示所有不再支持或已在 UIkit 3 中更改的 CSS 类或 JavaScript 属性。为了将您的网站迁移到 UIkit 3，必须修复这些警告。

通知

通知突出显示可能不会破坏您网站的潜在问题。某些通知可能根本不需要更改。这是因为 UIkit 2 中的一些名称仍然存在于 UIkit 3 中，但现在属于不同的组件或具有不同的语义。这无法通过我们用于确定这是否是正确标记的选择器来检测，因此您需要查看它并决定您是否已经更改了它，或者仍然需要修复它。