Flutter图像处理或展示插件 twicpics_components 的使用

概述

什么是 TwicPics？

TwicPics 是一个响应式媒体服务解决方案（SaaS），支持按需生成响应式图片和视频。开发者只需处理高分辨率版本的媒体文件，而终端用户将收到优化的、完美尺寸的、适应设备的版本，并从最近的交付点直接接收。

什么是 TwicPics Flutter Components？

TwicImg 和 TwicVideo 是使您能够在 Flutter 项目中轻松使用 TwicPics 功能的小部件。

特性

• 快速加载
• 图片和视频精确到像素
• 支持设备像素比（DPR）
• 延迟加载
• 低质量占位符
• 缓存管理
• 累积布局偏移（CLS）优化
• 智能裁剪
• 使用 TwicPics Transformations 实现更多功能

入门指南

要求

您需要有一个 TwicPics 账户。如果没有，您可以免费创建一个 TwicPics 账户。不过，您仍然可以使用我们的演示域来测试小部件，请参阅 /example 文件夹中的示例。

安装

在 pubspec.yaml 文件中添加 twicpics_components 作为依赖项：

$ flutter pub add twicpics_components

配置

配置您的 Flutter 应用程序：

// main.dart

import 'package:twicpics_components/twicpics_components.dart';

void main() {
  install(
    domain: "https://<your-domain>.twic.pics/",
  );
  runApp(...);
}

使用方法

显示网络图片

// my_widget.dart

import 'package:twicpics_components/twicpics_components.dart';

class MyWidget extends StatelessWidget {
  const MyWidget({super.key});
  [@override](/user/override)
  Widget build(BuildContext context) {
    return TwicImg(
      src: 'path/to/my/image',
    );
  }
}

显示网络视频

// my_widget.dart

import 'package:twicpics_components/twicpics_components.dart';

class MyWidget extends StatelessWidget {
  const MyWidget({super.key});
  [@override](/user/override)
  Widget build(BuildContext context) {
    return TwicVideo(
      src: 'path/to/my/video',
    );
  }
}

批量加载

当将 TwicImg 或 TwicVideo 嵌入到支持延迟加载的树中时，建议禁用延迟加载功能：

// my_widget.dart

class GridSample extends StatelessWidget {
  const GridSample({super.key});
  [@override](/user/override)
  Widget build(BuildContext context) {
    return GridView.count(
      primary: false,
      crossAxisCount: 3,
      children: [
        TwicImg(
          src: 'path/to/my/image',
          eager: true,
        ),
        TwicVideo(
          src: 'path/to/my/video',
          eager: true,
        ),
        // ...
      ]
    );
  }
}

设置焦点

您可以使用 focus 属性控制裁剪功能。

设置焦点点坐标

// my_widget.dart

class MyWidget extends StatelessWidget {
  const MyWidget({super.key});
  [@override](/user/override)
  Widget build(BuildContext context) {
    return TwicImg(
      src: 'path/to/my/image',
      focus: '30px40p', // 使用相对长度设置焦点点坐标
    );
  }
}

// my_widget.dart

class MyWidget extends StatelessWidget {
  const MyWidget({super.key});
  [@override](/user/override)
  Widget build(BuildContext context) {
    return TwicImg(
      src: 'path/to/my/image',
      focus: '345x678', // 使用绝对长度设置焦点点坐标
    );
  }
}

自动设置焦点

// my_widget.dart

class MyWidget extends StatelessWidget {
  const MyWidget({super.key});
  [@override](/user/override)
  Widget build(BuildContext context) {
    return TwicImg(
      src: 'path/to/my/image',
      focus: 'auto', // 自动选择焦点点
    );
  }
}

显示宽屏资产

通过设置 ratio 属性更改生成和显示资产的纵横比。

// my_widget.dart

class MyWidget extends StatelessWidget {
  const MyWidget({super.key});
  [@override](/user/override)
  Widget build(BuildContext context) {
    return TwicImg(
      src: 'path/to/my/image', // 主图片文件
      ratio: '4/3',
    );
  }
}

// my_widget.dart

class MyWidget extends StatelessWidget {
  const MyWidget({super.key});
  [@override](/user/override)
  Widget build(BuildContext context) {
    return TwicVideo(
      src: 'path/to/my/video', // 主视频文件
      ratio: '4/3',
    );
  }
}

使用 Row 小部件

当使用 Row Widget 时，必须为 TwicImg 或 TwicVideo 约束可用宽度：

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

class RowSample extends StatelessWidget {
  const RowSample({super.key});
  [@override](/user/override)
  Widget build(BuildContext context) {
    return Row(
      children: [
        SizedBox(
          width: 100, // 固定宽度
          child: TwicImg(
            src:'path/to/my/image',
          ),
        ),
        Expanded( // 让子组件填充可用空间
          child: TwicVideo(
            src:'path/to/my/video',
          ),
        ),
      ],
    );
  }
}

使用 TwicPics 转换

您可以通过 preTransform 属性访问 TwicPics Transformation。

// grid_sample.dart

class MyWidget extends StatelessWidget {
  const MyWidget({super.key});
  [@override](/user/override)
  Widget build(BuildContext context) {
    return TwicImg(
      src: 'path/to/my/image',
      preTransform: 'background=remove',
    );
  }
}

显示视频的最佳片段

TwicVideo 小部件允许您选择要显示的主视频文件的部分。用于选择的属性包括：

• from: 移动视频的起点
• to: 移动视频的终点
• duration: 限制视频的持续时间

这些属性的值以秒表示，且必须为正数。

// grid_sample.dart

class MyWidget extends StatelessWidget {
  const MyWidget({super.key});
  [@override](/user/override)
  Widget build(BuildContext context) {
    return TwicVideo(
      src: 'path/to/my/video',
      from: '3', /* 从第 3 秒开始播放视频 */
      to: '10.5' /* 在 10.5 秒结束 */
    );
  }
}