迁移指南

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

从 UIkit 3.24 迁移到 3.25

UIkit 3.25 重构了 Accordion 组件。手风琴的样式被移入独立的样式修饰符，以便在不带任何样式的情况下使用手风琴。要应用默认样式，请在所有手风琴上添加 .uk-accordion-default 类来更新标记。我们也相应地重命名了所有手风琴的 Less 变量和钩子。如果你在自定义 Less 主题中使用了这些 Less 变量和钩子，只需查找并替换它们。

此外，手风琴图标现在由一个 JavaScript 组件生成，而不再编译进 CSS。要恢复该图标，只需在手风琴标题的末尾添加一个带 uk-accordion-icon 属性的 span 元素。例如：

<a class="uk-accordion-title" href>Item 1 <span uk-accordion-icon></span></a>

Less Variables

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

从 UIkit 3.23 迁移到 3.24

UIkit 3.24 重构了 Countdown 组件。几乎所有 Less 变量都被移除。如果你曾使用 Less 变量自定义倒计时，就必须把它们删除。只需在 Less 文件中搜索 @countdown。请改用 Heading 组件 或 Base 组件 中的文本类来为倒计时设置样式。

我们还废弃了 Video 和 Cover 组件中的 automute 选项。视频请改用 muted 属性，YouTube 使用 mute=1，Vimeo 使用 muted=1。

我们移除了 @deprecated Less 变量。如果你在自定义 UIkit 主题中把该变量设为 true，只需将其删除，并确保你已经完成 UIkit 3.0 到 3.1 和 UIkit 3.4 到 3.5 的迁移。

从 UIkit 3.22 迁移到 3.23

UIkit 3.23 在 Height Viewport 组件 中将 minHeight 选项重命名为 min。

从 UIkit 3.21 迁移到 3.22

Lightbox 组件 经过了重构。我们移除了 uk-lightbox-toolbar-icon 和 uk-lightbox-button 类，以及所有以 @lightbox-toolbar-icon-* 和 @lightbox-button-* 开头的 Less 变量。如果你使用这些类或 Less 变量中的某一个自定义过灯箱，就必须将其删除。

我们将 uk-lightbox-toolbar 类重命名为 uk-lightbox-caption，包括其所有 Less 变量。如果你使用的是自定义 Less 主题，只需查找并替换这些 Less 变量。

以下 Less 变量也被重命名。

Search 组件 现在以不同的方式计算搜索框和搜索图标的内边距。此外，搜索的中号和大号样式已改为与搜索默认样式外观一致，只是尺寸不同。如果你自定义过搜索的 Less 变量，需要修订你的自定义内容。

从 UIkit 3.20 迁移到 3.21

UIkit 3.21 在 Search 组件 中引入了一个搜索修饰符，专门用于导航栏中的搜索。此前已有一个同名但主要用于下拉菜单的旧搜索修饰符。我们将这个修饰符重命名为 medium，因为它的样式比默认搜索略大一些。替换下列类来更新你的标记。

如果你在自定义 UIkit 主题中自定义过搜索导航栏修饰符的 Less 变量，就必须替换它们。

从 UIkit 3.17 迁移到 3.18

如果你创建过自定义 UIkit 样式并覆盖了某个 *-color-mode 变量，请确保它被设置为 light 或 dark。它不能再设置为 none 或留空。

UIkit 3.18 为 Section、Tile、Card 和 Overlay 组件中的 default 和 muted 样式修饰符引入了新的 *-color-mode Less 变量，就像 primary 和 secondary 样式修饰符那样。由于默认的 UIkit 样式使用浅色背景，这些颜色模式变量默认被设为 dark。如果你的自定义 UIkit 样式是深色的，且颜色模式变量会切换为相反的颜色，那么你也必须把新增的颜色模式变量改为 light。

// 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 模式，它会把项目分配到空间最多的列中。为了保持向后兼容，将 masonry 设为 true 时只会使用新的 pack 模式。要像以前那样按自然顺序显示项目，请使用 next 模式。

从 UIkit 3.15 迁移到 3.16

UIkit 3.16 简化了 Drop 组件 中的一些类。替换下列类来更新你的标记。

Dropdown、Dropbar 和 Navbar Dropdown 的 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-align: true 组合使用的 boundary: SELECTOR，改用新的 target 选项，并填入 boundary 中相同的选择器。

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

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

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

display 选项被移除。请改用 auto-update。

Navbar Dropbar

我们移除了 Navbar 组件中 dropbar 的样式，改为使用新的 Dropbar 组件。因此，Navbar 组件除 .uk-navbar-dropbar 类之外，还会设置 .uk-dropbar 和 .uk-dropbar-top。如果你手动放置 dropbar 的标记，需要自己添加这些类。

在 Less 中我们移除了 @navbar-dropbar-background 变量，因此要设置背景，请改用 @dropbar-background 变量。同时确保把你对导航栏 dropbar 应用过的其他样式也一并加上。

Less Variables

以下 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 被用于定位 Slideshow 或 Slider 中相邻的幻灯片，也同样如此。Slideshow 和 Slider 这两个组件开箱即支持图片懒加载。

重要 这一变更还要求 <img> 元素具有 width 和 height 属性，以避免布局偏移。

从 UIkit 3.10 迁移到 3.11

UIkit 3.11 为 Parallax 组件 新增了 start 和 end 选项，并废弃了 viewport 选项。用 end 选项替换 viewport 选项。只需用 1 减去你的 viewport 值，再乘以 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

Text Component

由于 UIkit 3.2 为 Text 组件 新增了 uk-text-bolder 类，uk-text-bold 类现在只会应用字面意义上的 bold 字重，而不再是 bolder。原本设为 bolder 的 @text-bold-font-weight 变量已被移除。

从 UIkit 3.0 迁移到 3.1

UIkit 3.1 新增了 @deprecated Less 变量。默认值为 false，已废弃的类不会编译进 CSS。

如果你想稍后再更新标记，并让已废弃的类与新类一起使用，请在自定义 UIkit 主题中把该变量设为 true。

@deprecated: true;

Heading Component

Heading 组件 中的 Primary 和 Hero 类已废弃。替换下列类来更新你的标记。

从 UIkit 2 迁移到 3

Uikit 3 提供了一个在浏览器中运行的迁移工具，它会列出从已有的 Uikit 2 站点 迁移所需的所有改动。运行该工具有两种方式：通过书签，或引入一个 JavaScript 文件。所需的迁移改动随后会列在浏览器的控制台中。

浏览器书签

使用迁移工具最简单的方式是通过浏览器书签。之后只需点击该书签，就能在你访问的任意页面上运行脚本。把下面的链接拖到浏览器的书签栏即可。

拖到你的书签栏 UIkit 3 Migration

或者，你可以用下面的代码作为 URL 手动创建一个书签。

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

HTML integration

你也可以通过在网站中加载所需的 JavaScript 来运行迁移工具。这样迁移脚本会始终在你的网站上加载。请记得在完成迁移后移除它。把下面这一行添加到 </body> 结束标签之前。

<script src="https://getuikit.com/migrate.min.js"></script>

Usage

要开始迁移，请把网站中的 UIkit 2 文件替换为对应的 UIkit 3 文件（JS 和 CSS 都要替换），然后用上面列出的任一方式运行迁移工具。要了解如何修改标记，请打开浏览器的开发者控制台。你会看到一列警告和提示，告诉你需要修改的内容。点击任意消息旁的箭头，可以查看更多关于所需改动的细节。

每条提示或警告都会告诉你需要修改什么，并列出所有受影响的 HTML 元素。较复杂的改动会用易于理解的示例加以说明。最好的迁移方式是逐个组件地修复。这样你可以在页面重新加载后确认错误消息是否消失，同时也能看到网站上的变化。

Warnings

警告会标出所有不再受支持或在 UIkit 3 中已发生变化的 CSS 类或 JavaScript 属性。必须修复这些警告，才能把网站迁移到 UIkit 3。

Notices

提示会标出可能存在问题、但未必会破坏网站的地方。有些提示可能完全不需要改动。这是因为 UIkit 2 中的某些名称在 UIkit 3 中仍然存在，但现在属于不同的组件，或者语义已经不同。我们用来判断标记是否正确的选择器无法检测到这种情况，因此你需要自行查看并判断是已经改好，还是仍需修复。