@ecolovo/uniapp-components 1.0.9 → 2.0.0

package/README.md

@@ -1,37 +1,28 @@
 # @ecolovo/uniapp-components
 
-Ecolovo UniApp 组件库
+UniApp **Vue3** 组件库。
 
+本项目是为基于 `cli` 脚手架创建的项目开发的，未在 HBuilderX 项目中实践，请自行验证是否可以正常使用。
 
-## Installation
+## 安装
 
 使用 npm / yarn 安装
 
 ```bash
-  npm install @ecolovo/uniapp-components
+npm install @ecolovo/uniapp-components
 ```
 
 同时需要使用 `uni-pages-hot-modules` 用来动态配置
 
 ```bash
-  npm install uni-pages-hot-modules --save-dev
+npm install uni-pages-hot-modules --save-dev
 ```
 
-## Usage
+## 组件库的配置
 
-### 1. 配置 `vue.config.js` 文件
+使用前，请按照以下步骤进行一些必要的配置。
 
-```javascript
-// vue.config.js
-
-module.exports = {
-  // configs...
-  transpileDependencies: ['@ecolovo/uniapp-components'],
-  // other configs...
-}
-```
-
-### 2. 在 `src/main.js` 文件中初始化组件库
+### 1. 在 `src/main.js` 文件中初始化组件库
 
 ```javascript
 // src/main.js
@@ -39,13 +30,13 @@ module.exports = {
 import init from '@ecolovo/uniapp-components/init';
 
 init({
-  // 配置组件前缀
-  // 在使用时加上前缀，如 button 组件，使用 <ui-button>
-  componentPrefix: 'ui',
+	// 配置组件前缀
+	// 在使用时加上前缀，如 button 组件，使用 <ui-button>
+	componentPrefix: 'ui',
 });
 ```
 
-### 3. 配置 `src/pages.js` 文件，
+### 2. 配置 `src/pages.js` 文件，
 
 ```javascript
 // src/pages.js
@@ -55,44 +46,55 @@ const { hot } = require('uni-pages-hot-modules');
 const componentEasyCom = require('@ecolovo/uniapp-components/easyCom');
 
 module.exports = hot((pagesJson) => {
-  const pagesConfig = require('./pagesDef');
-
-  return mergeWith(
-    // pages.json 中的配置
-    pagesJson,
-    pagesConfig,
-    componentEasyCom('ui'), // 填入和步骤 2 中同样的前缀
-    function (objValue, srcValue) {
-      if (Array.isArray(objValue)) {
-        return objValue.concat(srcValue);
-      }
-    }
-  );
+	const pagesConfig = require('./pagesDef');
+
+	return mergeWith(
+		// pages.json 中的配置
+		pagesJson,
+		pagesConfig,
+		componentEasyCom('ui'), // 填入和步骤 2 中同样的前缀
+		function (objValue, srcValue) {
+			if (Array.isArray(objValue)) {
+				return objValue.concat(srcValue);
+			}
+		}
+	);
 });
 ```
 
-### 4. 配置样式
+### 3. 配置样式
 
 #### 全局样式
 
-```html
+```vue
 <!-- App.vue -->
 
 <style lang="scss">
+// 引入组件库全局样式
 @use '@ecolovo/uniapp-components/styles/global';
 </style>
 ```
 
-#### 自定义组件配置
+#### 自定义样式
 
-```css
+```scss
 /* src/styles/prepend.scss */
 
+// 修改全局组件前缀与主题等全局样式
 @forward '@ecolovo/uniapp-components/styles/var/theme' with (
-  $component-prefix: 'ui', // 推荐修改为与组件前缀一致
-  $themes: (
-    primary: #d92e20,
-  )
+	$component-prefix: 'ui',
+	// 推荐修改为与组件前缀一致
+	$themes:
+		(
+			primary: #d92e20,
+		)
+);
+
+// 修改组件默认样式
+@forward '@ecolovo/uniapp-components/styles/var/component' with (
+	$badge: (
+		background: #d92e20,
+	)
 );
 
 @forward '@ecolovo/uniapp-components/styles';
@@ -104,14 +106,44 @@ module.exports = hot((pagesJson) => {
 const sass = require('sass');
 
 module.exports = {
-  // configs...
-  css: {
-    loaderOptions: {
-      scss: {
-        prependData: '@use "@/styles/prepend" as *;'
-      },
-    },
-  },
-  // other configs...
+	// configs...
+	css: {
+		loaderOptions: {
+			scss: {
+				prependData: '@use "@/styles/prepend" as *;',
+			},
+		},
+	},
+	// other configs...
 };
 ```
+
+### 4. 全局可用的 css 变量
+
+以下变量的访问必须为 `<ui-page>` 的内部元素。
+
+```scss
+// 顶部安全区高度
+--safe-area-top: 30px;
+
+// 底部安全区高度
+--safe-area-bottom: 30px;
+
+// 页面头部上边缘相较于顶部的距离，原则上等于 `--safe-area-top`
+--page-header-top: 30px;
+
+// 页面头部高度
+--page-header-height: 44px;
+
+// 页面头部下边缘相较于顶部的距离，原则上等于 `--page-header-top` + `--page-header-height`
+--page-header-bottom: 74px;
+
+// 小程序胶囊按钮宽度（实际为胶囊按钮最左侧到页面右边的距离）
+--menu-button-width: calc(100vw - 280px);
+```
+
+> 上述变量后的值仅供参考，以实际值为准
+
+## 使用
+
+请阅读 [**使用文档**](./docs/index.md) 。

package/components/aspect/aspect.vue

@@ -1,6 +1,6 @@
 <template>
-	<view :class="componentClassNames">
-		<view :class="$style['Aspect--content-wrapper']" :style="{ paddingTop: 100 * ratio + '%' }">
+	<view :class="[...classNames, $style['Aspect']]">
+		<view :class="$style['Aspect--content-wrapper']" :style="inlineStyle">
 			<view :class="$style['Aspect--content']" @click="$emit('click')">
 				<slot></slot>
 			</view>
@@ -8,24 +8,33 @@
 	</view>
 </template>
 
-<script>
-import componentName from '../../mixins/componentName';
+<script lang="ts" setup>
+import { computed } from 'vue';
+import useClassNames from '../../composable/component-name';
 
-export default {
-	name: 'Aspect',
+defineOptions({
 	options: {
-		virtualHost: true,
 		styleIsolation: 'shared',
+		virtualHost: true,
 	},
-	mixins: [componentName],
-	props: {
-		/** 高与宽的比例，默认为 1，即宽高相等，2 表示高为宽的 2 倍 */
-		ratio: {
-			type: [String, Number],
-			default: 1,
-		},
-	},
+});
+
+const classNames = useClassNames('aspect');
+
+type _Props = {
+	/** 图标名 */
+	ratio?: string | number;
 };
+
+const props = withDefaults(defineProps<_Props>(), {
+	ratio: 1,
+});
+
+defineEmits<{
+	(event: 'click'): void;
+}>();
+
+const inlineStyle = computed(() => `padding-top: ${100 * Number(props.ratio)}%;`);
 </script>
 
 <style lang="css" module>

package/components/badge/badge.scss

@@ -0,0 +1,20 @@
+@use 'sass:map';
+@use '../../styles/utils' as *;
+
+$badge: () !default;
+// 可配置的变量
+$badge-default: (
+	// 徽章相对于挂载元素右上角的偏移量
+	translate: 40% -40%,
+	// 文字字号
+	font-size: UTILS__GLOBAL_VAR(font-size, small),
+	// 文字颜色
+	color: #fff,
+	// 背景色
+	background: #ff0000,
+	// 边框样式
+	border: none,
+	// 徽章高度
+	height: calc(#{UTILS__LOCAL_VAR(font-size)} + 12rpx)
+);
+$badge: map.merge($badge-default, $badge);

package/components/badge/badge.vue

@@ -1,5 +1,5 @@
 <template>
-	<view :class="componentClassNames">
+	<view :class="[...classNames, $style['Badge']]">
 		<slot></slot>
 		<template v-if="$slots['badge'] || $slots['badge-value']">
 			<slot name="badge">
@@ -15,48 +15,57 @@
 	</view>
 </template>
 
-<script>
-import componentName from '../../mixins/componentName';
+<script lang="ts" setup>
+import { computed } from 'vue';
+import useClassNames from '../../composable/component-name';
 
-export default {
-	name: 'Badge',
+defineOptions({
 	options: {
-		virtualHost: true,
 		styleIsolation: 'shared',
+		virtualHost: true,
 	},
-	mixins: [componentName],
-	props: {
-		/** 显示在右上角的内容 */
-		value: {
-			type: [String, Number],
-			default: 0,
-		},
-		/** 最大显示值，超出时会在后面添加一个“+” */
-		max: {
-			type: Number,
-			default: 99,
-		},
-	},
-	computed: {
-		/** 显示值 */
-		showValue() {
-			const numberValue = Number(this.value);
-			return numberValue && numberValue > 0 ? (numberValue > this.max ? `${this.max}+` : numberValue) : '';
-		},
-	},
+});
+
+const classNames = useClassNames('badge');
+
+type _Props = {
+	/** 显示在右上角的内容 */
+	value?: string | number;
+	/** 最大显示值，超出时会在后面添加一个“+” */
+	max?: number;
 };
+
+const props = withDefaults(defineProps<_Props>(), {
+	value: 0,
+	max: 99,
+});
+
+defineEmits<{
+	(event: 'click'): void;
+}>();
+
+const showValue = computed(() => {
+	const numberValue = Number(props.value);
+	return numberValue && numberValue > 0 ? (numberValue > props.max ? `${props.max}+` : numberValue) : '';
+});
 </script>
 
 <style lang="scss" module>
-@use '../../styles/index' as *;
+@use '../../styles/utils' as *;
+@use './badge' as *;
 
 // 定义外部变量
-$component-name: 'badge';
-$component-vars: $badge;
 %external-vars {
-	@include UTILS__DEFINE_COMPONENT_VARS();
+	@include UTILS__DEFINE_COMPONENT_VARS($badge, 'badge');
 }
 
+$__translate: UTILS__LOCAL_VAR(translate);
+$__font-size: UTILS__LOCAL_VAR(font-size);
+$__height: UTILS__LOCAL_VAR(height);
+$__border: UTILS__LOCAL_VAR(border);
+$__color: UTILS__LOCAL_VAR(color);
+$__background: UTILS__LOCAL_VAR(background);
+
 .Badge {
 	@extend %external-vars;
 
@@ -65,7 +74,7 @@ $component-vars: $badge;
 	width: fit-content;
 
 	.Badge--box {
-		--padding-x: calc(#{UTILS__LOCAL_VAR(font-size)} / 2);
+		--padding-x: calc(#{$__font-size} / 2);
 
 		position: absolute;
 		top: 0;
@@ -74,15 +83,15 @@ $component-vars: $badge;
 		padding: 0 var(--padding-x);
 		box-sizing: content-box;
 		text-align: center;
-		min-width: calc(#{UTILS__LOCAL_VAR(height)} - 2 * var(--padding-x));
-		height: UTILS__LOCAL_VAR(height);
-		line-height: UTILS__LOCAL_VAR(height);
-		font-size: UTILS__LOCAL_VAR(font-size);
-		border: UTILS__LOCAL_VAR(border);
-		border-radius: UTILS__LOCAL_VAR(height);
-		translate: UTILS__LOCAL_VAR(translate);
-		color: UTILS__LOCAL_VAR(color);
-		background: UTILS__LOCAL_VAR(background);
+		min-width: calc(#{$__height} - 2 * var(--padding-x));
+		height: $__height;
+		line-height: $__height;
+		font-size: $__font-size;
+		border: $__border;
+		border-radius: $__height;
+		translate: $__translate;
+		color: $__color;
+		background: $__background;
 	}
 }
 </style>

package/components/button/button.scss

@@ -0,0 +1,15 @@
+@use 'sass:map';
+
+// 可配置的变量
+$button: () !default;
+$button-default: (
+	// 按钮主题颜色，默认取值组件 props 中的 type
+	theme: var(--theme-from-prop),
+	// 按钮文本颜色
+	text-color: #fff,
+	// 按钮激活态遮罩颜色
+	active-mask: #ffffff,
+	// plain 按钮的边框宽度
+	border-width: 3rpx
+);
+$button: map.merge($button-default, $button);