🍱 使用指南

本文档适用于从已经有一定开发进度的 web 应用迁移到南大家园微应用。注意：在阅读本迁移指南之前，请先保证你已经阅读完上一篇文档：「mincu 技术文档 - 项目结构」

React 应用

Example - example/react-vite (opens in a new tab) Example - example/react-next (opens in a new tab)

推荐使用 Function Component 来开发 React 项目

安装依赖

# npm
npm i mincu-react
# yarn
yarn add mincu-react
# pnpm
pnpm i mincu-react

判断是否为 mincu 环境

获取用户名

import { mincu, Ready } from 'mincu-react'
 
const App = () => {
  const name = mincu.appData.user.profile.basicProfile.name
  
  return (
    <Ready>
      <div>用户名：{name}</div>
    </Ready>
  ) 
}

操作 UI

带云家园 token 调用一些 API

import axios from 'axios'
import { mincu, Ready } from 'mincu-react'
 
const fetcher = axios.create()
mincu.useAxiosInterceptors(fetcher)
 
const App = () => {
  const name = mincu.appData.user.profile.basicProfile.name
  
  const fetchData = async () => {
    const removeLoading = await mincu.toast.loading('加载中', 0)
    try {
      const res = await fetcher.get(
        'https://os.ncuos.com/api/user/profile/basic'
      )
      alert(JSON.stringify(res.data))
    } catch (e) {
      alert(e)
    } finally {
      removeLoading()
    }
  }
  
  return (
    <Ready>
      <div>
        用户名：{name}
        <button onClick={() => mincu.toScreen({ screen: '周课表' })}>
          跳转到周课表
        </button>
        <button onClick={() => mincu.exit()}>退出微应用</button>
        {/* new */}
        <button onClick={fetchSchoolLife}>测试云家园接口是否能成功拉取</button>
      </div>
    </Ready>
  )
}

Vue3 应用

Example - example/vue-vite (opens in a new tab)

安装依赖

# npm
npm i mincu-vanilla
# yarn
yarn add mincu-vanilla
# pnpm
pnpm i mincu-vanilla

示例

<!-- Ready.vue -->
<script setup lang="ts">
import { ref } from 'vue';
import { mincu } from 'mincu-vanilla'
 
defineProps<{
  fallback: any
}>();
 
const ready = ref(mincu.isReady && mincu.isApp)
 
</script>
 
<template>
  <template v-if="ready">
    <slot></slot>
  </template>
 
  <template v-if="!ready">
    <component :is="fallback"></component>
  </template>
</template>
 
<!-- App.vue -->
<script setup lang="ts">
import Fallback from './components/Fallback.vue';
import Ready from './components/Ready.vue';
import Home from './Home.vue'
</script>
 
<template>
  <Ready :fallback="Fallback">
    <Home></Home>
  </Ready>
</template>

API 调用

<script setup lang="ts">
import { mincu } from 'mincu-vanilla'
import Button from './components/Button.vue';
import useNativeState from './hooks/useNativeState'
import { watch } from 'vue';
 
const colorScheme = useNativeState('colorScheme')
const colors = useNativeState('colors', '')
 
watch(colorScheme, (newVal) => {
  document.body.style.background = newVal === 'dark' ? '#222' : '#fff'
  document.body.style.color = newVal === 'dark' ? '#fff' : '#000'
})
 
const studentId = mincu.userInfo.profile.entireProfile.base_info.xh
</script>
 
<template>
  <div style="margin-left: 10px; margin-right: 10px; margin-top: 10px; padding-bottom: 10px;">
    <div>
      <p className="font-medium text-xl m-2">
        学号: {{ studentId }}
      </p>
      <p className="font-medium text-xl m-2">
        主题色: {{ colorScheme }}
      </p>
      <Button :onClick="() => mincu.login('username', 'pwd')">
        登录
      </Button>
      <p className="font-medium text-xl m-2">colors 测试</p>
      <div
        className="text-gray-900 bg-gradient-to-r from-red-200 via-red-300 to-yellow-200 hover:bg-gradient-to-bl focus:ring-4 focus:outline-none focus:ring-red-100 dark:focus:ring-red-400 font-medium rounded-lg text-sm px-5 py-2.5 text-center m-3"
        :style="{ color: colors.white }">
        colors.white
      </div>
      <div
        className="text-gray-900 bg-gradient-to-r from-red-200 via-red-300 to-yellow-200 hover:bg-gradient-to-bl focus:ring-4 focus:outline-none focus:ring-red-100 dark:focus:ring-red-400 font-medium rounded-lg text-sm px-5 py-2.5 text-center m-3"
        :style="{ color: colors.black }">
        colors.black
      </div>
  </div>
</template>

Hooks

import { ref, onBeforeUnmount, onMounted } from 'vue'
import { States, mincuCore } from 'mincu-vanilla'
 
export default <T extends keyof States>(key: T, defaultVal?: any) => {
  const state = ref<States[T]>(defaultVal)
 
  const handle = (res: States[T]) => {
    state.value = res
  }
 
  onMounted(() => {
    handle(mincu?.[key] ?? {})
    mincuCore.listener(key, handle)
  })
 
  onBeforeUnmount(() => {
    mincuCore.remove(key, handle)
  })
 
  return state
}

其他应用

直接参考 example/mincu-vanilla (opens in a new tab)

安装依赖

# npm
npm i mincu-vanilla
# yarn
yarn add mincu-vanilla
# pnpm
pnpm i mincu-vanilla

API 调用

import { mincu } from 'mincu-vanilla'
 
// Show a toast
mincu.toast.success('Hello World')
// Exit
mincu.exit()

📚 项目结构 🎼 实现原理