@gmcb/uv-ui 0.2.26 → 0.3.0

package/docs/guide/i18n.md

@@ -0,0 +1,194 @@
+## I18n 多语言切换
+
+本页示例面向 uni-app Vue 3 项目，使用 `vue-i18n@9` 与 `<script setup>`。
+
+### 安装
+
+```sh
+npm install vue-i18n
+```
+
+### 创建 i18n
+
+```js
+// locale/index.js
+import { createI18n } from 'vue-i18n';
+import zh from './zh.js';
+import en from './en.js';
+
+export const i18n = createI18n({
+	legacy: false,
+	locale: 'zh',
+	messages: {
+		zh,
+		en
+	}
+});
+```
+
+语言包示例：
+
+```js
+// locale/zh.js
+export default {
+	lang: {
+		title: 'uv-ui',
+		intro: '多平台快速开发的 UI 框架'
+	},
+	tabBar: {
+		index: '首页',
+		news: '消息',
+		center: '我的'
+	}
+};
+```
+
+在 `main.js` 中注册：
+
+```js
+import App from './App';
+import { createSSRApp } from 'vue';
+import uvUI from '@gmcb/uv-ui';
+import { i18n } from '@/locale';
+
+export function createApp() {
+	const app = createSSRApp(App);
+	app.use(uvUI);
+	app.use(i18n);
+	return { app };
+}
+```
+
+### 在页面中使用
+
+```vue
+<template>
+	<view style="margin-top: 200rpx;">
+		{{ t('lang.intro') }}
+	</view>
+</template>
+
+<script setup>
+import { onLoad } from '@dcloudio/uni-app';
+import { useI18n } from 'vue-i18n';
+
+const { t } = useI18n();
+
+onLoad(() => {
+	console.log(t('lang.intro'));
+});
+
+</script>
+```
+
+### 切换语言
+
+```vue
+<template>
+	<view style="margin-top: 200rpx;">
+		{{ t('lang.intro') }}
+		<uv-button @click="switchLang">切换语言</uv-button>
+	</view>
+</template>
+
+<script setup>
+import { useI18n } from 'vue-i18n';
+
+const { t, locale } = useI18n();
+
+function switchLang() {
+	locale.value = 'en';
+}
+
+</script>
+```
+
+### 响应式文本
+
+不要把翻译结果一次性写进普通变量。需要随语言切换更新的内容，使用 `computed`：
+
+```vue
+<template>
+	<view style="margin-top: 200rpx;">
+		{{ intro }}
+		<uv-button @click="switchLang">切换语言</uv-button>
+	</view>
+</template>
+
+<script setup>
+import { computed } from 'vue';
+import { useI18n } from 'vue-i18n';
+
+const { t, locale } = useI18n();
+const intro = computed(() => t('lang.intro'));
+
+function switchLang() {
+	locale.value = 'en';
+}
+
+</script>
+```
+
+### 设置导航栏标题
+
+原生导航栏标题不是模板绑定内容，需要在页面显示或语言切换后主动调用 `uni.setNavigationBarTitle()`。
+
+```vue
+<template>
+	<view style="margin-top: 200rpx;">
+		{{ t('lang.intro') }}
+		<uv-button @click="switchLang">切换语言</uv-button>
+	</view>
+</template>
+
+<script setup>
+import { onShow } from '@dcloudio/uni-app';
+import { useI18n } from 'vue-i18n';
+
+const { t, locale } = useI18n();
+
+function setTitle() {
+	uni.setNavigationBarTitle({
+		title: t('lang.title')
+	});
+}
+
+onShow(() => {
+	setTitle();
+});
+
+function switchLang() {
+	locale.value = 'en';
+	setTitle();
+}
+
+</script>
+```
+
+### 设置原生 TabBar 文案
+
+```vue
+<template>
+	<view style="margin-top: 200rpx;">
+		<uv-button @click="switchLang">切换语言</uv-button>
+	</view>
+</template>
+
+<script setup>
+import { useI18n } from 'vue-i18n';
+
+const { t, locale } = useI18n();
+
+function updateTabBar() {
+	uni.setTabBarItem({ index: 0, text: t('tabBar.index') });
+	uni.setTabBarItem({ index: 1, text: t('tabBar.news') });
+	uni.setTabBarItem({ index: 2, text: t('tabBar.center') });
+}
+
+function switchLang() {
+	locale.value = 'en';
+	updateTabBar();
+}
+
+</script>
+```

package/docs/guide/index.md

@@ -0,0 +1,28 @@
+# 指南
+
+本目录记录 `@gmcb/uv-ui` 的接入、主题、平台和开发约定。组件用法请查看 [组件](../components/index.md)，工具函数请查看 [工具](/api/utils/index.md)。
+
+## 接入
+
+| 文档 | 说明 |
+| --- | --- |
+| [演示](./demo.md) | 示例项目和演示说明。 |
+| [设计](./design.md) | 组件设计和平台适配约定。 |
+| [扩展配置](../components/setting.md) | 注册插件、启用 `uni.$uv`、配置主题和默认 props。 |
+| [代码提示](./codeHint.md) | 编辑器提示和类型辅助说明。 |
+
+## 样式与平台
+
+| 文档 | 说明 |
+| --- | --- |
+| [主题](./theme.md) | 主题变量、主题生成和样式覆盖。 |
+| [安全区](./safeAreaInset.md) | 安全区、底部占位和平台差异。 |
+| [自定义图标](./customIcon.md) | 接入 iconfont 或自定义图标。 |
+| [国际化](./i18n.md) | 多语言配置示例。 |
+| [注意事项](./note.md) | 常见使用约束和平台注意点。 |
+
+## 推荐阅读顺序
+
+1. 阅读 [文档首页](../index.md) 完成安装、注册和 easycom。
+2. 阅读 [扩展配置](../components/setting.md) 确认 `uni.$uv` 是否可用。
+3. 按需查看 [组件](../components/index.md) 和 [工具](/api/utils/index.md)。

package/docs/guide/note.md

@@ -0,0 +1,74 @@
+## 注意事项
+
+#### "$uv"被占用
+
+uv-ui 有很多自带的 js 工具函数，注册后可以通过 `uni.$uv` 使用，也会挂载到 Vue 3 的 `app.config.globalProperties.$uv`，所以请勿占用 `$uv` 变量名或重复挂载同名全局属性。
+
+
+#### uv-ui对nvue的支持
+
+什么是`nvue`？见[关于nvue](/guide/design.html#关于nvue)  
+
+uv-ui 面向 uni-app Vue 3、app-vue、app-nvue、h5、小程序等多端场景，支持单独导入，开箱即用。
+
+#### 对VUE3的支持
+
+uv-ui全面支持`VUE3`。
+
+
+#### 技术点要求
+
+1. uv-ui依赖`SCSS`预处理器，所以您需要给HBuilder X安装 “sass/scss编译” 插件，详见[sass/scss编译](https://ext.dcloud.net.cn/plugin?id=2046)
+2. uv-ui基于HX的最新版本开发，旧版本可能会不兼容，如遇问题，请升级HX尝试是否可解决
+3. uv-ui要求项目开启uniapp的V3版本，V3有很大的优势，详见[V3版本介绍](https://ask.dcloud.net.cn/article/36599)
+4. HX2.5.5稳定版正式引入`easycom`，建议开发者升级HX到2.5.1及以上的稳定版，详见[关于easycom](/components/quickstart.html#_3-配置easycom组件模式)
+
+
+#### 关于Hbuilder X
+
+uniapp依赖于HX，uniapp经过这两年发展(2018-2020)，势头强劲，茁壮成长。我们目睹了整个过程，陪着uniapp一起成长，感慨能有
+一家良心企业能扎根技术，埋头苦干，把APP，H5还有各家小程序做到大一统，同时也愤慨各家大厂的小程序各自为营，仿佛倒退到多年前
+各家[浏览器大战](https://baike.baidu.com/item/%E6%B5%8F%E8%A7%88%E5%99%A8%E5%A4%A7%E6%88%98/8488119?fr=aladdin)的时代，让人唏嘘不已。  
+根据我们的经验，我们强烈建议:
+- 开发者在开发线上项目的时候只使用HX的稳定版
+- 初学者不要使用HX内测版，不然会碰到莫名其妙的问题，会挫败学习信心
+- 每当HX更新大功能的时候，比如以往的自定义组件模式，近来的V3版本，还是目前的uniCloud，或者以后可能关于nuve的大功能，线上项目请过一段时间再使用。
+- 建议喜欢尝鲜并熟悉uniapp的用户，在电脑分别安装HX的稳定版和内测版，尝鲜使用内测版，开发使用稳定版，二者分别更新，互不干扰
+
+
+#### 编译调试
+
+开发的时候，特别是写布局的时候，我们建议使用chrome或者HX内置的浏览器，需要说明的是，电脑浏览器的预览效果是不精细的，
+写完之后，可以手机连上电脑同一局域网的WiFi，在手机浏览器上再进行细微的调整。  
+写完布局再写逻辑的时候，如果还需要兼容小程序和APP，一定要每写完一个页面，就用APP基座和小程序真机进行调试，这能及早发现问题，否则会剪不断理还乱。  
+
+
+#### 内网穿透
+
+有时候需要通过花生壳等工具，进行内网穿透，让外部的人可以访问到本地的调试网页，这时由于`webpack-dev-server`会默认检查`hostname`，
+去掉此限制即可，在uniapp项目根目录下新建`vue.config.js`文件(如果有，不用创建)，修改如下内容：
+
+```js
+module.exports = {
+	configureWebpack: {
+		devServer: {
+			disableHostCheck: true
+		}
+	}
+}
+```
+
+#### 安全区适配(针对APP)
+
+在iPhone X等机型，底部带有指示条，如果配置了`safearea`则会在底部生成一个原生的白色区块，好处是不会导致
+误触，缺点是颜色无法修改，有时候也影响美观。  
+uv-ui在各个可能会受到指示条影响的地方都做了特别处理，比如弹窗，键盘组件等，详见[底部安全区适配](/guide/safeAreaInset.html)
+
+
+
+#### 为什么uv-ui的源码中会有那么多的注释？
+
+很多开源项目，发布的时候都会刻意去掉注释，这可能是为了干净整洁，也可能是为了减少体积，还可能是出品方认为用户不会，也没必要去阅读源码。  
+相反，uv-ui不这么认为，我们会一直将注释保留在发行的版本中，这些注释不是为了给我们自己看的，而是为了给用户看的。  
+我们希望用户在使用的过程中，能通过阅读源码，既能提升工作效率，还能学到知识。因为uv-ui的理念是"挣脱束缚，向往自由"，我们也希望您在阅读
+源码的过程中，如果发现问题，或者有更好的实现方式和想法，可以反馈给我们，进而构建一个更强健的UI框架。

package/docs/guide/safeAreaInset.md

@@ -0,0 +1,64 @@
+## 安全区适配
+
+### 底部安全区
+这个适配，主要是针对IPhone X等一些底部带指示条的机型，指示条的操作区域与页面底部存在重合，容易导致用户误操作，因此我们需要针对这些机型进行底部安全区适配。  
+uv-ui是uni-app态的UI框架uni-app专门针对底部安全区域的解决方案，具体如下(也可见uni官方说明[全面屏、刘海屏适配（iphoneX适配）及安全区设置](https://ask.dcloud.net.cn/article/35564))：
+- 在APP上(以下只对APP生效)，可以通过项目根目录的`mainfest.json`文件`app-plus`节点下配置`safearea`的`bottom`属性为`none`，以此来关闭IPhone X等机型的底部安全区域。
+配置后需要重新编译，并重启调试基座才会生效，具体如下：
+
+``` json
+"app-plus": {
+	"safearea": {
+		"bottom": {
+			"offset": "none"
+		}
+	}
+}
+```
+如果`offset`设置为`auto`，那么在IPhone X的底部安全区，APP上就会生成一个原生的元素进行占位，此时也就无需解决安全区指示条引起的问题。
+
+- 在非APP端，诸如小程序，或者微信浏览器(其他浏览器，如UC等手机浏览器，底部有浏览器工具条，不存在安全区指示条引起的问题)，底部是没有安全区占位的，
+这种情况，就要使用css去解决，一般是通过给元素添加底部内边距的形式，如下：
+
+``` html 
+<style>  
+	.list {  
+		padding-bottom: 0;  
+		padding-bottom: constant(safe-area-inset-bottom);  
+		padding-bottom: env(safe-area-inset-bottom);  
+	}  
+</style>
+```
+
+鉴于以上问题，uv-ui提供了一个组件`uv-safe-bottom`，如果有需要，您可以在任何地方引用它，它会自动判断在并且在IPhone X等机型的时候，给元素加上一个适当
+底部内边距，在APP上，即使您保留了原生安全区占位(`offset`设置为`auto`)，也不会导致底部出现双倍的空白区域，也即APP上`offset`设置为`auto`时。
+``` html 
+<template>
+	<view>
+		......
+		<uv-safe-bottom></uv-safe-bottom>
+	</view>
+</template>
+```
+
+### 顶部安全区
+
+由于我们在做页面布局时经常会使用顶部位置，uv-ui提供了一个组件`uv-status-bar`，如`uv-popup`从顶部弹出时，可以考虑使用此组件。
+``` html 
+<template>
+	<view>
+		<uv-status-bar></uv-status-bar>
+		......
+	</view>
+</template>
+```
+
+### 关于uv-ui某些组件`safe-area-inset`参数的说明
+
+在uv-ui中，一些组件如`uv-popup`、`uv-keyboard`组件等，提供了一个`safeAreaInsetBottom`参数(布尔类型)，如果设置为`true`，就会在组件内部对安全区进行适配，
+从而避免安全区指示条引起的问题，以下为uv-ui的`uv-keyboard`组件在`微信浏览器`中分别设置`safeAreaInsetBottom`参数
+为`false`和`true`的表现：
+
+<div>
+	<img src="https://www.uvui.cn/common/keyboard.png" alt="uv-ui" class="logo">
+</div>

package/docs/guide/theme.md

@@ -0,0 +1,67 @@
+# 自定义主题
+
+`@gmcb/uv-ui` 的主题由 SCSS 变量和运行时配置共同组成。项目接入时推荐在统一样式入口维护主题变量，避免在业务页面中分散覆盖。
+
+## 引入主题变量
+
+在 `uni.scss` 或项目主题入口引入：
+
+```scss
+@import '@gmcb/uv-ui/theme.scss';
+```
+
+如需覆盖主题变量，请在自己的主题文件中保持变量名一致，并确保覆盖文件在组件样式生效前被加载。
+
+```scss
+@import '@gmcb/uv-ui/theme.scss';
+@import '@/styles/theme.scss';
+```
+
+## 常用变量
+
+```scss
+$uv-main-color: #303133;
+$uv-content-color: #606266;
+$uv-tips-color: #909193;
+$uv-light-color: #c0c4cc;
+$uv-border-color: #dadbde;
+$uv-bg-color: #f3f4f6;
+$uv-disabled-color: #c8c9cc;
+
+$uv-primary: #3c9cff;
+$uv-success: #5ac725;
+$uv-warning: #f9ae3d;
+$uv-error: #f56c6c;
+$uv-info: #909399;
+```
+
+## 基础样式
+
+在 `App.vue` 或全局样式入口引入基础样式：
+
+```scss
+@import '@gmcb/uv-ui/index.scss';
+```
+
+基础样式包含常用工具类和组件共享样式，例如 `uv-line-1`、`uv-border`、`uv-border-top`、`uv-hover-class`。
+
+## 运行时配置
+
+插件注册后可以通过 `uni.$uv.setConfig` 调整默认配置和组件 props：
+
+```ts
+uni.$uv.setConfig({
+  config: {
+    unit: 'rpx',
+  },
+  props: {
+    text: {
+      color: {
+        default: '#303133',
+      },
+    },
+  },
+});
+```
+
+`setConfig` 需要在 `app.use(uvUI)` 之后调用。详见 [扩展配置](../components/setting.md)。

package/docs/index.md

@@ -0,0 +1,88 @@
+# @gmcb/uv-ui
+
+`@gmcb/uv-ui` 是基于 uv-ui 的 uni-app 多端 UI 组件包，包含 `uv-*` 组件、主题样式、工具函数、请求实例和 `$uv` 全局能力。
+
+## 快速入口
+
+| 入口 | 说明 |
+| --- | --- |
+| [指南](./guide/index.md) | 安装注册、主题、安全区、国际化、自定义图标和开发约定。 |
+| [组件](./components/index.md) | 查看组件分类、easycom 配置和常用 `uv-*` 组件。 |
+| [API](./api/index.md) | 查看默认导出、`uni.$uv`、请求、路由、配置和深度引用路径。 |
+| [工具](/api/utils/index.md) | 查看格式化、校验、路由、防抖节流等工具。 |
+| [常见问题](./faq/index.md) | 排查 easycom、样式、`uni.$uv`、请求和平台兼容问题。 |
+
+## 安装
+
+```bash
+npm i @gmcb/uv-ui
+```
+
+## 注册
+
+```ts
+import { createSSRApp } from 'vue';
+import uvUI from '@gmcb/uv-ui';
+import App from './App.vue';
+
+export function createApp() {
+  const app = createSSRApp(App);
+  app.use(uvUI);
+  return {
+    app,
+  };
+}
+```
+
+注册后可以通过 `uni.$uv` 使用工具和请求实例，也可以在组件实例中访问 `$uv`。
+
+## easycom
+
+```json
+{
+  "easycom": {
+    "autoscan": true,
+    "custom": {
+      "^uv-(.*)": "@gmcb/uv-ui/components/uv-$1/uv-$1.vue"
+    }
+  }
+}
+```
+
+配置后可直接在页面中使用组件：
+
+```vue
+<template>
+  <uv-button type="primary">提交</uv-button>
+  <uv-icon name="search" size="24" />
+</template>
+```
+
+## 样式
+
+在 `uni.scss` 或项目统一样式入口引入主题变量：
+
+```scss
+@import '@gmcb/uv-ui/theme.scss';
+```
+
+在 `App.vue` 或全局样式入口引入基础样式：
+
+```scss
+@import '@gmcb/uv-ui/index.scss';
+```
+
+## 文档结构
+
+| 分类 | 文档 |
+| --- | --- |
+| 指南 | [指南总览](./guide/index.md)、[主题](./guide/theme.md)、[安全区](./guide/safeAreaInset.md)、[国际化](./guide/i18n.md) |
+| 组件 | [组件总览](./components/index.md)、[安装](./components/install.md)、[扩展配置](./components/setting.md)、[常见问题](./components/problem.md) |
+| API | [API 总览](./api/index.md)、[工具总览](/api/utils/index.md)、[HTTP 请求](/api/request/http.md)、[路由](/api/utils/route.md) |
+| 常见问题 | [FAQ](./faq/index.md) |
+
+## 使用约定
+
+- 当前包名统一使用 `@gmcb/uv-ui`，文档中的旧包名或 `uni_modules` 示例不作为本包推荐接入方式。
+- 工具文档归入 `api/utils`，请求、混入和配置类 API 拆分到 API 下对应分组；历史 `js` 分类不再保留。
+- 深度引用依赖包内发布路径，例如 `@gmcb/uv-ui/libs/function/index.js`。

package/libs/config/config.js

@@ -1,14 +1,4 @@
-// 此版本发布于2024-01-24
-const version = '1.1.20';
-
-// 开发环境才提示，生产环境不会提示
-if (process.env.NODE_ENV === 'development') {
-	console.log(`\n %c uvui V${version} https://www.uvui.cn/ \n\n`, 'color: #ffffff; background: #3c9cff; padding:5px 0; border-radius: 5px;');
-}
-
 export default {
-    v: version,
-    version,
     // 主题名称
     type: [
         'primary',

package/libs/css/color.scss

@@ -1,27 +1,28 @@
-$uv-main-color: #303133 !default;
-$uv-content-color: #606266 !default;
-$uv-tips-color: #909193 !default;
+$uv-main-color: #333333 !default;
+$uv-content-color: #7a7a7a !default;
+$uv-tips-color: #9a9a9a !default;
 $uv-light-color: #c0c4cc !default;
-$uv-border-color: #dadbde !default;
-$uv-bg-color: #f3f4f6 !default;
+$uv-border-color: #eeeeee !default;
+$uv-bg-color: #f5f5f5 !default;
+$uv-bg-light-color: #fffbf4 !default;
 $uv-disabled-color: #c8c9cc !default;
 
-$uv-primary: #3c9cff !default;
-$uv-primary-dark: #398ade !default;
-$uv-primary-disabled: #9acafc !default;
-$uv-primary-light: #ecf5ff !default;
+$uv-primary: #00b4c3 !default;
+$uv-primary-dark: #157572 !default;
+$uv-primary-disabled: #b4e3d9 !default;
+$uv-primary-light: #dff3f9 !default;
 
-$uv-warning: #f9ae3d !default;
-$uv-warning-dark: #f1a532 !default;
+$uv-warning: #ff9a05 !default;
+$uv-warning-dark: #ed6c04 !default;
 $uv-warning-disabled: #f9d39b !default;
 $uv-warning-light: #fdf6ec !default;
 
 $uv-success: #5ac725 !default;
 $uv-success-dark: #53c21d !default;
 $uv-success-disabled: #a9e08f !default;
-$uv-success-light: #f5fff0;
+$uv-success-light: #f5fff0 !default;
 
-$uv-error: #f56c6c !default;
+$uv-error: #ff4d4f !default;
 $uv-error-dark: #e45656 !default;
 $uv-error-disabled: #f7b2b2 !default;
 $uv-error-light: #fef0f0 !default;
@@ -29,4 +30,4 @@ $uv-error-light: #fef0f0 !default;
 $uv-info: #909399 !default;
 $uv-info-dark: #767a82 !default;
 $uv-info-disabled: #c4c6c9 !default;
-$uv-info-light: #f4f4f5 !default;
+$uv-info-light: #f4f4f5 !default;

package/package.json

@@ -1,9 +1,13 @@
 {
 	"name": "@gmcb/uv-ui",
-	"version": "0.2.26",
+	"version": "0.3.0",
 	"description": "uv-ui 破釜沉舟之兼容vue3+2、nvue、app、h5、小程序等多端基于uni-app和uView2.x的生态框架，支持单独导入，开箱即用，利剑出击。",
 	"main": "index.js",
 	"homepage": "https://git.keeprisk.cn/gmcb/front-end/tree/master/packages/uv-ui",
+	"scripts": {
+		"docs:dev": "vitepress dev . --config .vitepress/config.mts",
+		"docs:build": "vitepress build . --config .vitepress/config.mts"
+	},
 	"publishConfig": {
 		"access": "public"
 	},
@@ -17,6 +21,7 @@
 	"author": "yinjiazeng@163.com",
 	"license": "MIT",
 	"files": [
+		"docs",
 		"libs",
 		"components",
 		"CHANGELOG.md",
@@ -24,5 +29,5 @@
 		"index.scss",
 		"theme.scss"
 	],
-	"gitHead": "295849adc75d0a7f7197f2ff4d8264b3cce8b913"
+	"gitHead": "0b5311c299e38de9caf076ec3a5fede4525b2484"
 }

package/theme.scss

@@ -8,7 +8,8 @@ $uv-tips-color: #909193;
 $uv-light-color: #c0c4cc;
 $uv-border-color: #dadbde;
 $uv-bg-color: #f3f4f6;
-$uv-disabled-color: #c8c9cc;
+$uv-bg-light-color: #fffbf4;
+$uv-disabled-color: #c8c9cc;
 
 $uv-primary: #3c9cff;
 $uv-primary-dark: #398ade;