Skip to content

Latest commit

 

History

History
220 lines (154 loc) · 5.84 KB

README.md

File metadata and controls

220 lines (154 loc) · 5.84 KB
Raw

Mincu 南大家园 JS API

文档地址

https://mincu.vercel.app/

什么是 Mincu？

iNCU 为其内嵌的 WEB 页面提供了丰富的 JS API，用来扩展内嵌页面 JS 的能力，如获取用户信息、操作原生 UI、获取原生 UI 和数据调用能力，以及解决你最头疼的认证系统。

为什么要用？

  1. 定制属于你的 webview，做最极致的用户体验

  2. 无需再为调试客户端头疼，使用 Web 开发技术即可获得和 Native 一样的体验

  3. 跨平台调用原生能力

  4. 可唤起系统原生的 UI 界面/组件，让 Web App 更 Native 化

  5. 使用客户端分享功能，打通用户分享转发链路

迭代计划

  1. 集成更多原生功能

  2. useNativeState 状态缓存

  3. 高效调试方案

  4. 脚手架能力 (@Dollie)

  5. 考虑将原生代码同样集成于本仓库

  6. 白名单系统

  7. ...

使用说明

Quick Start

快速创建 mincu 项目：

# npm
$ npm init mincu@latest
# yarn
$ yarn create mincu
# pnpm
$ pnpm create mincu
# or
$ npx create-mincu

安装依赖

React

$ npm install mincu-react
# or
$ yarn add mincu-react

其他 (Vue、Vanilla)

$ npm install mincu-vanilla
# or
$ yarn add mincu-vanilla

引入

import { useLogin } from 'mincu-react' // or mincu-hooks

const App = () => {
  // 使用 App 端登录并获取是否初始化 Web 容器状态
  // useLogin 是一个组合 hook
  // 里面包含 useAppReady 和登录状态获取并存储的逻辑
  const { isReady } = useLogin()

  if (!isReady) {
    return <div>Loading</div>
  }

  return <div>Thank you for using mincu</div>
}

接收 Native -> Web 通信方法

import { useNativeState } from 'mincu-react' // or mincu-hooks

const App = () => {
  // 已初始化
  
  // 使用 Native 对 Web 的通信实现颜色主题状态共享
  // 接收 Native 端已注册的可共享状态的变化
  const colorScheme = useNativeState('colorScheme')

  return <div>Current Theme is {colorScheme}</div>
}

Web -> Native 通信方法

这种方法更加常用一些

import { networkModule } from 'mincu-react' // or mincu-network

const App = () => {
  // 已初始化
  
  const refreshToken = async () => {
    // 向 Native 通信，并获取 Native 端的返回值
    const token = await networkModule.refreshToken()
    alert(token)
  }

  return <button onClick={refreshToken}>刷新 token</button>
}

调试方法

为了方便在移动端 WebView 中调试，我们提供了 mincu-debug ，mincu-debug 采用了 Client/Server 模型，实现了各种在 WebView 中打 log，刷新页面，注入/取消注入 Devtool 等功能。（参考 react-native 的 HMRClient/Server）。

  • 安装 mincu-debug
npm i --save-dev mincu-debug # or yarn add -D mincu-debug
  • 在前端代码中引入 Client，通过 applyConsole 方法来重写默认的 console 事件，实现打印事件的绑定。建议只在 dev 环境中动态引入，避免增大 bundle 体积。
// 如果你使用 vite，则通过 import.meta.env.DEV 判断 DEV 环境。
if (process.env.NODE_ENV === 'development') {
  import('mincu-debug').then(({ default: debugModule }) => {
    debugModule.applyConsole()
  })
}
  • 启动 mincud Server，监听来自 Client 的打印事件：
npx mincud

推荐将 mincud 与前端 dev server 同时启动，不需要额外开启另外一个终端：

npx mincud npm run dev
// package.json
{
  "scripts": {
    "start": "mincud npm run dev",
    "dev": "vite --host",
    "build": "tsc && vite build",
    "serve": "vite preview"
  }
}

  • 执行命令 npm run start 后，mincud 将会启动并执行后面的 npm run dev 命令，然后对该命令执行的结果进行相应操作，对目标命令的输出结果匹配，匹配到 dev host（比如 http://localhost:8081）后将会打开一个二维码页面，这时打开南大家园，在生活 Tab，打开右上角 - 扫一扫页面进行扫描即可在南大家园内跳转到该页面进行开发。

  • mincud 启动后将会捕获终端输入事件，按 r 会尝试刷新页面，按 d 则会尝试切换（注入/取消注入）Devtool（eruda）

> Press "r" | Reload the client page
> Press "d" | Toggle the client devtool

完整的用法请看 example/vanilla-ts

其他说明

packages

  • mincu-core 核心逻辑部分，包含了常用的用户数据，提供 web 和 native 的双向通信、调用来自 App 的接口等功能。
  • mincu-data 数据部分，基本上来自于 core 里的 appData，不过加了一层初始化默认值处理。
  • mincu-debug 调试部分，包含了 mincud 和 debugModule，以方便在 WebView 中进行远程调试。
  • mincu-event 封装了一些原生操作函数，包括 openUrl, setShareConfig, showShare, login。
  • mincu-hooks 封装了一些适用于 react 的 hooks，包括 useAppReady, useNativeState, useSafeArea。
  • mincu-lib 共享库，包含了 constant 及 utils。
  • mincu-network 基于 axios 封装的网络库，主要增加了请求拦截器，刷新 token 等功能。
  • mincu-ui 封装了与原生界面显示有关的调用，包括 Toast, StatusBar Style, Header 标题栏, toScreen 跳转, exit 退出。
  • create-mincu mincu 模板生成 cli，开箱即用。

presets

  • mincu-vanilla 依赖了 mincu-core, mincu-data, mincu-event, mincu-network, mincu-ui
  • mincu-react 依赖了 mincu-vanilla, mincu-hooks

它们都可以单独地引入到你的项目中使用。你可以根据你的需求引入所需要的依赖。

使用到的项目