@ecolovo/uniapp-components 1.0.10 → 2.0.1

package/README.md

@@ -1,117 +1,253 @@
 # @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
-```
-
-## 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
 
-import init from '@ecolovo/uniapp-components/init';
+import { init } from '@ecolovo/uniapp-components';
 
 init({
-  // 配置组件前缀
-  // 在使用时加上前缀，如 button 组件，使用 <ui-button>
-  componentPrefix: 'ui',
+	// 配置组件前缀
+	// 在使用时加上前缀，如 button 组件，使用 <ui-button>
+	componentPrefix: 'ui',
 });
 ```
 
-### 3. 配置 `src/pages.js` 文件，
+### 2. 配置 `src/pages.js` 文件
 
 ```javascript
 // src/pages.js
 
 const mergeWith = require('lodash/mergeWith');
-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 componentEasyCom = require('@ecolovo/uniapp-components/easyCom').default;
+const pageJson = require('./pages-config/index');
+
+module.exports = mergeWith(
+	pageJson,
+	componentEasyCom('ui'), // 填入和步骤 2 中同样的前缀
+	function (objValue, srcValue) {
+		if (Array.isArray(objValue)) {
+			return objValue.concat(srcValue);
+		}
+	}
+);
 ```
 
-### 4. 配置样式
+> `uni-pages-hot-modules` 库在 Vue3.x 版本中无法正常使用，可使用以下脚本进行 `pages.js` 的动态配置
+>
+> ```javascript
+> // scripts/build.js
+>
+> /* eslint-disable no-console, @typescript-eslint/no-require-imports */
+>
+> const fs = require('fs');
+> const path = require('path');
+> const srcDir = path.resolve(__dirname, '../src');
+> const pagesJsPath = path.join(srcDir, 'pages.js');
+> const pagesConfigDir = path.join(srcDir, 'pages-config');
+> const mainTsPath = path.join(srcDir, 'main.ts');
+>
+> // 1. Inject environment variables before pages.js is evaluated
+> const platformArgIndex = process.argv.indexOf('-p');
+> const platform = platformArgIndex !== -1 ? process.argv[platformArgIndex + 1] : 'h5';
+> process.env.UNI_PLATFORM = platform;
+>
+> const envPath = path.resolve(__dirname, '../.env');
+> if (fs.existsSync(envPath)) {
+> 	const envContent = fs.readFileSync(envPath, 'utf-8');
+> 	for (const line of envContent.split(/\r?\n/)) {
+> 		const trimmed = line.trim();
+> 		if (!trimmed || trimmed.startsWith('#')) continue;
+> 		const eqIndex = trimmed.indexOf('=');
+> 		if (eqIndex !== -1) {
+> 			const key = trimmed.slice(0, eqIndex).trim();
+> 			let value = trimmed.slice(eqIndex + 1).trim();
+> 			if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+> 				value = value.slice(1, -1);
+> 			}
+> 			process.env[key] = value;
+> 		}
+> 	}
+> }
+>
+> // 2. Evaluate pages.js to generate config in memory
+> Object.keys(require.cache).forEach((key) => {
+> 	if (key.includes('pages-config') || key.endsWith(path.join('src', 'pages.js'))) {
+> 		delete require.cache[key];
+> 	}
+> });
+> const pagesConfig = require(pagesJsPath);
+> let pagesJsonStr = JSON.stringify(pagesConfig);
+>
+> // 3. Patch fs.readFileSync to intercept pages.json reads
+> const originalReadFileSync = fs.readFileSync;
+> fs.readFileSync = function (...args) {
+> 	const filePath = typeof args[0] === 'string' ? path.resolve(args[0]) : '';
+> 	if (filePath.endsWith('pages.json')) {
+> 		const options = args[1];
+> 		const encoding = typeof options === 'string' ? options : options && options.encoding;
+> 		if (encoding === 'utf8' || encoding === 'utf-8') {
+> 			return pagesJsonStr;
+> 		}
+> 		return Buffer.from(pagesJsonStr, 'utf8');
+> 	}
+> 	return originalReadFileSync.apply(this, args);
+> };
+>
+> // 4. Replace parsePagesJsonOnce with non-cached version, so rebuilds pick up new config
+> const pagesModulePath = require.resolve('@dcloudio/uni-cli-shared/dist/json/pages');
+> delete require.cache[pagesModulePath];
+> const pagesModule = require(pagesModulePath);
+> const originalParsePagesJson = pagesModule.parsePagesJson;
+> pagesModule.parsePagesJsonOnce = function (inputDir, platform) {
+> 	return originalParsePagesJson(inputDir, platform);
+> };
+>
+> // 5. Set up file watcher for HMR (watch mode only)
+> const hasBuildCommand = process.argv.includes('build');
+> const hasWatch = process.argv.includes('-w') || process.argv.includes('--watch');
+> const isDevMode = !hasBuildCommand || hasWatch;
+>
+> if (isDevMode && fs.existsSync(pagesConfigDir)) {
+> 	try {
+> 		const chokidar = require('chokidar');
+> 		const watcher = chokidar.watch(pagesConfigDir, {
+> 			ignoreInitial: true,
+> 			awaitWriteFinish: { stabilityThreshold: 300 },
+> 		});
+> 		watcher.on('change', (file) => {
+> 			console.log(`[HMR] Pages config changed: ${path.relative(srcDir, file)}`);
+>
+> 			// Clear require cache for config modules
+> 			Object.keys(require.cache).forEach((key) => {
+> 				if (key.includes('pages-config') || key.endsWith(path.join('src', 'pages.js'))) {
+> 					delete require.cache[key];
+> 				}
+> 			});
+>
+> 			// Re-evaluate pages.js and update in-memory config
+> 			const newConfig = require(pagesJsPath);
+> 			pagesJsonStr = JSON.stringify(newConfig);
+>
+> 			// Touch main.ts to trigger Rollup rebuild
+> 			try {
+> 				const now = new Date();
+> 				fs.utimesSync(mainTsPath, now, now);
+> 			} catch (_) {
+> 				// Fallback: touch any .vue file
+> 				const fallback = path.join(srcDir, 'App.vue');
+> 				if (fs.existsSync(fallback)) {
+> 					const now = new Date();
+> 					fs.utimesSync(fallback, now, now);
+> 				}
+> 			}
+> 		});
+> 	} catch {
+> 		console.warn('[HMR] chokidar not available, pages hot reload disabled');
+> 	}
+> }
+>
+> // 6. Run the uni CLI
+> require('@dcloudio/vite-plugin-uni/bin/uni');
+> ```
+>
+> package.json 中的脚本需要替换，如 `dev:mp-weixin` 由原来的 `uni -p mp-weixin` 替换为 `node scripts/build.js -p mp-weixin` 。
+
+### 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';
 ```
 
 ```javascript
-// vue.config.js
-
-const sass = require('sass');
-
+// vite.config.ts
 module.exports = {
-  // configs...
-  css: {
-    loaderOptions: {
-      scss: {
-        prependData: '@use "@/styles/prepend" as *;'
-      },
-    },
-  },
-  // other configs...
+	// other configs...
+	css: {
+		preprocessorOptions: {
+			scss: {
+				additionalData: '@use "@/styles/prepend.scss" as *;',
+			},
+		},
+	},
 };
 ```
+
+### 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);