文档

Appearance

图片 ​

版本说明 ​

时间修改人备注
2025-04-24YG补充文档
2025-10-20YG添加图片资源管理方案getAssetUrl

一、基本展示规范 ​

  • 图片展示时，尺寸不能压缩变形
  • 当图片资源不存在，界面不能展示裂开的图或者白屏，默认展示一张报错的图片
  • 当禁止图片被选中时，需要给图片加一个css属性 pointer-events: none，防止部分安卓机点击图片时会覆盖在页面上
  • 根据实际情况选择使用vant里Image的 fit 属性：contain、cover; （vant文档）
  • 在小程序环境下可以使用 <image> 的 mode 属性：aspectFit、aspectFill、widthFix、heightFix;（微信小程序文档）
  • 移动端展示类图片一般都要加图片预览功能，除了一些特殊情况，如：banner图、头像等。
  • 图片预览使用vant的 ImagePreview 实现。
  • 在UniApp中也可以使用 uni.previewImage() API实现跨平台的图片预览功能
  • 图片懒加载：使用vant图片组件 vant-image 的 lazy-load 属性。
  • 在UniApp中使用 <image> 组件的 lazy-load 属性实现懒加载

二、图片格式选择 ​

  • PNG格式：适用于需要透明度的图像、图标、插图等

    • 优点：支持透明度，无损压缩
    • 缺点：文件较大

  • SVG格式：适用于图标、简单图形

    • 优点：矢量图形，缩放不失真，文件小
    • 缺点：不适合复杂图像，渲染复杂图形时性能较差

三、图片尺寸与优化 ​

  • 图片资源应部署在CDN上，提高加载速度

  • 尺寸控制

    • 图片实际尺寸应与展示尺寸相匹配，避免过大造成资源浪费
    • 建议图片宽度不超过750px（满足2倍屏需求）
    • 图标类图片建议使用icon-font或SVG代替

  • 图片压缩

    • 上传前应对图片进行适当压缩（不能有模糊感）
    • 可使用TinyPNG等工具进行无损压缩

四、应用方案：cdn图片资源管理方案 ​

为了更好地管理项目中的图片资源，推荐使用 getAssetUrl 工具函数来统一处理不同环境下的图片路径。

4.1 getAssetUrl 工具函数介绍 ​

getAssetUrl 是一个用于处理资源路径的工具函数，可以根据不同环境自动适配资源路径的加载方式，主要解决以下问题：

  1. 在不同环境（CDN、本地、小程序）下统一资源访问方式
  2. 支持构建时的资源预加载和处理
  3. 确保路径格式一致性
  4. 支持CDN资源加密

4.2 使用方法 ​

无需引入，直接在代码中使用 getAssetUrl 或 uni.getAssetUrl 函数即可。

在template模版中使用 ​

js
// 在组件中使用
<image :src="getAssetUrl('assets/images/home/banner1.png')"></image>

// 或者使用全局方法
<image :src="uni.getAssetUrl('assets/images/home/banner1.png')"></image>

在script中使用 ​

js
const bannerItems = ref([
    { img: uni.getAssetUrl('assets/images/home/banner1.png')},
    { img: uni.getAssetUrl('assets/images/home/banner2.png')},
    { img: uni.getAssetUrl('assets/images/home/banner1.png')},
])

在style标签中使用 ​

vue
<script setup>
const iconRight = `url(${uni.getAssetUrl('assets/images/shop/icon-right.png')})`;
</script>

<style lang="scss" scoped>

.icon-score {
    background: v-bind(iconRight) no-repeat top/20rpx 20rpx;
}
</style>

4.3 实现原理 ​

getAssetUrl 函数根据不同环境提供不同的资源路径处理策略：

  1. CDN 环境：当环境变量 VITE_CDN_RESOURCE_URL 以 http 开头时，直接返回 CDN 路径
  2. 本地：使用 /assets/ 开头的绝对路径

4.4 在项目中配置使用 ​

1. 创建资源路径工具函数 ​

在 src/utils 目录下导出 getAssetUrl 方法：

js
/**
 * 获取资源URL的工具函数
 * 支持不同环境下的资源路径处理
 */

// 预加载资源，使用构建工具的资源预加载功能
const imageModules = import.meta.glob('/src/assets/**/*.{png,jpg,jpeg,gif,svg,webp,js,html,ttf,woff,woff2,eot,otf}', { eager: true });
const cdnResourceUrl = import.meta.env.VITE_APP_CDN_RESOURCE_URL;
const cdnAuthKey = import.meta.env.VITE_APP_CDN_AUTH_KEY;
const cdnAuthOpen = import.meta.env.VITE_APP_CDN_AUTH_OPEN;
const cdnAuthTime = import.meta.env.VITE_APP_CDN_AUTH_TIME;

export const getAssetUrl = (relativePath) => {
    // console.warn('getAssetUrl', relativePath);
    // 如果cdnResourceUrl以http开头，则直接返回cdn资源，否则访问本地路径
    if (cdnResourceUrl && cdnResourceUrl.startsWith('http')) {
        const result = generateAuthUrl(cdnResourceUrl + relativePath, {});
        return result;
    }
    // 确保路径格式一致
    const normalizedPath = relativePath.startsWith('/')
        ? relativePath
        : `/${relativePath}`;

    // 小程序环境使用绝对路径
    // #ifdef MP-WEIXIN
    return `/${relativePath}`;
    // #endif

    // 非小程序环境尝试使用Vite的资源处理
    // #ifndef MP-WEIXIN
    try {
        // 构建完整路径
        const fullPath = `/src${normalizedPath}`;

        // 检查资源是否存在于预加载的模块中
        if (imageModules[fullPath]) {
            return imageModules[fullPath].default;
        }

        // 资源不存在时回退到静态路径
        console.warn(`[getAssetUrl] 资源未找到: ${fullPath}，使用回退路径`);
        return `${import.meta.env.VITE_APP_CDN_RESOURCE_URL || './static/'}${relativePath}`;
    } catch (error) {
        console.error('[getAssetUrl] 加载资源出错:', error);
        return `${import.meta.env.VITE_APP_CDN_RESOURCE_URL || './static/'}${relativePath}`;
    }
    // #endif
}

2. 在 main.js 中全局挂载 ​

js
import { createSSRApp } from "vue";
import App from "./App.vue";
// 导入资源路径工具函数
import { getAssetUrl } from '@/utils/assetUtils';

export function createApp() {
    const app = createSSRApp(App);
    
    // 将getAssetUrl挂载为全局属性
    app.config.globalProperties.getAssetUrl = getAssetUrl;
    
    // 挂载为全局方法，方便在组件外部使用
    uni.getAssetUrl = getAssetUrl;
    
    // 将 CDN 地址挂载到全局
    uni.cdnEnvUrl = import.meta.env.VITE_CDN_RESOURCE_URL;
    
    return {
        app,
    };
}

3. 配置环境变量 ​

在项目根目录创建 .env 或 .env.production 文件：

env
# 资源 CDN 地址，生产环境使用 CDN，开发环境留空使用本地资源
VITE_CDN_RESOURCE_URL=https://your-cdn-domain.com/

4.5 资源目录建议结构 ​

src/
├── assets/
│   ├── images/
│   │   ├── home/
│   │   │   ├── banner1.png
│   │   │   └── banner2.png
│   │   ├── icons/
│   │   │   ├── icon1.png
│   │   │   └── icon2.png
│   │   └── common/
│   │       ├── logo.png
│   │       └── background.jpg
│   ├── fonts/
│   └── js/

4.6 注意事项 ​

  1. 资源路径始终相对于 src 目录，如 assets/images/home/banner1.png
  2. 环境变量 VITE_CDN_RESOURCE_URL 在生产环境下应指向有效的 CDN 地址