Alibaba/ice 项目核心 API 使用指南

Alibaba/ice 项目核心 API 使用指南

ice ICE是阿里巴巴开源的一款企业级中后台搭建工具，提供了丰富的组件库、模板以及可视化拖拽功能，帮助企业快速构建高质量的企业级应用。 项目地址: https://gitcode.com/gh_mirrors/ice1/ice

前言

Alibaba/ice 是一个基于 React 的企业级前端解决方案，提供了丰富的 API 来简化开发流程。本文将深入解析 ice 框架的核心 API 及其使用场景，帮助开发者更好地构建企业级应用。

基础配置 API

defineAppConfig - 应用配置定义

defineAppConfig 是 ice 框架中用于定义应用全局配置的核心方法，它提供了类型安全的应用配置定义方式。

import { defineAppConfig } from 'ice';

export default defineAppConfig(() => ({
  app: {
    rootId: 'ice-container',  // 指定应用挂载的 DOM 节点 ID
    // 其他应用级配置...
  }
}));

使用场景：

• 定义应用挂载节点
• 配置全局错误边界
• 设置应用级缓存策略

definePageConfig - 页面配置定义

definePageConfig 用于定义页面级配置，支持插件扩展，是 ice 框架实现页面级能力扩展的基础。

import { definePageConfig } from 'ice';

export const pageConfig = definePageConfig(() => ({
  title: '关于我们',  // 页面标题
  meta: [            // SEO 相关元信息
    {
      name: 'theme-color',
      content: '#eee',
    },
  ],
}));

最佳实践：

• 每个路由组件都应定义自己的 pageConfig
• 可通过插件扩展支持更多页面级配置项

路由相关 API

history - 路由控制

ice 提供了统一的路由控制 API，基于 react-router 封装，提供一致的路由操作体验。

import { history } from 'ice';

// 封装路由跳转方法
export function navigateTo(link: string) {
  history.push(link);
}

注意事项：

• 在应用初始化完成前不要直接调用
• 推荐封装为工具方法使用

路由 Hooks 集合

ice 提供了一系列路由相关的 React Hooks，极大简化了路由相关开发：

useParams - 获取动态路由参数

// 路由规则：/user/:id
// 当前路径：/user/123
const params = useParams();
// params = { id: '123' }

useSearchParams - 处理查询参数

const [searchParams, setSearchParams] = useSearchParams();

// 获取参数
console.log(searchParams.get('page'));

// 修改参数
setSearchParams({ page: '2' });

useNavigate - 编程式导航

const navigate = useNavigate();

// 跳转页面
navigate('/login');

// 替换当前历史记录
navigate('/home', { replace: true });

useLocation - 获取位置信息

const location = useLocation();
// 包含 pathname, search, hash, state 等信息

数据管理 API

useAppData - 全局应用数据

useAppData 配合 dataLoader 实现全局数据管理：

export const dataLoader = defineDataLoader(async () => {
  return await fetchUserInfo();
});

组件中使用：

const userData = useAppData();

useData - 页面级数据

useData 用于获取页面级数据，需配合页面数据加载器使用：

// 在页面组件中
const pageData = useData();

渲染控制 API

useMounted - 渲染状态检测

const mounted = useMounted();
return mounted ? <ClientComponent /> : <Loading />;

ClientOnly - 客户端渲染组件

<ClientOnly fallback={<Spinner />}>
  {() => <BrowserOnlyComponent />}
</ClientOnly>

dynamic - 动态加载组件

const AsyncComponent = dynamic(
  () => import('./HeavyComponent'),
  { 
    ssr: false,  // 禁用服务端渲染
    fallback: <Loading /> 
  }
);

布局与导航组件

KeepAliveOutlet - 路由缓存

<KeepAliveOutlet />

Link - 导航链接

<Link to="/about" state={{ from: 'home' }}>关于</Link>

Outlet - 子路由渲染

// Layout 组件中
<Outlet />

类型定义

ice 提供了完善的 TypeScript 类型支持：

import type { AppConfig, RouteConfig } from 'ice';

总结

Alibaba/ice 提供的这套 API 体系覆盖了企业级应用开发的各个方面，从配置管理、路由控制到数据流管理和渲染优化，开发者可以基于这些 API 快速构建高质量的前端应用。合理使用这些 API 可以显著提升开发效率和代码质量。

ice ICE是阿里巴巴开源的一款企业级中后台搭建工具，提供了丰富的组件库、模板以及可视化拖拽功能，帮助企业快速构建高质量的企业级应用。 项目地址: https://gitcode.com/gh_mirrors/ice1/ice