Flutter图片加载与显示插件octo_image的使用

OctoImage

OctoImage 是一个用于显示占位符、错误部件并转换图像的库。推荐与 CachedNetworkImage 版本 2.2.0 或更新版本一起使用。

快速开始

OctoImage 需要一个 ImageProvider 来显示图像。你可以提供占位符或进度指示器、ImageBuilder 和/或错误部件。或者，可以使用预定义的组合 OctoSet。

自定义所有组件

OctoImage(
  image: CachedNetworkImageProvider('https://blurha.sh/assets/images/img1.jpg'),
  placeholderBuilder: OctoPlaceholder.blurHash(
    'LEHV6nWB2yk8pyo0adR*.7kCMdnj',
  ),
  errorBuilder: OctoError.icon(color: Colors.red),
  fit: BoxFit.cover,
);

使用 OctoSet

OctoImage.fromSet(
  fit: BoxFit.cover,
  image: CachedNetworkImageProvider(
    'https://upload.wikimedia.org/wikipedia/commons/thumb/4/4e/Macaca_nigra_self-portrait_large.jpg/1024px-Macaca_nigra_self-portrait_large.jpg',
  ),
  octoSet: OctoSet.circleAvatar(
    backgroundColor: Colors.red,
    text: Text("M"),
  ),
);

ImageProviders

推荐使用 CachedNetworkImageProvider，因为它支持进度指示器、错误处理和缓存，并且在 Android、iOS、Web 和 macOS 上工作良好（Web 上不支持缓存）。确保使用至少 2.2.0 版本。

其他 ImageProvider 也可以使用，但对于某些 ImageProvider（如 MemoryImage），使用 OctoImage 没有意义。

占位符和进度指示器

最好只使用占位符或进度指示器之一，但不要同时使用两者。占位符仅在图像开始加载时构建一次，而进度指示器每次收到新的进度信息时都会重建。

最简单的进度指示器是 CircularProgressIndicator。

OctoImage(
  image: image,
  progressIndicatorBuilder: (context) => const CircularProgressIndicator(),
),

使用预构建的进度指示器：

OctoImage(
  image: image,
  progressIndicatorBuilder: OctoProgressIndicator.circularProgressIndicator(),
),

包括的所有占位符和进度指示器：

错误部件

当 ImageProvider 抛出错误时显示错误部件。你可以构建自定义部件或使用预构建部件：

OctoImage(
  image: image,
  errorBuilder: (context, error, stacktrace) => const Icon(Icons.error),
);

使用预构建的错误部件：

OctoImage(
  image: image,
  errorBuilder: OctoError.icon(),
);

包括的所有错误部件：

图像构建器

图像构建器可以在显示之前调整图像。例如，将图像裁剪成圆形，或添加覆盖层等。

示例：以 50% 的不透明度显示图像：

OctoImage(
  image: image,
  imageBuilder: (context, child) => Opacity(
    opacity: 0.5,
    child: child,
  ),
);

使用预构建的图像转换器裁剪图像为圆形：

OctoImage(
  image: image,
  imageBuilder: OctoImageTransformer.circleAvatar(),
);

包括的所有图像转换器：

OctoSets

使用 OctoSet 可以获得最佳效果。这些集合包含占位符或进度指示器、图像构建器和/或错误部件构建器的组合。始终至少包含占位符或进度指示器和错误部件。

使用 OctoImage.fromSet：

OctoImage.fromSet(
  image: image,
  octoSet: OctoSet.circleAvatar(backgroundColor: Colors.red, text: Text("M")),
);

包括的所有 OctoSet：

示例代码

import 'package:flutter/material.dart';
import 'package:octo_image/octo_image.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'OctoImage Demo',
      theme: ThemeData(),
      home: const OctoImagePage(),
    );
  }
}

class OctoImagePage extends StatelessWidget {
  const OctoImagePage({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('OctoImage Demo'),
      ),
      body: ListView(
        children: [
          _customImage(),
          const SizedBox(height: 16),
          _circleAvatar(),
        ],
      ),
    );
  }

  Widget _customImage() {
    return SizedBox(
      height: 150,
      child: OctoImage(
        image: const NetworkImage('https://via.placeholder.com/150'),
        progressIndicatorBuilder: (context, progress) {
          double? value;
          var expectedBytes = progress?.expectedTotalBytes;
          if (progress != null && expectedBytes != null) {
            value = progress.cumulativeBytesLoaded / expectedBytes;
          }
          return CircularProgressIndicator(value: value);
        },
        errorBuilder: (context, error, stacktrace) => const Icon(Icons.error),
      ),
    );
  }

  Widget _circleAvatar() {
    return SizedBox(
      height: 75,
      child: OctoImage.fromSet(
        fit: BoxFit.cover,
        image: const NetworkImage(
          'https://upload.wikimedia.org/wikipedia/commons/thumb/4/4e/Macaca_nigra_self-portrait_large.jpg/1024px-Macaca_nigra_self-portrait_large.jpg',
        ),
        octoSet: OctoSet.circleAvatar(
          backgroundColor: Colors.red,
          text: const Text("M"),
        ),
      ),
    );
  }
}