@gmcb/uv-ui 0.2.26 → 0.3.0

package/docs/guide/codeHint.md

@@ -0,0 +1,44 @@
+## HBuilder X对uv-ui的代码提示
+
+<!-- <demo-model url="/"></demo-model> -->
+
+uv-ui发布一周后，	迅速适配了HX的代码提示功能，让用户可以更简单，畅快的使用uv-ui的组件，这个提示功能有如下特色：
+
+- 通过敲`<u`关键字(无需`<uv-`后面的`-`)，HX会通过弹出提示列出uv-ui的所有组件
+- 可以在提示中一键直达对应组件的官方文档
+- 提示中有完整的参数类型、	说明，事件描述等提示
+- 无需给HX安装插件和设置，即可拥有以上提示功能
+
+
+### 触发提示
+
+在"*.vue"文件的模板编写区域，通过`<u`开头的关键字，就能	触发uv-ui的组件候选列表：
+- 如果想得到更准确的提示，可以完整敲出组件名称，如`<uv-badge`就会弹出唯一的提示，此时回车即可键入。
+- 如果对某一个组件的名称记忆不清，可凭借大概的字符输入，HX会按模糊搜索的方式进行匹配可能的组件选项，比如`uv-alert-tips`组件，我们可以敲`<uv-altip`，
+`<uv-tips`，或者`<uv-aler`等等，都可识别出组件的提示，总的来说，以`<u`，开头，后面可以是组件的部分关键字，前中后部分都可，大家可自行尝试。
+
+<img src="https://www.uvui.cn/code_hint/1.png"/>
+
+<br><br>
+
+### 一键在浏览器打开组件对应文档
+
+当我们在HX匹配到某个组件后，提示框的右边会弹出此组件所在的文档地址，通过鼠标点击，即可在浏览器快速打开对应的文档。
+
+<img src="https://www.uvui.cn/code_hint/2.png"/>
+
+<br><br>
+
+### 参数提示
+
+当我们键入完整的组件结构后，通过`:`开头，即可列出组件的参数，右边有对应的类型和说明提示，还可以通过模糊的匹配的方式(敲出参数名称的部分字符)，快速找到某一个参数。
+
+<img src="https://www.uvui.cn/code_hint/3.png"/>
+
+<br><br>
+
+### 事件提示
+
+某些组件有回调事件，通过`@`开头，即可列出对应的事件名称，右边有事件对应的说明，回车即可自动键入。
+
+<img src="https://www.uvui.cn/code_hint/4.png"/>

package/docs/guide/customIcon.md

@@ -0,0 +1,168 @@
+## 目录
+
+- [vue中自定义图标库](/guide/customIcon.html#基础说明)
+- [nvue中自定义图标库](/guide/customIcon.html#nvue中自定义图标库)
+
+## CustomIcon 扩展自定义图标库
+
+<!-- <demo-model url="/pages/componentsA/icon/index"></demo-model> -->
+<br>
+
+::: danger 注意
+`nvue`页面暂时不支持自定义图标，如需在 nvue 中使用 ，请自行引入字体文件，[具体方法在最下方](/guide/customIcon.html#nvue中自定义图标库)。
+
+:::
+
+uv-ui已通过大量的实践中，收集了用户最有可能需要用到的图标，见[Icon 图标](/components/icon.html)，但我们也相信，它肯定无法覆盖所有的场景和需求。  
+
+用户也可以使用标签的方式，自行引入字体图标，为何要通过扩展的方式集成呢？  
+这是因为uv-ui有统一的字体图标组件，使用方便，配置灵活，且风格统一。
+
+:::tip 说明
+以下说明和演示，均针对[阿里字体图标库](https://www.iconfont.cn)，其他字体库源同理
+:::
+
+总的来说，我们要实现的效果如下：
+
+```css
+@font-face {
+	/* 声明"custom-icon"字体 */
+	font-family: "custom-icon";
+	src: url('data:application/x-font-woff2;charset=utf-8;base64,xxxxxxxx') format('woff2');
+}
+
+.custom-icon {
+	/* 引用上面声明的"custom-icon"字体 */
+	font-family: "custom-icon" !important;
+	font-size: 16px;
+	font-style: normal;
+	-webkit-font-smoothing: antialiased;
+	-moz-osx-font-smoothing: grayscale;
+}
+
+/* 字体图标的前缀为"custom-icon-" */
+.custom-icon-copy:before {
+  content: "\e641";
+}
+```
+
+通过如下方式引用：  
+
+通过`custom-prefix`指定类名为`custom-icon`
+
+```vue
+<uv-icon name="copy" custom-prefix="custom-icon"></uv-icon>
+```
+
+### 基础说明
+
+我们假定您一个项目中，需要扩展多个图标，所以您应该把各个图标收集进一个阿里图标库的项目中，即使您后面不断的扩展图标，也能让它们在同一个库中。
+
+一般情况下，我们建议您在收藏的项目中，使用"下载至本地"的功能，而后解压，复制文件夹中的"iconfont.css"至uni-app目中(其余的文件可忽略)
+
+下面的操作默认您已进入阿里图标库的"图标管理"栏目中
+
+1. 我们建议，您应该修改这个图标的前缀，这样以后有新图标加入的时候，不用每次频繁修改前缀，在右上角的"项目设置"，进入"编辑项目"：
+
+<img src="https://www.uvui.cn/custom_icon/custom_icon_3.png" />
+
+
+2. 修改"FontClass/Symbol 前缀"项为"custom-icon-"，修改"Font Family"为"custom-icon"，如下图：
+
+<img src="https://www.uvui.cn/custom_icon/custom_icon_4.png" />
+
+
+3. 下载项目至本地
+
+<img src="https://www.uvui.cn/custom_icon/custom_icon_1.png" />
+
+4. 复制"iconfont.css"至项目，一般放在根目录的`static`文件夹下
+
+<img src="https://www.uvui.cn/custom_icon/custom_icon_2.png" />
+
+5. 复制"iconfont.css"文件到uni-app目根目录的`static`目录后(也可以为其他目录)，打开"iconfont.css"，内部如下：
+
+**删掉下图圈出的部分，记得把"src: url('data:application/x-font-woff2......"最后的逗号`,`改成分号`;`。**
+
+<img src="https://www.uvui.cn/custom_icon/custom_icon_8.png" />
+
+6. **最终如下图：这行比较长，一定要将末尾的逗号变成了分号。==================》很重要，由于文本较长，可能忽略**
+
+<img src="https://www.uvui.cn/custom_icon/custom_icon_9.png" />
+
+
+7. 在项目根目录的"App.vue"中，引入上述的"iconfont.css"，注意自己存放的路径，且通过"@import"引入的外部样式，为了兼容性建议使用相对路径，
+且引入的样式，需要写在`style`标签有效内容中的最前面，如下：
+
+```css
+/* App.vue */
+<style>
+/* 此处为style标签里面的最上面 */
+@import "@/static/iconfont.css";
+...
+</style>
+```
+
+8. 在页面通过uv-ui的[Icon](/components/icon.html)组件使用图标，图标名称为您在阿里图标库中点击"编辑图标"时的"Font Class / Symbol"(该值可修改，每次修改都需重新下载"iconfont.css"放到uni-app目中，
+覆盖原来的"iconfont.css")
+
+<img src="https://www.uvui.cn/custom_icon/custom_icon_7.png" />
+
+如上图，我们得到"backspace"值，使用如下：
+
+```vue
+<uv-icon name="backspace" custom-prefix="custom-icon" size="30" color="#888888"></uv-icon>
+```
+
+从上可以看出，相比uv-ui内置的图标使用，多了一句固定的`custom-prefix="custom-icon"`，其余使用方法完全相同
+<br><br>
+
+**注意**：执行完上面的操作后，您就可以随心所欲的扩展自己的图标了，最重要的是第二步，修改了它，就免了以后每次都要修改"iconfont.css"的多处细节。
+当然，每次新增图标，当您把"iconfont.css"复制至项目中覆盖原来的"iconfont.css"后，都需要执行一遍第5步删掉多余的内容，别忘了修改最后的`,`为`;`。 
+
+最后提一下，为了多平台兼容性，您应该仅把单色图标添加到阿里图标库的项目中，即使添加了多色的图标，在使用中，也会被转成单色。
+
+祝您使用愉快！
+
+## NVUE中自定义图标库
+
+在项目实战中使用了`uv-ui`的图标库，如果图标不够用需要自定义，上述vue中自定义图标比较简单，在nvue中自定义图标有所不同，下面是详细步骤：
+
+1. 将/uni_modules/uv-icon/components下面的uv-icon**复制一份**放到项目根目录components文件下，并命名成其他名称，例如：custom-icon
+
+<img src="https://www.uvui.cn/custom_icon/custom_icon_nvue_1.png" style="width:40%;"/>
+
+2. 下载iconfont，注意项目设置的Font Family要与后面修改的必须一致，在这里我们就修改成`custom-icon`。
+
+<img src="https://www.uvui.cn/custom_icon/custom_icon_nvue_2.png" style="width:60%;" />
+
+3. 删除一起复制过来的icons.js、uvicons.ttf，将下载的iconfont.ttf放入custom-icon目录下，然后替换ttf地址：
+
+<img src="https://www.uvui.cn/custom_icon/custom_icon_nvue_3.png" style="width:60%;" />
+
+4. 将该文件中的46行、194行的uvicon-iconfont均修改成custom-icon（因为我们在第2步中设置的custom-icon）。
+
+<img src="https://www.uvui.cn/custom_icon/custom_icon_nvue_4.png" style="width:60%;" />
+<img src="https://www.uvui.cn/custom_icon/custom_icon_nvue_5.png" style="width:60%;" />
+
+5. 将51行`import icons from './icons'`代码删除或者注释，然后将136行代码改成`const code = null`。
+
+<img src="https://www.uvui.cn/custom_icon/custom_icon_nvue_6.png" style="width:60%;" />
+<img src="https://www.uvui.cn/custom_icon/custom_icon_nvue_7.png" style="width:60%;" />
+
+6. 最后就是使用图标，`name`属性需要传入unicode码，如下：
+
+```vue
+<custom-icon name="e897"></custom-icon>
+```
+
+### nvue自定义图标工程化包
+
+上述方法可能对于很多小伙伴不好实现，会遇到问题，作者直接把做好的包放到了git上面了，直接拉取下来放到自己项目就可以使用：[https://gitee.com/climblee/uv-custom-icon.git
+](https://gitee.com/climblee/uv-custom-icon.git)
+
+但是字体图标下载之前需要做相应的设置，如下：
+
+**Tips：**
+- 按照上面的第2步骤，将FontClass/Symbol 前缀改成：uv-custom-icon-，将Font Family改成：uv-custom-icon
+- 组件里面引入图标的路径是`@/static/iconfont.ttf`，所以你只需要下载自己的字体图标`iconfont.ttf`文件放到相应目录下就好了。

package/docs/guide/demo.md

@@ -0,0 +1,92 @@
+## 演示
+
+uv-ui会将各个版本的演示在此展示，目前演示的版本有H5，其他版本的演示将会陆续添加。  
+
+### 使用方法
+
+- H5版本可以用微信或者手机浏览器扫描二维码即可
+<!-- - 微信小程序只能通过微信扫码查看 -->
+<!-- - 安卓版本只能在安卓使用，可以用安卓浏览器或者QQ扫码进行安装(**微信中不能扫码安装**)，安装过程中您可能需要勾选相应的提示，允许安装来自非应用市场的APP，或者您需要在`设置`中打开
+[允许安装来自未知来源的应用](https://www.pc841.com/shoujijiqiao/45848.html) -->
+
+### 说明
+
+文档中也有相应的演示示例，但它是通过`iframe`嵌入到网页，所以可能会造成某些uni-app API在网页上(浏览器F12手机调试模式无问题)无法使用，造成组件有BUG的错觉。  
+
+**注意：** 建议您只在浏览文档时使用文档右侧的演示功能，电脑示例由于分辨率和uni-app用`rpx`单位的问题，显示可能会不够细致<!-- ，请通过微信扫码小程序体验最佳的效果 -->。
+
+
+### 扫码
+
+<div class="demo-wrap row">
+	<div class="col-md-3 col-sm-6 col-xs-12">
+		<div class="demo-item">
+			<img src="https://www.uvui.cn/common/wx.png" />
+			<div class="platform-name">
+				微信小程序
+				<p class="platform-tips">只能微信扫码</p>
+			</div>
+		</div>
+	</div>
+	<div class="col-md-3 col-sm-6 col-xs-12">
+		<div class="demo-item">
+			<img src="https://www.uvui.cn/common/h5.png" />
+			<div class="platform-name">
+				H5
+				<p class="platform-tips">微信或浏览器扫码</p>
+			</div>
+		</div>
+	</div>
+	<div class="col-md-3 col-sm-6 col-xs-12">
+		<div class="demo-item">
+			<img src="https://www.uvui.cn/common/app.png" />
+			<div class="platform-name">
+				安卓
+				<p class="platform-tips">浏览器扫码安装(微信扫码无效)</p>
+			</div>
+		</div>
+	</div>
+</div>
+
+
+<style scoped>
+	.demo-item {
+		text-align: center;
+		border: 1px solid #eaeefb;
+		border-radius: 5px;
+		-webkit-transition: bottom 0.4s;
+		transition: bottom 0.4s;
+		position: relative;
+		bottom: 0;
+		margin: 1.5rem;
+		padding: 2rem 0;
+	}
+	
+	.demo-item:hover {
+	    bottom: 6px;
+	    box-shadow: 0 6px 18px 0 rgba(232, 237, 250, .5);
+	}
+	
+	.demo-item img {
+		width: 160px;
+		margin: auto;
+	}
+	
+	.demo-item .platform-name {
+		color: #606266;
+		font-size: 18px;
+		position: relative;
+		margin: 20px 0;
+	}
+	
+	.demo-item .platform-tips {
+		text-align: center;
+		position: absolute;
+		font-size: 14px;
+		bottom: -50px;
+		left: auto;
+		width: 100%;
+		right: auto;
+		color: #909399;
+	}
+</style>

package/docs/guide/design.md

@@ -0,0 +1,56 @@
+## 设计理念
+
+#### 导航栏
+
+uniapp可以通过配置`pages.json`生成原生元素的导航栏，简要说明如下：
+- 优点是可以快速渲染，配置便捷，还可以带入一部分原生内容(针对App Store)
+- 缺点是配置不够灵活，遮罩无法覆盖导航栏等
+
+建议：
+- 如果开发者使用nvue，可以直接自定义导航栏，无需使用uniapp自带的
+- 如果是普通的vue页面，直接使用uniapp自带导航栏。如果自带的不能满足，条件允许就用`subNVue`绘制，否则就用普通元素绘制
+
+说明：uni官方有关于导航栏的详细说明，请参见[自定义导航栏](https://uniapp.dcloud.io/collocation/pages?id=customnav)
+
+
+#### 关于nvue
+
+nvue源自于uniapp引入的阿里weex开源原生渲染引擎，单weex来说，是不推荐使用的，因为它没有周边的生态和第三方的功能。  
+uniapp引入weex之后，一直在整合，但也没有对weex进行定制开发，在APP端某些需要性能相关的可以使用nvue，以下是我们对nvue的一些见解：
+- nvue具有媲美`react native`的性能，uniapp一直在打通vue和nvue的壁垒
+- nvue页面中还不能像写vue一样便利，比如对样式的限制，api还不能和vue完全互通等
+
+建议：uniapp一直在强化vue，重心不在nvue，如果不是特别复杂的应用，可以直接使用vue开发，应用的首页(V3版本)使用`nvue`，渲染的速度会有显著的提升，
+如果有需要进一步了解，请参见[nvue开发与vue开发的常见区别](https://uniapp.dcloud.io/use-weex?id=nvue开发与vue开发的常见区别)
+
+
+#### 关于单位
+
+我们在web中，常用的是`px`，`rem`等单位，`rem`在uniapp中不推荐使用，我们分别做如下阐述：  
+
+web中：
+可以使用`px`，它属于静态单位，它的最终呈现尺寸不会和屏幕尺寸有关系  
+
+uniapp中(vue和nvue)：  
+`px`属于静态单位，uni中还有`upx`和`rpx`单位，`upx`为uniapp成立之初的动态单位，后来各家小程序跟随微信小程序，都使用
+`rpx`单位，使它成为了既定的事实标准，uniapp也就提倡并官宣使用`rpx`单位，但是`upx`也一样能使用，和`rpx`效果相同。  
+另外：uniapp，vh和vw也完全可以使用的，一般我们需要让某个元素高度铺满整个屏幕时，可以设置高度为`100vh`。  
+
+weex中：
+这里说的是阿里的weex，而不是uniapp改良后的nvue版本中的weex，它的`px`单位和uniapp中的`rpx`或者`upx`是一样的，也属于
+动态单位，它自创了个`wx`单位，和web中的`px`一样，属于静态单位。  
+说明：uniapp的nvue版本中，虽然也是引入weex，但是改良后，没有了`wx`，`nvue`的`rpx`(`upx`)与`px`和uniapp的vue版本单位效果一致。  
+
+建议：开发中，只需谨记两个单位，`px`和`rpx`，一般情况下，我们推荐字体和宽高等，都使用`rpx`单位，如果真的需要固定尺寸，就是用`px`。
+如果关于各单位和他们的由来历史，还需要进一步了解，可以参见[尺寸单位](https://uniapp.dcloud.io/frame?id=尺寸单位)
+
+
+#### 布局
+
+为兼容多端运行，我们建议开发者使用`flex`，不要使用`float`布局。移动端使用`flex`是没有顾虑的，而`flex`布局，可以达到事半功倍的效果。  
+如果不熟悉`flex`，可以参考[阮一峰的flex教程](http://www.ruanyifeng.com/blog/2015/07/flex-grammar.html)
+
+
+#### 简要介绍 app.use 的原理 
+
+uv-ui 在 Vue 3 项目中通过 `app.use(uvUI)` 注册，我们想借此机会解释一下插件注册的基本原理，详见[简要介绍 app.use 的原理](/components/vueUse.html)

package/docs/guide/globalVariable.md

@@ -0,0 +1,239 @@
+## 全局变量的实现方式
+
+uni-app Vue 3 项目中，全局变量建议优先使用组合式状态、普通配置模块或 `getApp().globalData`。如果项目已经引入 Vuex，也可以用 Vuex 4 的 `useStore()` 在 `<script setup>` 中读取和修改状态。
+
+常见方式：
+
+1. 本地存储：适合 token、用户偏好等需要跨启动保存的数据。
+2. 配置文件：适合接口域名、静态开关等构建期或运行期配置。
+3. `app.config.globalProperties`：适合少量确实需要挂到组件实例上的全局能力。
+4. `globalData`：适合 uni-app 全局数据，但它本身不是响应式。
+5. Vuex/Pinia：适合需要响应式更新的全局状态。
+
+### 本地存储
+
+```js
+uni.setStorageSync('token', 'value');
+
+const token = uni.getStorageSync('token');
+```
+
+异步写法：
+
+```js
+uni.setStorage({
+	key: 'token',
+	data: 'value',
+	success() {
+		console.log('保存成功');
+	}
+});
+
+uni.getStorage({
+	key: 'token',
+	success(res) {
+		console.log(res.data);
+	}
+});
+```
+
+### 配置文件
+
+```js
+// common/config.js
+export default {
+	domain: 'https://www.example.com'
+};
+```
+
+在页面中按需引入：
+
+```vue
+<script setup>
+import { onLoad } from '@dcloudio/uni-app';
+import config from '@/common/config.js';
+
+onLoad(() => {
+	console.log(config.domain);
+});
+
+</script>
+```
+
+### app.config.globalProperties
+
+如果确实需要挂载到组件实例上，Vue 3 使用 `app.config.globalProperties`：
+
+```js
+// main.js
+import App from './App';
+import { createSSRApp } from 'vue';
+import config from '@/common/config.js';
+
+export function createApp() {
+	const app = createSSRApp(App);
+	app.config.globalProperties.$domain = config.domain;
+	return { app };
+}
+```
+
+在 `<script setup>` 中读取：
+
+```vue
+<template>
+	<view>域名：{{ domain }}</view>
+</template>
+
+<script setup>
+import { getCurrentInstance } from 'vue';
+import { onLoad } from '@dcloudio/uni-app';
+
+const { proxy } = getCurrentInstance();
+const domain = proxy.$domain;
+
+onLoad(() => {
+	console.log(domain);
+});
+
+</script>
+```
+
+如果只是普通配置，优先直接 `import config`，不要为了少写一行 import 就挂到全局。
+
+### globalData
+
+`globalData` 简单直接，但不是响应式。页面返回或重新显示时，需要在 `onShow` 中重新同步到本页的响应式变量。
+
+```vue
+<!-- App.vue -->
+<script setup>
+import { onLaunch } from '@dcloudio/uni-app';
+
+const app = getApp({ allowDefault: true });
+app.globalData.userName = '白居易';
+
+onLaunch(() => {
+	console.log(app.globalData.userName);
+});
+
+</script>
+```
+
+页面 A：
+
+```vue
+<template>
+	<view>作者是：{{ author }}</view>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import { onShow } from '@dcloudio/uni-app';
+
+const author = ref('');
+
+onShow(() => {
+	author.value = getApp().globalData.userName;
+});
+
+</script>
+```
+
+页面 B 修改：
+
+```vue
+<template>
+	<view>
+		<view>作者是：{{ author }}</view>
+		<uv-button @click="modifyUserName">修改 userName</uv-button>
+	</view>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import { onShow } from '@dcloudio/uni-app';
+
+const author = ref('');
+
+onShow(() => {
+	author.value = getApp().globalData.userName;
+});
+
+function modifyUserName() {
+	getApp().globalData.userName = '诗圣';
+	author.value = getApp().globalData.userName;
+}
+
+</script>
+```
+
+### Vuex 4
+
+```js
+// store/index.js
+import { createStore } from 'vuex';
+
+const store = createStore({
+	state: {
+		vuex_token: '123654789',
+		vuex_user: {
+			name: '白居易'
+		}
+	},
+	mutations: {
+		modifyToken(state, payload) {
+			state.vuex_token = payload.token;
+		},
+		modifyUserName(state, name) {
+			state.vuex_user.name = name;
+		}
+	}
+});
+
+export default store;
+```
+
+在 `main.js` 中注册：
+
+```js
+import App from './App';
+import { createSSRApp } from 'vue';
+import store from '@/store';
+import uvUI from '@gmcb/uv-ui';
+
+export function createApp() {
+	const app = createSSRApp(App);
+	app.use(store);
+	app.use(uvUI);
+	return { app };
+}
+```
+
+页面中使用：
+
+```vue
+<template>
+	<view>
+		<view>Token 值为 {{ token }}</view>
+		<view>作者为 {{ userName }}</view>
+		<uv-button @click="btnClick">修改 Vuex 状态</uv-button>
+	</view>
+</template>
+
+<script setup>
+import { computed } from 'vue';
+import { useStore } from 'vuex';
+
+const store = useStore();
+const token = computed(() => store.state.vuex_token);
+const userName = computed(() => store.state.vuex_user.name);
+
+function btnClick() {
+	store.commit('modifyToken', { token: 'xxxyyyzzz' });
+	store.commit('modifyUserName', '诗圣');
+}
+
+</script>
+```
+
+如果项目只是需要 `@gmcb/uv-ui` 的工具方法，优先使用 `uni.$uv` 或按需导入工具函数；不要把业务状态挂到 `$uv` 上。