Appearance

Iconify for Vue 函数：loadIcons ​

本教程属于 Iconify for Vue 函数教程 的一部分。

函数 loadIcons() 从 Iconify API 检索图标。

何时使用此函数：

  • 预加载多个稍后将使用的图标。这将确保在需要时图标数据已可用，并且加载速度更快。
  • 如果你需要在图标数据可用后立即获取。例如，在渲染自定义组件时。但是，如果你只需要加载单个图标，还有更易用的 loadIcon()。

此函数是预加载已知将来会用到的图标的最有效方式。它会批量从 Iconify API 加载图标数据，从而减少查询次数。

使用相同的图标名称多次调用该函数是安全的，组件不会从 Iconify API 重复加载图标数据。如果你设置了回调参数，即使图标是通过其他 loadIcons() 调用加载的，回调也会被正确触发，从而确保回调的可靠性。

使用方法 ​

该函数包含以下参数：

  • icons，(string|IconifyIconName)[]。要加载的图标列表。
  • callback，function。可选的回调函数。该回调不仅在所有图标获取完成时调用，在部分图标获取完成时也会调用。

该函数返回一个 function，你可以使用它来停止加载图标。例如，当你在自定义组件中加载图标，但图标尚未加载完成时组件的生命周期就已结束，此时就需要使用它来移除回调。

图标列表 ​

图标列表是一个数组。每个元素可以是字符串，例如 mdi:home，或 IconifyIconName 对象。

回调函数 ​

可选回调函数包含以下参数：

  • loaded，IconifyIconName[]。已加载的图标列表。
  • missing，IconifyIconName[]。API 上不可用的图标列表。
  • pending，IconifyIconName[]。仍在加载中的图标列表。
  • unsubscribe，function。用于取消加载的函数。它与调用 loadIcons() 的返回值相同。

IconifyIconName 类型 ​

IconifyIconName 是一个简单的对象，包含以下属性，所有属性均为必填：

  • provider，string。API 提供商。对于公共 Iconify API，该值为空字符串 ""。
  • prefix，string。图标集前缀。
  • name，string。图标名称。

示例 ​

加载单个图标的简单回调：

jsimport { loadIcons } from '@iconify/vue';

const iconName = 'mdi:home';
loadIcons([iconName], (loaded, missing, pending, unsubscribe) => {
   if (loaded.length) {
       console.log(
           `Icon ${iconName} have been loaded and is ready to be renderered.`
       );
       return;
   }

   if (missing.length) {
       console.log(`Icon ${iconName} does not exist.`);
       return;
   }

   if (pending.length) {
       // Pending icons list in this example is empty.
       // If you call loadIcons() with multiple icons, pending list might not be empty, but for one icon it is always empty.
       //
       // Callback is called when something changes, with 1 icon there can only be 2 type of changes: icon has loaded or icon is missing.
   }
});

loadIcons() 的异步版本：

jsimport { loadIcons } from '@iconify/vue';

/**
* Function to load icons, returns Promise
*/
function loadTestIcons(icons) {
   return new Promise((fulfill, reject) => {
       loadIcons(icons, (loaded, missing, pending, unsubscribe) => {
           if (pending.length) {
               // Icons are pending, wait for all to load/fail
               //
               // If pending list is not empty, callback will be called
               // again when all icons are either loaded or missing
               return;
           }
           if (missing.length) {
               reject({
                   loaded,
                   missing,
               });
           } else {
               fulfill({
                   loaded,
               });
           }
       });
   });
}

/**
* Usage example in async function
*/
async function test() {
   // Wait for icons to load
   await loadTestIcons(['jam:info', 'cil:locomotive', 'cil:paper-plane']).catch(
       (err) => {
           console.error('Failed to load icons:', err.missing);
       }
   );

   // Do stuff with loaded icons
   console.log('Loaded!');
}
test();

组件示例 ​

此示例动态加载图标数据，并在图标加载期间渲染 <slot />。虽然 Vue 组件本身已经具备此功能，因此该示例显得有些多余，但它用于展示如何使用 getIcon() 和 loadIcons()。

jsimport { Icon, getIcon, loadIcons } from '@iconify/vue';
import { h, defineComponent, ref } from 'vue';

export default defineComponent({
   components: {
       Icon,
   },
   props: ['icon'],
   setup() {
       // 用于存储取消加载函数的变量
       const loader = ref(null);

       // 图标数据
       const data = ref(null);

       // 检查图标数据的函数
       const check = (icon: string) => {
           const iconData = getIcon(icon);

           // 取消旧的加载器
           if (loader.value) {
               loader.value();
               loader.value = null;
           }

           if (iconData) {
               data.value = iconData;
           } else {
               loader.value = loadIcons([icon], () => {
                   data.value = getIcon(icon);
               });
           }
       };
       return {
           loader,
           data,
           check,
       };
   },
   watch: {
       icon: {
           immediate: true,
           handler(value) {
               // 检查新值
               this.check(value);
           },
       },
   },
   // 停止加载
   unmounted() {
       const loader = this.loader.value;
       if (loader) {
           loader();
       }
   },
   render() {
       const icon = this.data;
       if (icon) {
           return h(Icon, {
               icon,
           });
       }
       return this.$slots.default ? this.$slots.default() : null;
   },
});

如果您只想加载单个图标，还可以使用更简单的 loadIcon()。