@gmcb/uv-ui 0.2.26 → 0.3.0

package/docs/api/index.md

@@ -0,0 +1,77 @@
+# API
+
+本页记录 `@gmcb/uv-ui` 的主要运行时入口。组件文档请查看 [组件](../components/index.md)，工具函数请查看 [工具](/api/utils/index.md)。
+
+## 默认导出
+
+```ts
+import uvUI from '@gmcb/uv-ui';
+```
+
+默认导出是 Vue 插件：
+
+```ts
+app.use(uvUI);
+```
+
+安装后会注册全局 mixin，并向 `uni.$uv` 注入工具、配置、请求实例和路由方法。
+
+## uni.$uv
+
+| 能力 | 说明 | 文档 |
+| --- | --- | --- |
+| `uni.$uv.http` | 基于 `luch-request` 的请求实例。 | [HTTP 请求](/api/request/http.md) |
+| `uni.$uv.route` | 路由跳转封装。 | [路由](/api/utils/route.md) |
+| `uni.$uv.config` | 内置配置对象。 | [扩展配置](../components/setting.md) |
+| `uni.$uv.debounce` / `uni.$uv.throttle` | 防抖与节流。 | [防抖节流](/api/utils/debounce.md) |
+| `uni.$uv.test` | 常用校验规则。 | [规则校验](/api/utils/test.md) |
+| `uni.$uv.timeFormat` / `uni.$uv.timeFrom` | 时间格式化。 | [时间](/api/utils/time.md) |
+| `uni.$uv.queryParams` | 对象转 URL 参数。 | [参数](/api/utils/queryParams.md) |
+| `uni.$uv.colorGradient` / `hexToRgb` / `rgbToHex` | 颜色工具。 | [颜色](/api/utils/colorSwitch.md) |
+| `uni.$uv.platform` | 平台判断。 | [快速使用](/api/utils/fastUse.md) |
+
+## 深度引用
+
+工具函数可以从包内 `libs` 路径按需引用：
+
+```ts
+import { trim, random } from '@gmcb/uv-ui/libs/function/test.js';
+import { timeFormat, queryParams } from '@gmcb/uv-ui/libs/function/index.js';
+import route from '@gmcb/uv-ui/libs/utils/route.js';
+import Request from '@gmcb/uv-ui/libs/luch-request/index.js';
+```
+
+深度引用路径依赖当前包结构，升级前应确认目标文件仍存在。
+
+## 样式入口
+
+```scss
+@import '@gmcb/uv-ui/theme.scss';
+@import '@gmcb/uv-ui/index.scss';
+```
+
+## 组件入口
+
+推荐通过 easycom 使用组件：
+
+```json
+{
+  "easycom": {
+    "autoscan": true,
+    "custom": {
+      "^uv-(.*)": "@gmcb/uv-ui/components/uv-$1/uv-$1.vue"
+    }
+  }
+}
+```
+
+确需手动引入时，按组件发布路径引用：
+
+```ts
+import UvButton from '@gmcb/uv-ui/components/uv-button/uv-button.vue';
+```
+
+## 注意
+
+- 当前文档统一使用 `utils` 作为工具分类，历史 `js` 路径不再保留。
+- 文档中的历史接入方式不作为本包推荐路径；当前统一使用 `@gmcb/uv-ui`。

package/docs/api/mixins/mpShare.md

@@ -0,0 +1,95 @@
+## mpShare 小程序分享
+
+`mpShare` 是对小程序 `onShareAppMessage`、`onShareTimeline` 生命周期的封装。开启后，uv-ui 会通过 mixin 给页面注入默认分享逻辑；如果页面需要自定义分享内容，也可以在页面中使用 uni-app 的组合式生命周期覆盖。
+
+### 开启分享
+
+在 `main.js` 注册插件时传入 `mpShare: true`：
+
+```js
+import App from './App';
+import { createSSRApp } from 'vue';
+import uvUI from '@gmcb/uv-ui';
+
+export function createApp() {
+	const app = createSSRApp(App);
+	app.use(uvUI, { mpShare: true });
+	return { app };
+}
+```
+
+### 全局分享配置
+
+```js
+uni.$uv.mpShare = {
+	title: '小程序名称',
+	path: '',
+	imageUrl: ''
+};
+```
+
+页面中可在 `onReady` 后修改当前分享信息：
+
+```vue
+<script setup>
+import { onReady } from '@dcloudio/uni-app';
+
+onReady(() => {
+	uni.$uv.mpShare.title = '对酒当歌，人生几何';
+	uni.$uv.mpShare.path = '/pages/index/index';
+});
+
+</script>
+```
+
+### 重写 onShareAppMessage
+
+```vue
+<script setup>
+import { onShareAppMessage } from '@dcloudio/uni-app';
+
+onShareAppMessage(res => {
+	if (res.from === 'button') {
+		console.log(res.target);
+	}
+
+	return {
+		title: '自定义分享标题',
+		path: '/pages/test/test?id=123'
+	};
+});
+
+</script>
+```
+
+### 分享到朋友圈
+
+```vue
+<script setup>
+import { onShareTimeline } from '@dcloudio/uni-app';
+
+onShareTimeline(() => {
+	return {
+		title: '自定义朋友圈标题',
+		query: 'id=123',
+		imageUrl: ''
+	};
+});
+
+</script>
+```
+
+### 取消分享
+
+单个页面可在生命周期中关闭：
+
+```vue
+<script setup>
+import { onLoad } from '@dcloudio/uni-app';
+
+onLoad(() => {
+	uni.$uv.mpShare = false;
+});
+
+</script>
+```

package/docs/api/request/apiManage.md

@@ -0,0 +1,88 @@
+## API集中管理
+
+这里说的集中管理，是指把各个请求，统一放到一个文件中进行管理，这样的好处是不用每次调用`uni.$uv.get`时都需要传入`url`参数，一些固定的
+请求参数也可以不用显式的传入，如下为配置后的使用示例：
+
+```
+uni.$uv.api.getSearch().then(res => {
+	console.log(res);
+})
+```
+
+### 前言
+
+在进行这个配置之前，建议先配置请求的拦截器，本示例和和拦截器是一脉相承的，请移步：[Http拦截器](/api/request/http.html)
+
+
+### 准备工作
+
+在根目录新建`/common/http.api.js`，如已有`common`目录，创建`http.api.js`即可。
+
+
+### 说明
+
+本文件的内部大体结构，和请求拦截器的内部结构基本一致。Vue 3 项目中建议导出普通初始化函数，在 `main.js` 的 `createApp` 中接收 `app` 后完成挂载，
+对各个参数的处理，在请求拦截器部分有关于内部各个参数的详细介绍，详见：[Http拦截器](/api/request/http.html)
+
+以下为`/common/http.api.js`的内部内容，说明都在注释中，请举一反三，灵活配置即可：
+
+```js
+// /common/http.api.js
+
+// 如果没有通过拦截器配置域名的话，可以在这里写上完整的URL(加上域名部分)
+let hotSearchUrl = '/ebapi/store_api/hot_search';
+let indexUrl = '/ebapi/public_api/index';
+
+// 此处 app 就是 createSSRApp(App) 创建出的应用实例，可以通过 app.config.globalProperties 挂载全局能力。
+// https://www.uvui.cn/api/request/http.html#%E4%BD%95%E8%B0%93%E8%AF%B7%E6%B1%82%E6%8B%A6%E6%88%AA%EF%BC%9F
+export function setupHttpApi(app) {
+	// 此处没有使用传入的params参数
+	const getSearch = (params = {}) => uni.$uv.http.get(hotSearchUrl, {
+		id: 2
+	});
+	
+	// 此处使用了传入的params参数，一切自定义即可
+	const getInfo = (params = {}) => uni.$uv.http.post(indexUrl, params);
+	
+	// 将各个定义的接口名称统一放进 uni.$uv.api 下，页面中可直接通过 uni.$uv.api 调用
+	uni.$uv.api = { getSearch, getInfo };
+	app.config.globalProperties.$api = uni.$uv.api;
+}
+```
+
+### 引入
+
+我们上面是创建和配置了`http.api.js`，接下来需要在`main.js`中进行挂载，如果您配置了拦截器，这部分的引入代码，需要写在拦截器引入的后面：
+
+```js
+import App from './App'
+import { createSSRApp } from 'vue'
+import uvUI from '@gmcb/uv-ui'
+import { setupHttpInterceptor } from '@/common/http.interceptor.js'
+import { setupHttpApi } from '@/common/http.api.js'
+
+export function createApp() {
+	const app = createSSRApp(App)
+	app.use(uvUI)
+	setupHttpInterceptor(app)
+	setupHttpApi(app)
+	return { app }
+}
+```
+
+
+### 使用
+
+经过以上配置后，我们可以在各个页面的js中方便的调用各个接口，如下示例：
+
+```js
+// 调用getSearch接口
+uni.$uv.api.getSearch().then(res => {
+	console.log(res);
+})
+
+// 调用getInfo接口
+uni.$uv.api.getInfo({id: 3}).then(res => {
+	console.log(res);
+})
+```