跳到主要内容

快速开始

ice.js 支持小程序开发。由于小程序端大部分能力及配置均与 Web 应用对齐，本章节仅介绍小程序快速开始、与 Web 应用的差异点以及小程序独有能力的使用。

提示

当你准备开发小程序时，请务必阅读本模块文档。

创建小程序应用​

共有两种方式创建 ice.js 小程序应用：

1. 通过小程序模板创建​

$ npm create ice ice-app --template @ice/miniapp-scaffold
$ cd ice-app
$ npm install

创建完毕后可以直接跳到调试与构建章节。

2. 改造已有的 Web 应用​

将已有的 ice.js Web 应用改造为支持小程序开发，只需进行以下几步：

配置命令​

在 package.json 中配置以下 scripts 命令：

  "scripts": {
    "start": "ice start",
    "start:wechat": "ice start --target wechat-miniprogram",
    "start:ali": "ice start --target ali-miniapp",
    "build": "ice build",
    "build:wechat": "ice build --target wechat-miniprogram",
    "build:ali": "ice start --target ali-miniapp"
  }

配置小程序开发插件及运行时依赖​

安装小程序开发插件 @ice/plugin-miniapp 和小程序运行时依赖 @ice/miniapp-runtime：

$ npm install @ice/plugin-miniapp -D
$ npm install @ice/miniapp-runtime -S

在 ice.config.mts 中配置插件：

ice.config.mts
import miniapp from '@ice/plugin-miniapp';

export default defineConfig({
  plugins: [miniapp()],
});

添加 miniappManifest​

在 src/app.tsx 中导出 miniappManifest，在其中配置 routes 数组用以指定小程序中的页面（详见小程序-路由）:

export const miniappManifest = {
  routes: [
    // 初始化项目中仅有 index 一个页面
    'index' 
  ]
};

适配 HTML 标签样式​

从 Web 应用迁移而来意味着你的项目中使用了 HTML 标签，为了适配样式，你还需要在 src/global.css 引入样式的 polyfill：

@import '@ice/miniapp-html-styles/html';

关于在小程序中使用 HTML 标签的注意事项，详见文档使用 HTML 标签。

调试与构建​

当需要开发小程序时，执行对应的命令即可。例如，需要开发调试微信小程序时，执行

$ npm run start:wechat

需要构建微信小程序生产环境的产物时，执行

$ npm run build:wechat

编译完成后，命令行会给出相应提示，提醒开发者使用对应的小程序开发者工具打开编译产物目录进行调试预览：

Use wechat-miniprogram developer tools to open the following folder:
~/Code/ice-next/examples/miniapp-project/build

支持小程序平台​

可以看到，相比开发 Web 应用，开发小程序的命令需要传递 platform 参数，目前 ice.js 支持开发的小程序平台及其 platform 名称如下：

小程序平台platform
阿里系（支付宝、淘宝、钉钉等）ali-miniapp
微信wechat-miniprogram

暂未支持但计划支持的小程序平台及其 platform 名称如下：

小程序平台platform
字节bytedance-microapp
百度baidu-smartprogram
快手kuaishou-miniprogram

待支持能力​

  • 配置小程序原生应用生命周期及事件
  • 配置小程序原生页面生命周期及事件
  • 配置原生小程序 project.config.json
  • 与原生页面、组件、插件混用
  • 分包加载

不支持能力​

受小程序环境限制，以下 ice.js 提供的能力在小程序端不适用，相关章节中也会进行标注：

信息

小程序中的数据请求需要统一使用其提供的 request 相关 API，因此 ice.js 提供的数据模拟 Mock 能力对小程序不适用。小程序端的数据模拟能力可通过开发者工具进行配置使用，这里列出阿里及微信小程序的相关使用文档：

信息

没有经过适配的 Web 组件库暂时无法直接在 ice.js 小程序端使用。