[{"value":"快速开始","id":"快速开始","hLevel":2,"level":1},{"value":"API 方法","id":"api-方法","hLevel":2,"level":1,"children":[{"value":"trigger()","id":"trigger","hLevel":3,"level":2},{"value":"exit()","id":"exit","hLevel":3,"level":2}]},{"value":"使用示例","id":"使用示例-2","hLevel":2,"level":1,"children":[{"value":"示例 1：数据加载","id":"示例-1数据加载","hLevel":3,"level":2},{"value":"示例 2：表单保存","id":"示例-2表单保存","hLevel":3,"level":2}]},{"value":"注意事项","id":"注意事项","hLevel":2,"level":1,"children":[{"value":"务必配对使用 trigger() 和 exit()","id":"务必配对使用-trigger-和-exit","hLevel":3,"level":2},{"value":"避免嵌套使用","id":"避免嵌套使用","hLevel":3,"level":2}]}]

加载

Loading（加载）是一个用于显示全局加载状态的组件，通过在 SHOPLINE 商家后台页面顶部显示进度条动画，向商家传达应用正在处理请求或加载数据。它能有效管理预期，让商家了解应用的响应状态，避免因等待而产生不确定感。

快速开始

以下示例展示了加载组件的基本实现方式：

import Client, { Loading, shared } from '@shoplineos/app-bridge';
// 1. 初始化 App Bridge
const app = Client.createApp({
  appKey: 'your-app-key',
  host: shared.getHost(),
});
// 2. 创建 Loading 实例
const loading = Loading.create(app);
// 3. 显示加载状态
loading.trigger();
setTimeout(() => {
  loading.exit();
}, 2000);

当调用 trigger() 方法后，会在页面顶部显示加载进度条，效果如下：

API 方法

trigger()

(): void

开始显示加载状态。

使用示例

// 显示加载状态
loading.trigger();

exit()

(): void

结束并隐藏加载状态。

使用示例

// 隐藏加载状态
loading.exit();

使用示例

示例 1：数据加载

import Client, { Loading, shared } from '@shoplineos/app-bridge';
const app = Client.createApp({
  appKey: 'your-app-key',
  host: shared.getHost(),
});
const loading = Loading.create(app);
// 加载商品数据
const fetchProducts = async () => {
  // 显示加载状态
  loading.trigger();
  try {
    const response = await fetch('/api/products');
    const products = await response.json();
    // 处理数据
    console.log('商品数据:', products);
  } catch (error) {
    console.error('加载失败:', error);
  } finally {
    loading.exit();
  }
};
fetchProducts();

示例 2：表单保存

const handleSave = async (formData) => {
  // 显示加载状态
  loading.trigger();
  try {
    // 提交表单数据
    await saveProduct(formData);
    // 保存成功
    console.log('保存成功');
  } catch (error) {
    // 保存失败
    console.error('保存失败:', error);
  } finally {
    // 隐藏加载状态
    loading.exit();
  }
};

注意事项

务必配对使用 trigger() 和 exit()

每次调用 trigger() 后必须确保调用 exit()，否则加载状态会一直显示，影响使用体验。

// 推荐：使用 try-finally 确保 exit() 会被调用
const loadData = async () => {
  loading.trigger();
  try {
    await fetchData();
  } finally {
    loading.exit(); // 无论成功或失败都会执行
  }
};

避免嵌套使用

不要在已经显示加载状态时重复调用 trigger()，这可能导致加载状态无法正确关闭。

// 不推荐：嵌套使用
loading.trigger();
loading.trigger(); // 避免重复调用
loading.exit(); // 可能无法正确关闭
// 推荐：使用标志位控制
let isLoading = false;
const loadData = async () => {
  if (isLoading) return;
  isLoading = true;
  loading.trigger();
  try {
    await fetchData();
  } finally {
    loading.exit();
    isLoading = false;
  }
};