leaf-island-uniapp

Leaf Island UI（uni-app 版）

一款专为 UniApp 打造的自然治愈系 / 卡通风格轻量组件库。目前声明支持 H5 / Web 和微信小程序；其他平台尚未纳入支持范围。

免责声明：本项目所有组件及素材均为原创或采用合法开源协议，与任何商业游戏作品无关。

组件前缀统一为 li-（如 Button → li-button）。

✨ 平台支持

平台支持范围以 package.json 中的 uni_modules.platforms 声明为准。其他平台需完成编译和运行验证后再加入支持列表。

📦 安装

npm 安装

在 uni-app CLI 项目中安装：

npm install leaf-island-uniapp

然后在 pages.json 中配置 Easycom 路径：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^li-(.*)": "leaf-island-uniapp/components/li-$1/li-$1.vue"
    }
  }
}

本包将 vue、@lucide/vue 和 lucide-static 声明为 peer dependencies，请确保宿主项目使用 Vue 3，并安装图标依赖：

npm install @lucide/vue lucide-static

uni_modules 安装

也可以把整个 leaf-island 目录放进 uni-app 项目根目录的 uni_modules/ 下：

your-uni-app-project/
├── uni_modules/
│   └── leaf-island/        <-- 复制这里
│       ├── components/
│       ├── styles/
│       ├── assets/
│       ├── index.less
│       ├── package.json
│       └── readme.md
├── pages.json
├── App.vue
└── main.js

放入后 无需额外配置 即可使用 li- 开头的任意组件（已内置 easycom 规则）。

若你把自己的项目 easycom 配置成 autoscan: true，也能自动识别；本包在 package.json 中已声明 easycom.custom 规则，放进 uni_modules 即生效。

图标组件依赖 Lucide 官方包：H5 端使用 @lucide/vue 渲染组件，小程序端通过 lucide-static 的 ?raw SVG 字符串生成 data URI 后交给 image 渲染。请一并安装：

npm install @lucide/vue lucide-static

li-icon 支持当前 lucide-static 版本的全部图标；小程序端为支持运行时任意图标名，会将全量 SVG 字符串编入包内。若后续对包体要求极高，可改回显式图标映射。

🎨 全局样式

组件样式使用 Less 设计 token 与 CSS 自定义属性。全局样式需在 App.vue 中引入一次：

<!-- App.vue -->
<style lang="less">
@import 'leaf-island-uniapp/index.less';
</style>

如果通过 uni_modules 目录安装，则使用 @import '@/uni_modules/leaf-island/index.less';。

• :root 与小程序 page 根节点会注入默认浅色 CSS 变量。
• 运行时切换：用 <li-theme-provider :theme="theme">...</li-theme-provider> 包裹内容，并把 theme 设为 light 或 dark。主题值可绑定 Vue 响应式状态；容器内的组件会继承对应主题色。
• 自定义主题：可在容器或其祖先覆盖 --animal-* CSS 变量。Less token 和组件色值映射见 styles/variables.less 与 styles/themes/。
• 字体：默认使用系统字体。如需自定义字体，用 uni.loadFontFace 注入后覆盖变量 --animal-font-family。完整示例见仓库 docs/theming-and-bundle.md。

🧩 组件清单（47 个）

图标来源：Lucide Icons，ISC License。

🚀 快速使用

<template>
  <view>
    <li-title>自然小岛</li-title>
    <li-divider />
    <li-button type="primary" @click="sayHi">上岛啦</li-button>
    <li-card title="今日天气">
      <li-typewriter text="晴，适合散步和观察自然～" />
    </li-card>
    <li-modal :open="showModal" title="欢迎" @close="showModal = false">
      <p>欢迎来到自然小岛！</p>
    </li-modal>
  </view>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import LiModal from 'leaf-island-uniapp/components/li-modal/li-modal.vue';

const showModal = ref(false);
function sayHi() {
  showModal.value = true;
}
</script>

使用 npm 安装时，Easycom 路径指向 node_modules 中的包；若 IDE 提示找不到，可按上面的 npm 包路径显式导入。使用 uni_modules 安装时，路径改为 @/uni_modules/leaf-island/...。

🧱 目录结构

leaf-island/
├── components/        # 47 个组件，目录名 = 组件名（li-xxx）
│   └── li-xxx/
│       ├── li-xxx.vue
│       └── types.ts   # 组件 props / emits 类型
├── area-data/         # 内置省、市、区县数据与级联选项工厂
├── styles/            # 主题变量、reset、全局样式（:root + page 双根注入）
├── assets/            # SVG / PNG / JPG 等静态资源
├── index.less         # 全局样式入口（@import 一次）
├── package.json       # uni_modules 元数据 + easycom 规则
└── readme.md

📄 License

见仓库 LICENSE。