@lyb/media-preview项目招募

模块 1：核心基础能力开发

1.1 媒资模型定义

需实现通用默认媒资模型，并支持泛型自定义扩展，兼容图片、视频等基础媒资类型，核心字段包含媒资地址、宽高、类型等，仓颉语言示例代码规范：

// 仓颉语言 - 默认媒资模型定义
pub struct DefaultMediaModel {
  pub uri: string;        // 媒资资源地址
  pub width: float;       // 媒资宽度
  pub height: float;      // 媒资高度
  pub mediaType: MediaType; // 媒资类型：图片/视频
}

// 媒资类型枚举
pub enum MediaType {
  IMAGE,
  VIDEO
}

// 泛型预览配置选项（核心，支持自定义模型）
pub struct MediaPreviewOptions<T> {
  pub initIndex: int = 0; // 初始预览索引
  pub medias: List<T>;    // 媒资列表
  pub thumbBuilder: (item: T, index: int) => Component; // 缩略图构建器
  pub contentBuilder: (item: T, index: int) => Component; // 预览内容构建器
}

1.2 基础预览能力

1. 实现媒资列表的加载与渲染，支持设置初始预览索引；

2. 实现媒资的滑动切换（横向），支持懒加载优化，降低内存占用；

3. 实现基础手势交互：双击缩放、双指捏合缩放 / 旋转、拖拽平移，缩放最大比例建议 1.5（防止失真）；

4. 实现预览窗口的打开 / 关闭，支持与主页面的无缝衔接。

仓颉语言核心调用示例：

// 仓颉语言 - 预览框架核心调用
pub class MediaPreview {
  // 打开预览窗口，接收UI上下文和配置选项
  pub static func open(context: UIContext, options: MediaPreviewOptions<Any>): void {
    // 核心实现：渲染预览页面、绑定媒资数据、初始化动画
  }
}

// 业务侧调用示例
let options = MediaPreviewOptions<DefaultMediaModel> {
  initIndex: 0,
  medias: mediaList
};
MediaPreview.open(getUIContext(), options);

1.3 仿微信一镜到底转场动画

这是核心功能，需实现入场 / 出场无缝转场，无闪屏、无卡顿，帧率稳定 60FPS，核心实现要求：

1. 为列表项绑定唯一geometryId，实现共享元素转场；

2. 记录点击项的位置、宽高信息，用于动画的起始 / 结束状态匹配；

3. 实现卡片到预览页的宽高、位置属性动画，duration 建议 200ms；

4. 预览时隐藏原列表项，返回时恢复显示，模拟微信原生体验；

5. 解决 Image 组件渲染延迟导致的闪屏问题，添加渲染完成回调。

仓颉语言动画核心示例：

// 仓颉语言 - 一镜到底转场动画核心
pub struct MediaListItem<T> {
  pub item: T;
  pub index: int;
  pub options: MediaPreviewOptions<T>;

  build() {
    Column() {
      // 预览缩略图组件，绑定共享元素ID
      Image(this.item.uri)
        .geometryId(this.getGeometryId())
        .onAreaChange((old, new) => {
          // 记录元素位置/宽高信息
          this.saveItemArea(new);
        });
    }
    .onClick(() => {
      // 隐藏当前项，打开预览
      this.hideCurrentItem();
      MediaPreview.open(getUIContext(), this.options);
    });
  }

  // 生成唯一共享元素ID
  func getGeometryId(): string {
    return "media_item_" + this.index;
  }
}

模块 2：高级定制能力开发

1. 缩略图自定义：实现thumbBuilder构建器，支持业务侧自定义媒资缩略图的渲染样式（如添加圆角、水印、播放按钮）；

2. 预览内容自定义：实现contentBuilder构建器，支持自定义预览页内容（如图片添加文字说明、视频添加播放控制栏）；

3. 交互行为自定义：支持自定义预览页的关闭方式、手势触发阈值、动画时长等；

4. 完全自定义媒资模型：支持业务侧继承默认模型或自定义全新模型，框架需兼容泛型解析。

模块 3：工程化配套开发

1. 工程结构搭建：遵循鸿蒙仓颉语言开发规范，搭建清晰的工程结构（核心组件、模型、工具类、示例 Demo 分离）；

2. 示例 Demo 开发：实现 2 个基础 Demo—— 简单用法 Demo（快速集成）、自定义 Demo（全量定制能力展示）；

3. 开发文档编写：包含安装教程、快速开始、API 参考、自定义指南、迁移攻略等内容；

4. 单元测试：对核心组件、动画逻辑、模型解析进行单元测试，测试覆盖率不低于 80%；

5. 兼容性适配：保证在 HarmonyOS 5.0.0 (12) 及以上版本的真机 / 模拟器中正常运行，无崩溃、无兼容性报错。

本次开发对代码质量、功能体验、工程规范、兼容性四大维度制定严格的质量认证标准，所有要求需全部达标，以下为细分指标及验收标准：

维度 1：代码质量要求

1. 语法规范：所有代码遵循仓颉语言官方语法规范，无语法错误、无未定义变量、无空指针风险（利用仓颉内存安全特性）；

2. 代码结构：组件化封装，高内聚低耦合，核心逻辑与 UI 渲染分离，工具类抽离复用，禁止冗余代码；

3. 命名规范：类、结构体、方法、变量命名遵循驼峰命名法，常量全大写，命名语义化，禁止拼音 / 英文混合；

4. 注释规范：公共类、公共方法、核心逻辑必须添加详细注释，注释覆盖率不低于 70%，支持文档自动生成；

5. 性能优化：实现媒资懒加载，避免一次性加载所有资源；图片渲染使用缓存机制，防止 OOM；动画使用原生属性动画，禁止使用耗时的自定义绘制。

维度 2：功能体验要求

2.1 基础功能验收标准

2.2 一镜到底动画验收标准

1. 入场动画：点击列表项后，卡片平滑过渡到预览页，位置、宽高匹配精准，无偏移、无拉伸；

2. 出场动画：关闭预览页后，预览内容平滑过渡回原列表项，恢复原位置 / 宽高，无闪屏；

3. 动画流畅度：真机测试帧率稳定 60FPS，无掉帧、无卡顿，动画时长均匀，无忽快忽慢；

4. 边界场景：列表项在屏幕顶部 / 底部 / 中间位置时，动画均正常生效，无异常。

2.3 定制能力验收标准

1. 自定义模型：业务侧传入自定义模型后，框架能正常解析并渲染，无类型错误；

2. 自定义构建器：通过thumbBuilder/contentBuilder自定义的样式，能正常渲染，不影响核心功能；

3. 定制配置：修改动画时长、缩放比例等配置后，效果实时生效，无配置不生效问题。

维度 3：工程规范要求

1. 工程结构：符合鸿蒙仓颉语言工程规范，目录结构清晰，如下为推荐结构：

plaintext

media-preview-cangjie/
├── core/          // 核心组件（预览页、动画、交互）
├── model/         // 媒资模型（默认模型、枚举、泛型定义）
├── util/          // 工具类（尺寸计算、动画工具、缓存工具）
├── demo/          // 示例Demo（简单用法、自定义用法）
├── test/          // 单元测试用例
├── README.md      // 项目说明文档
└── CHANGELOG.md   // 版本更新日志

2. 依赖管理：无多余第三方依赖，仅依赖鸿蒙原生 API，降低集成成本；

3. 开源协议：遵循 Apache-2.0 开源协议，工程中包含 LICENSE 文件，所有代码无版权问题；

4. 文档完整性：开发文档包含安装教程、快速开始、API 参考、自定义示例、常见问题，内容准确、可落地，新手能快速集成。

维度 4：兼容性与稳定性要求

1. SDK 适配：在 HarmonyOS 5.0.0 (12) 及以上版本的真机 / 模拟器中，所有功能正常运行，无兼容性报错；

2. 设备适配：支持手机、平板等鸿蒙设备，自适应不同屏幕尺寸，预览内容无拉伸、无变形；

3. 稳定性：连续预览 100 + 张图片 / 10 + 个视频，无崩溃、无内存泄漏，内存占用稳定；

4. 边界场景：处理空媒资列表、无效媒资地址、超大尺寸图片、超长视频等边界场景，无崩溃，有友好的错误提示。

维度 5：交付物完整性要求

最终需交付完整可运行的工程代码+配套文档+示例 Demo，具体包含：

1. 仓颉语言编写的完整框架代码，可直接通过鸿蒙开发工具编译运行；

2. 详细的开发文档（Markdown 格式），包含所有使用指南和 API 说明；

3. 可直接运行的示例 Demo，包含基础用法和自定义用法；

4. 单元测试用例，可直接执行并通过所有测试；

5. LICENSE 文件（Apache-2.0）、README.md、CHANGELOG.md。