Fyne ( go跨平台GUI )项目实战-scanner摄像头扫码组件开发技术详解

Fyne ( go跨平台GUI )项目实战-scanner摄像头扫码组件开发技术详解

---

一、项目概述

项目名称 ：fyne-scanner

模块路径 ：gitee.com/cchmkj/fyne-scanner

开发语言 ：Go 1.25 + C (CGO)

目标平台 ：Android (arm64) / Windows (桌面测试)

技术栈 ：Fyne v2.8.0 跨平台 UI + Android NDK Camera2 + gozxing 条码解码

许可证：MIT

1.1 功能特性

特性	说明
实时摄像头扫码	基于 Android Camera2 NDK API，YUV 420 预览流直取灰度平面，gozxing 实时解码
相册图片解码	跨平台 DecodeImage()，支持 JPEG/PNG/GIF/WEBP，内置智能编码转换 (GBK→UTF-8)
扫码 UI 组件	全屏取景框 + 绿色四角标 + 动态扫描线，微信风格
手电筒控制	基于 ACamera FLASH_MODE 切换
独立发布模块	自成 Go module，外部项目一键 go get 引入
权限自动处理	CGO 直调 JNI checkSelfPermission / requestPermissions

1.2 项目定位

fyne-scanner 是一个可被任意 Fyne 项目引用的独立扫码组件 。它将 Android Camera2 NDK 的底层复杂度封装为简洁的 Scanner 接口，同时提供 ScanView / TorchButton 等即插即用的 Fyne Widget。桌面端编译为零 CGO 的纯 Go stub 实现，支持图片解码。

---

二、项目结构

FyneCamera/                          ← 主应用（演示项目）
├── main.go                          ← 主入口：BigButton + ScanView 集成
├── go.mod                           ← 根模块，replace => ./scanner
├── FyneApp.toml                     ← Fyne 应用清单
├── build.bat                        ← 一键构建 + 安装脚本
├── build_android.ps1                ← Android APK 打包流水线
├── gen_icon.ps1                     ← 应用图标生成脚本
├── push.bat                         ← 发布到 GitHub
├── push_gitee.bat                   ← 发布到 Gitee（含自动版本号）
├── debug.keystore                   ← Android 调试签名密钥库
├── test_decode.go                   ← 独立解码测试工具 (go:build ignore)
├── tools/
│   ├── apktool.jar                  ← APK 反编译/重打包工具
│   └── 1.apk
│
├── scanner/                         ← ★ 核心模块（独立 Go module）
│   ├── go.mod                       ← module gitee.com/cchmkj/fyne-scanner
│   ├── .gitignore
│   ├── scanner.go                   ← Scanner 接口 + Frame/Result 数据模型
│   ├── decode_image.go              ← 图片二维码解码（跨平台）
│   ├── scanner_android.go           ← Android Scanner 实现 (build tag: android)
│   ├── scanner_desktop.go           ← 桌面端 stub (build tag: !android)
│   ├── camera_android.go            ← Android Camera2 CGO 封装 (build tag: android && !386)
│   ├── push_to_github.bat
│   │
│   ├── ui/                          ← Fyne Widget 库（依赖 Fyne + scanner）
│   │   ├── scanview.go              ← 全屏扫码视图（摄像头预览 + 绿框蒙层 + 扫描线）
│   │   └── torch_button.go          ← 手电筒开关按钮
│   │
│   └── test/                        ← 示例应用（独立 Go module）
│       ├── go.mod                   ← module scanner/test, replace => ../
│       └── main.go                  ← 相册扫码 + API 速查示例
│
├── test/                            ← 根项目测试工具
│   └── test_jpg_code.go             ← 批量 JPG 解码测试
│
└── testScanner/                     ← 外部项目集成示例
    ├── go.mod
    ├── main.go                      ← 最简单的扫码 App
    ├── build.bat / build_android.ps1
    └── FyneApp.toml

2.1 模块层次关系

testScanner (外部项目)                  ← go get gitee.com/cchmkj/fyne-scanner
    │
    └── gitee.com/cchmkj/fyne-scanner  ← ★ 独立 Go module
         ├── scanner/    (接口 + 平台实现)
         └── scanner/ui/ (Fyne Widget 库)

FyneCamera (根项目)                     ← replace => ./scanner (本地开发)
    ├── gitee.com/cchmkj/fyne-scanner
    └── gitee.com/cchmkj/fyne-scanner/ui

---

2.2 运行效果

• 运行APP

• 开始扫码
• 扫码结果 GBK码/UTF8码自动解码

三、包设计详解

3.1 package scanner --- 核心接口层

文件 ：scanner/scanner.go

依赖：无（纯 Go 定义，零外部依赖）

数据模型

// FrameFormat 帧像素格式
const (
    FormatYUV420NV21 FrameFormat = iota  // Android 默认 YUV420 NV21
    FormatGray                            // Y 平面灰度 → gozxing 解码用
    FormatRGB
)

// Frame 摄像头帧
type Frame struct {
    Width       int
    Height      int
    Data        []byte
    Format      FrameFormat
    Orientation int       // 摄像头传感器方向 (0/90/180/270)
}

// Result 扫码结果
type Result struct {
    Text   string          // 解码后的文本内容（已 GBK→UTF-8 转换）
    Format string          // 条码格式名 (QR_CODE / CODE_128 / ...)
    Points [][2]float64    // 二维码定位点坐标
}

核心接口

type Scanner interface {
    Start(cb FrameCallback) error    // 开启摄像头，每收到一帧回调 cb
    Stop()                            // 停止摄像头并释放资源
    Decode(f Frame) (*Result, error)  // 单帧解码
    SetTorch(on bool) error           // 开关手电筒
}

func New() Scanner                    // 工厂方法 → 返回平台实现
func DecodeImage(img image.Image) (*Result, error)  // 跨平台图片解码

平台实现选择策略

编译目标	文件	实现	CGO
android	scanner_android.go + camera_android.go	Camera2 NDK 取帧 + gozxing	是
!android	scanner_desktop.go	纯 Go stub（摄像头不可用）	否

---

3.2 camera_android.go --- Android Camera2 CGO 封装

文件 ：scanner/camera_android.go

Build Tag ：android && !386

CGO LDFLAGS ：-lcamera2ndk -lmediandk -llog -landroid

关键常量 ：__ANDROID_API__ = 24

相机初始化流水线

ACameraManager_create()
    │
    └→ select_back_camera_id()           // 枚举所有相机，选 ACAMERA_LENS_FACING_BACK
        └→ ACameraManager_getCameraCharacteristics()
            └→ 读取 ACAMERA_SENSOR_ORIENTATION  // 传感器方向
    
    └→ ACameraManager_openCamera()       // 打开相机设备
    └→ AImageReader_new(1280x720, YUV_420_888)  // 创建图像读取器
    └→ ACaptureSessionOutputContainer_create()
    └→ ACameraDevice_createCaptureSession()     // 创建捕获会话
    └→ ACameraDevice_createCaptureRequest(TEMPLATE_PREVIEW)
    └→ ACaptureRequest_addTarget()
    └→ ACameraCaptureSession_setRepeatingRequest()
    └→ pthread_cond_wait(&cond)          // 等待 on_session_active 信号

帧读取机制

• on_image_available() 回调在 binder 线程，互斥锁保护全局 g_ctx
• AImageReader_acquireLatestImage() 取最新帧，丢弃旧帧
• 只提取 Y 平面 (Plane 0) → 等同于灰度图 → 可直接喂给 gozxing
• Go 侧 pollFrame() 通过 camera_get_frame() 拷贝帧数据到新 Buffer

手电筒控制

uint8_t flash_mode = on ? 2 : 0;  // ACAMERA_FLASH_MODE_TORCH=2, OFF=0
ACaptureRequest_setEntry_u8(request, ACAMERA_FLASH_MODE, 1, &flash_mode);
ACameraCaptureSession_setRepeatingRequest(session, ...);  // 重新提交请求

JNI 辅助函数

函数	功能	实现方式
get_jni_env()	获取 JNIEnv*	dlsym(JNI_GetCreatedJavaVMs) → AttachCurrentThread
get_application_context()	获取 Application Context	JNI 调用 ActivityThread.currentApplication()
check_permission()	检查权限	JNI 调用 Context.checkSelfPermission()
get_current_activity()	获取当前 Activity	反射 ActivityThread.mActivities → ArrayMap.values()
request_permission()	请求权限	JNI 调用 Activity.requestPermissions()

相机关闭顺序（关键！防止 native crash）

1. g_ctx.closing = 1                    // 阻止新帧回调
2. ACameraCaptureSession_stopRepeating()
3. ACameraCaptureSession_close()        // 停止图片回调
4. usleep(200ms)                        // 等待 binder 回调完成
5. free(frame_data)
6. ACaptureRequest_free()
7. ACameraDevice_close()                // 先关设备
8. AImageReader_delete()                // 后删 ImageReader（自动释放 ANativeWindow）
9. ACameraManager_delete()
10. pthread_cond_destroy / pthread_mutex_destroy

⚠️ 关键注意 ：不能单独调用 ANativeWindow_release()，它由 AImageReader_delete() 内部释放，否则 double-free crash。

---

3.3 decode_image.go --- 图片二维码解码

文件 ：scanner/decode_image.go

依赖：gozxing, golang.org/x/image, golang.org/x/text

解码流水线

image.Image
    │
    └→ tryDecodeWithScales()
        ├── 图片 ≤ 1280px → 原尺寸直接试
        └── 图片 > 1280px → [640, 800, 1024, 1280, 1600] 多级缩放重试
            └→ resizeBilinear()         // draw.BiLinear.Scale 保留定位图案质量
                │
    └→ tryDecodeWithBinarizers()
        ├── 策略1: HybridBinarizer      // 对大多数场景效果好
        ├── 策略2: GlobalHistgramBinarizer  // 某些图片只有它能识别
        │
    └→ tryConvertGBKToUTF8()            // 智能 GBK→UTF-8 转换

GBK 智能编码转换

许多国产二维码生成器用 GBK 编码中文但不写入 ECI 段，gozxing 默认按 ISO-8859-1 解析。本模块的检测逻辑：

1. 遍历所有 rune，判断是否全部 ≤ 0xFF（Latin-1 范围）
2. 若全部为 Latin-1 且包含高字节 (≥ 0x80) → 大概率是 GBK 被误解析
3. 提取每个 rune 的低字节组成原始 GBK 字节流
4. 使用 GB18030 解码器转为 UTF-8
5. 检测转换后是否包含中文字符（CJK Unified Ideographs U+4E00~U+9FFF 等 6 个区段）
6. 含中文则返回转换结果，否则返回原文

---

3.4 scanner_android.go --- Android Scanner 实现

文件 ：scanner/scanner_android.go

Build Tag ：android

startCameraFlow (goroutine)
    ├── openCamera(1280, 720)                    // CGO 调用 camera_init
    ├── ticker = 33ms (~30fps)                   // 轮询取帧
    ├── cam.pollFrame()                          // CGO 调用 camera_get_frame
    ├── cb(frame)                                // 回调给 ScanView 渲染预览
    └── scanner.Decode(frame)
        ├── frameToGrayImage()                   // Y 平面 → image.Gray
        ├── gozxing.NewBinaryBitmapFromImage()
        └── reader.Decode() → tryConvertGBKToUTF8()

3.5 scanner_desktop.go --- 桌面端 Stub

文件 ：scanner/scanner_desktop.go

Build Tag ：!android

• Start() 返回 "camera not supported on desktop"
• SetTorch() 返回 "torch not supported on desktop"
• Decode() 调用 decodeQR() 正常工作
• CheckPermission() 返回 true
• Log() / RequestPermission() 为空实现

---

3.6 package ui --- Fyne Widget 库

文件 ：scanner/ui/scanview.go, scanner/ui/torch_button.go

依赖：fyne.io/fyne/v2, parent scanner package

ScanView --- 全屏扫码视图

层级	组件	说明
底层	canvas.Raster → drawFrame()	摄像头灰度预览（适配 4 个方向旋转）
中层	canvas.Raster → drawOverlay()	暗色蒙层 + 绿色四角标 + 绿色扫描线
顶层	container.Border + 底部文字	半透明黑底 "将二维码放入框内，即可自动扫描"

扫描线动画：

• 60fps 刷新，每帧位移 12px
• 触底后从顶部 -4px 重新开始，循环
• 等待布局完成后才开始（viewH > 0，最多等 3s）

方向适配 (drawFrame 中的 4 种旋转)：

Orientation	Y 平面 → 显示坐标变换
0°	dst[x][y] = src[y][x] (直拷)
90°	dst[dstW-1-y][x] = src[y][x]
180°	dst[srcW-1-x][srcH-1-y] = src[y][x]
270°	dst[y][dstH-1-x] = src[y][x]

权限流程：

Start() → CheckPermission(CAMERA) 
    ├── 未授权 → 显示灰色画面 → RequestPermission() → 轮询等待最多 6s
    │   └── 仍被拒 → 返回 "权限被拒绝" → resultChan
    └── 已授权 → startScanLineAnimation() → Start() → 帧回调 + Decode
        └── 解码成功 → stop scanline → scanner.Stop() → resultChan ← 结果

TorchButton --- 手电筒开关按钮

• 圆角矩形按钮，"打开灯光" / "关闭灯光" 切换
• 点击事件通过 onTapped(on bool) 回调给外部
• MinSize = 180×56

---

3.7 main.go --- 演示应用

文件 ：main.go

自定义 BigButton

type BigButton struct { widget.BaseWidget }
// 圆角矩形 + 24px 白色粗体文字
// MinSize: 180×56

页面结构

主页面 (showMainView)
├── 标题 "扫码工具"
├── [开始扫码] [相册扫码]
├── 结果编辑框 (MultiLineEntry, 可追加)
└── [清空数据] [关闭应用]

扫码页 (startScan)
├── ScanView (全屏)
├── TorchButton (手电筒)
└── BigButton (取消扫码)

异步扫码流程

go scanView.Start()
go func() {
    result := <-scanView.ResultChan()
    fyne.Do(func() {
        appendResult(result)
        showMainView(w)
    })
}()

---

四、构建系统

4.1 环境要求

组件	版本/路径
Android SDK	D:\Android\Sdk
Android NDK Bundle	D:\Android\Sdk\ndk-bundle (API 24+)
Build Tools	35.0.0
JDK (keytool)	PATH 中可用
Go	1.25+
Fyne CLI	go install fyne.io/fyne/v2/cmd/fyne@latest
apktool	tools/apktool.jar (2.9.3)
ADB	platform-tools 已连接设备 PVKGK22C16000006

4.2 构建流水线 (build_android.ps1)

┌──────────────────────────────┐
│ 1. fyne package               │  → FyneCamera.apk (基础 APK)
│    -os android/arm64          │
├──────────────────────────────┤
│ 2. apktool decode             │  → decoded/
├──────────────────────────────┤
│ 3. Icon injection             │  → 5 densities mipmap
│    (48/72/96/144/192 px)      │
├──────────────────────────────┤
│ 4. AndroidManifest patch      │  → CAMERA permission + minSdk=24 + icon
├──────────────────────────────┤
│ 5. apktool build              │  → FyneCamera_unsigned.apk
├──────────────────────────────┤
│ 6. zipalign -f 4              │  → FyneCamera_aligned.apk
├──────────────────────────────┤
│ 7. apksigner sign             │  → FyneCamera-signed.apk
│    (debug.keystore)           │
├──────────────────────────────┤
│ 8. Cleanup intermediate files │
├──────────────────────────────┤
│ 9. adb install -r             │  → 设备
└──────────────────────────────┘

关键 NDK 环境变量：

$env:CGO_LDFLAGS = "-L$SysrootLib\aarch64-linux-android\24 -L..."

确保链接器能找到 libcamera2ndk.so / libmediandk.so（API 24+）。

4.3 APK 注入说明

fyne package 生成的 APK 不含 CAMERA 权限且 minSdkVersion 默认为 21，通过 apktool 反编译后注入：

注入的 AndroidManifest 片段：

<uses-permission android:name="android.permission.CAMERA"/>
<uses-feature android:name="android.hardware.camera" android:required="false"/>
<uses-feature android:name="android.hardware.camera.autofocus" android:required="false"/>
<!-- minSdkVersion="24" -->
<!-- android:icon="@mipmap/ic_launcher" -->

4.4 一键构建

build.bat        → PowerShell 构建 + adb install → 设备

---

五、发布系统

5.1 版本号自动管理

push_gitee.bat 自动读取 git tag，语义化递增 patch 号：

v0.1.0 → v0.1.1 → v0.1.2 → v0.1.3 → ...

5.2 发布到 Gitee

push_gitee.bat   → 自动版本号 → commit → tag → push

5.3 Go 环境配置（使用者需设）

go env -w GOPRIVATE=gitee.com
go env -w GOINSECURE=gitee.com
git config --global url."https://用户名:token@gitee.com/".insteadOf "https://gitee.com/"

---

六、外部项目集成指南

6.1 go.mod 配置

module your-project

go 1.25.0

require gitee.com/cchmkj/fyne-scanner v0.1.3

6.2 本地开发时用 replace

replace gitee.com/cchmkj/fyne-scanner => ../FyneCamera/scanner

6.3 代码集成示例

package main

import (
    "gitee.com/cchmkj/fyne-scanner"
    "gitee.com/cchmkj/fyne-scanner/ui"

    "fyne.io/fyne/v2"
    "fyne.io/fyne/v2/app"
    "fyne.io/fyne/v2/container"
)

func main() {
    a := app.New()
    w := a.NewWindow("扫码")

    scanView := ui.NewScanView()
    torchBtn := ui.NewTorchButton(func(on bool) {
        scanView.SetTorch(on)
    })

    w.SetContent(container.NewBorder(nil, torchBtn, nil, nil, scanView))
    
    go scanView.Start()
    go func() {
        result := <-scanView.ResultChan()
        // 处理扫码结果
    }()

    w.ShowAndRun()
}

6.4 仅使用图片解码（无 UI / 无 Fyne）

import (
    "image"
    _ "image/jpeg"
    "os"

    "gitee.com/cchmkj/fyne-scanner"
)

func main() {
    f, _ := os.Open("qrcode.jpg")
    defer f.Close()
    img, _, _ := image.Decode(f)
    result, err := scanner.DecodeImage(img)
    if err == nil {
        fmt.Println(result.Text)
    }
}

---

七、外部依赖清单

7.1 scanner 模块直接依赖

包	版本	用途
fyne.io/fyne/v2	v2.8.0	UI 框架（仅 scanner/ui 子包使用）
github.com/makiuchi-d/gozxing	v0.1.1	二维码/条码解码核心
golang.org/x/image	v0.24.0	draw.BiLinear.Scale 双线性缩放
golang.org/x/text	v0.40.0	GB18030 中文编码转换

7.2 Android CGO 系统库

库	用途
libcamera2ndk.so	NDK Camera2 API
libmediandk.so	AImageReader
liblog.so	__android_log_print 日志
libandroid.so	基础 Android NDK 函数

---

八、关键技术决策

8.1 为什么不直接用 CameraX 或 Camera1？

方式	问题
CameraX (Java API)	Fyne/gomobile 无法直接调用 AndroidX，需要写 JNI 桥接
Camera1 (android.hardware.Camera)	API 21 已废弃，新设备兼容性差
Camera2 NDK ✅	纯 C API，CGO 直接调用，零 Java 层，性能最优

8.2 为什么只取 Y 平面做解码？

Y 平面即灰度图像。二维码解码只需要明暗对比信息，不需要 UV 色彩分量。直接取 Y 平面：

• 省去 YUV→RGB 转换开销
• 数据量减半（1280×720 全 YUV420 = ~1.38MB，Y 平面 = 0.92MB）
• gozxing 解析灰度图速度最快

8.3 为什么用 apktool 注入而非 gradle 构建？

Fyne 的 fyne package -os android 生成的是 gradle-free 的 APK。要添加 CAMERA 权限和修改 minSdk 最简洁的方式就是 apktool decode → 修改 → rebuild。

8.4 为什么模块拆分为两个 repo？

scanner/ 是独立 Go module (gitee.com/cchmkj/fyne-scanner)：

• 独立发布 ：其他项目直接 go get 引入
• 独立版本管理：语义化版本标签 (v0.1.x)
• 依赖隔离：桌面端使用方不拉 Android NDK/CGO 的构建配置

---

九、日志与调试

9.1 Android Logcat

adb logcat -s fyne_camera

所有 CGO 日志（camera_android.go 中的 LOGI/LOGE）和 Go 侧 scanner.Log() 调用均使用 tag "fyne_camera"。

9.2 GBK 转换调试日志

tryConvertGBKToUTF8() 在 Android 端输出详细诊断日志：

• 输入字符串长度
• allLatin1 / hasHighByte 检测结果
• 原始字节长度
• 解码后是否含中文

---

十、已知问题与注意事项

#	问题	影响	解决方案
1	gomobile/fyne package 内不继承主机 Go env	外部项目构建 Android APK 时无法下载 Gitee 模块	添加 replace 指向本地 scanner
2	ANativeWindow_release 与 AImageReader_delete 双重释放	native crash	严格按关闭顺序，不单独调 ANativeWindow_release
3	__ANDROID_API__ 默认 16，Camera2 API 未暴露	编译报错符号未定义	CGO 文件 #undef __ANDROID_API__ → #define 24
4	89GBK 二维码（无 ECI segment）中文乱码	gozxing 按 ISO-8859-1 解析	tryConvertGBKToUTF8 智能检测并转换
5	安装时签名不匹配	不同 debug.keystore 冲突	adb uninstall 卸载旧版后重装
6	session 关闭后 binder 线程仍回调 on_image_available	use-after-free crash	closing 标志 + 200ms 等待 binder 回调排空

---

十一、文件清单

源代码文件（9 个）

文件	行数	平台	职责
main.go	183	all	演示应用
test_decode.go	36+	all	独立解码测试
scanner/scanner.go	47	all	接口 + 数据模型
scanner/decode_image.go	221	all	图片解码 + GBK 转换
scanner/scanner_android.go	130	android	Camera2 + gozxing 实时解码
scanner/scanner_desktop.go	75	!android	桌面端 stub
scanner/camera_android.go	638	android	CGO Camera2 + JNI 权限
scanner/ui/scanview.go	388	all	全屏扫码视图
scanner/ui/torch_button.go	62	all	手电筒按钮

构建脚本（4 个）

文件	说明
build.bat	根项目一键构建
build_android.ps1	Android APK 完整打包流水线
gen_icon.ps1	生成 512×512 应用图标
push_gitee.bat	发布到 Gitee（自动版本号）

十二、本项目组件在以下几个方面对 Fyne 生态具有实质性的扩展意义：

---

1、填补 Fyne 原生能力缺口

Fyne 作为跨平台 GUI 框架，官方仅提供基础 UI 组件（按钮、标签、输入框等），以下能力原生完全缺失：

缺失能力	本项目填补方式
摄像头实时预览	Camera2 NDK → Go Frame → canvas.Raster 逐帧渲染
条码/二维码扫描	gozxing 实时解码 + GBK 编码智能转换
手电筒控制	ACamera FLASH_MODE_TORCH CGO 封装
Android 运行时权限	JNI 直调 checkSelfPermission / requestPermissions

这 4 项能力覆盖了大量实际业务场景（扫码登录、商品条码、票务核验等），Fyne 开发者不必重复造轮子。

---

2、验证 Fyne 跨平台架构的正确性

本项目是 Fyne "一次编写、分层实现" 架构理念的最佳实践验证：

Scanner 接口（跨平台纯 Go 定义）
    │
    ├── Android 实现：CGO + NDK Camera2            ← 2000+ 行复杂 C/Go 混编
    ├── 桌面实现：纯 Go stub（零 CGO）              ← 75 行
    └── UI 组件：Fyne Widget 标准接口               ← 独立子包，复用 Scanner 接口

关键验证点：

• 依赖隔离 ：桌面端 go build 不触发任何 CGO 编译，构建秒过
• 接口抽象正确 ：Scanner 接口的 Start/Stop/Decode/SetTorch 四个方法足够表达所有平台的扫码语义
• Fyne Widget 扩展机制可行 ：widget.BaseWidget + canvas.Raster + widget.NewSimpleRenderer 的组合能承载摄像头预览流这种重型渲染

---

3、为 Fyne 社区提供复用范式

3.1 Go Module 化发布

将组件发布为独立 Go module（gitee.com/cchmkj/fyne-scanner），其他项目一行 go get 即可集成。这为非官方组件如何接入 Fyne 生态提供了模板。

3.2 Fyne Widget 扩展的标准模式

ScanView 和 TorchButton 展示了如何正确地：

// 1. 继承 BaseWidget
type ScanView struct {
    widget.BaseWidget
    // ...
}

// 2. ExtendBaseWidget 绑定自身
func NewScanView() *ScanView {
    sv := &ScanView{...}
    sv.ExtendBaseWidget(sv)      // ← 关键：传入自己的指针
    return sv
}

// 3. 实现 CreateRenderer 返回层级容器
func (sv *ScanView) CreateRenderer() fyne.WidgetRenderer {
    return widget.NewSimpleRenderer(
        container.NewStack(
            sv.raster,   // 底层：canvas.Raster 动态渲染
            sv.overlay,  // 中层：半透明蒙层 + 动画
            tipLayer,    // 顶层：文字提示
        ),
    )
}

这个模式------用 container.NewStack 叠层 + canvas.Raster 做高效逐帧渲染------是 Fyne 文档中未详述但实践中最高频的自定义 Widget 方式。

3.3 Fyne + Android CGO 集成范例

fyne package -os android 生成的 APK 本质上是一个 gomobile 应用。本项目展示了如何在不修改 Fyne 源码的情况下，通过 CGO 深度集成 Android 原生 API：

• dlsym(JNI_GetCreatedJavaVMs) 在 static library 中获取 JVM 引用
• 反射 ActivityThread 内部结构获取 Activity 和 Context
• 绕过 gomobile 的 Java 层限制，直接调用 SDK API

这为其他需要 Android 原生能力（传感器、蓝牙、WiFi Direct 等）的 Fyne 项目提供了技术路线参考。

---

4、揭示 Fyne 当前框架的局限性

局限	表现	本项目如何绕过
fyne package 不继承主机 Go env	Gitee 私有库无法下载	本地开发用 replace 指令
APK 不注入 CAMERA 权限	Camera2 API 调用失败	apktool decode + 注入 AndroidManifest
默认 API 21，Camera2 API 不可见	编译符号未定义	#undef __ANDROID_API__ → #define 24
CGO LDFLAGS 默认不链接 camera2ndk	链接报错	手工设置 CGO_LDFLAGS 指向 API 24 sysroot
Fyne 无官方线程模型约定	gomobile 异步回调到 C 线程	fyne.Do() 包裹所有 UI 刷新

这些踩坑记录本身就是对 Fyne 框架的有价值的补充说明。

---

5、总结

本项目不是"Fyne 的一个应用"，而是"Fyne 生态的一个能力扩展层"。

它把 Android Camera2 NDK 的 2000+ 行 C/Go 混合代码封装为 4 个方法的 Scanner 接口，把扫码 UI 封装为 2 个即插即用的 Fyne Widget。对 Fyne 社区而言，它证明了：

1. Fyne Widget 系统可以支撑高频摄像头渲染
2. CGO 可以安全地与 Fyne 事件循环共存
3. Go module 化是 Fyne 组件的正确分发方式
4. Android 原生 API 的集成有可复用的技术路径

文档版本：1.0

最后更新：2026-07-25

适用模块版本：v0.1.3+