安装与引入

1. 放置组件库

将 jzfw-ui 目录放入项目的 uni_modules/ 下：

your-project/
└── uni_modules/
    └── jzfw-ui/
        ├── components/
        ├── core/
        ├── hooks/
        ├── icons/
        ├── locale/
        ├── theme/
        ├── types/
        ├── config.uts
        ├── index.uts
        └── package.json

jzfw-ui 依赖以下同系列插件，请一并放入 uni_modules/：jzfw-frame（帧驱动）、jzfw-svg（SVG 渲染）、jzfw-share（系统分享）、jzfw-open-web（打开网页）。

2. 自动注册（easycom）

组件遵循 easycom 默认规则自动注册（uni_modules/*/components/组件名/组件名.uvue），无需修改 pages.json 的 easycom 配置，模板中直接使用 <jz-button> 等标签即可。

3. 引入图标字体

图标基于 remixicon 字体，需在 App.uvue 的 <style> 中引入一次：

/* App.uvue */
<style>
  @import "@/uni_modules/jzfw-ui/icons/index.scss";
</style>

4. 初始化主题与语言（推荐）

在 App.uvue 的 onLaunch 中初始化主题监听与语言监听：

<script setup lang="uts">
  import { initTheme, initLocale } from "@/uni_modules/jzfw-ui";

  onLaunch(() => {
    initTheme();   // 监听系统 / App / 宿主主题变化
    initLocale();  // 探测系统语言并监听语言变化
  });
</script>

• initTheme()：App 端监听 onOsThemeChange / onAppThemeChange，小程序端监听 onHostThemeChange。H5 端 onHostThemeChange 存在打包丢失问题，需由宿主自行调用 setTheme 桥接。
• initLocale(value?)：触发一次语言探测；非 App 端监听 onLocaleChange。传入非空 value 时覆盖默认语言（默认 zh-cn）。

5. 使用页面基座 jz-page

推荐每个页面以 <jz-page> 作为根节点。它提供主题背景、可滚动容器、可选回到顶部按钮，并挂载全局反馈服务 jz-ui（toast / confirm / loading），使页面内任意位置都能 useUi() 唤起反馈。

<template>
  <jz-page>
    <!-- 页面内容 -->
  </jz-page>
</template>

若不使用 jz-page，也可手动在页面放置 <jz-ui></jz-ui> 来启用 useUi() 命令式反馈。详见 [全局服务 useUi](/guide/。

6. 环境要求

依赖	版本
HBuilderX	^4.75
uni-app x	^5.24

平台支持

平台	支持
App-Android / App-iOS	✅
App-鸿蒙 (HarmonyOS)	✅
Web (H5) Chrome / Safari	✅
微信小程序	✅

下一步

• [快速上手](/guide/