## 所需插件 **超能力插件：** 必须对使用此技能的所有工作处于活动状态。在整个构建管道中使用——设计决策、代码生成、调试、质量检查以及它提供增强功能的任何任务。如果超级大国提供了更好的方法来完成某件事，那么优先选择它而不是默认方法。 # Android PDF 导出（原生 PdfDocument）使用内置的“android.graphics.pdf.PdfDocument” API 从任何 Android 屏幕生成专业品牌 PDF 文档。零外部依赖——纯 Canvas 绘图。支持 A4 纵向/横向、多页分页、信头、表格、摘要卡、信息部分、状态徽章和图表。 ## 概述 **库选择：** 本机`android.graphics.pdf.PdfDocument`（0 KB 添加到APK）。 iText（AGPL 许可证）、PDFBox-Android（自 2023 年以来已过时）和 OpenPDF（需要 java.awt hack）等替代方案均被拒绝。 **架构：** 核心“DmsPdfGenerator”对象提供可重用的绘图基元。每个模块的导出器（销售、库存、网络）为每个屏幕组成这些原语。 `PdfExportHelper` 通过 `FileProvider` 处理文件 I/O 和共享。核心/pdf/ DmsPdfGenerator.kt — 可重复使用的绘图基元（信头、表格、卡片、页脚） PdfExportHelper.kt — 保存到缓存 + 通过 FileProvider Intent 共享核心/用户界面/组件/ PdfExportButton.kt — 可重复使用的 TopAppBar 按钮（图标 +“PDF”标签）每模块导出器（每个功能模块一个对象）： SalesReportPdfExporter.kt — 销售报告 + 发票列表 InventoryPdfExporter.kt — 库存水平、采购订单/转移/调整详细信息 + 列表 NetworkPdfExporter.kt — 经销商列表/详细信息、谱系 ## 依赖关系 **无。** 仅使用 Android SDK 类： * `android.graphics.pdf.PdfDocument` * `android.graphics.Canvas`、`Paint`、`TextPaint`、`Typeface`、`Color` * `android.text.StaticLayout`, `android.text.TextUtils` * `androidx.core.content.FileProvider` （已经在大多数项目中） ## 第 1 步：FileProvider 设置 ### AndroidManifest.xml <提供商 android:name="androidx.core.content.FileProvider" android:authorities="${applicationId}.fileprovider" 安卓：导出=“假” 机器人：grantUriPermissions =“true”> <元数据 android:name="android.support.FILE_PROVIDER_PATHS" android:resource="@xml/file_paths" /> ### res/xml/file_paths.xml（新） <路径> <缓存路径名称=“pdf_exports”路径=“pdf_exports/”/> ## 步骤 2：PdfExportHelper 将 PdfDocument 保存到应用程序的缓存目录并启动共享表或 PDF 查看器。对象 PdfExportHelper { 有趣的exportAndShare（上下文：上下文，文档：PdfDocument，文件名：字符串，标题：字符串）{ 尝试{ val file = savePdfToCache(上下文、文档、文件名) sharePdf（上下文、文件、标题） Toast.makeText(context, context.getString(R.string.pdf_export_success), Toast.LENGTH_SHORT).show() } catch (e: 异常) { Toast.makeText(context, context.getString(R.string.pdf_export_error), Toast.LENGTH_SHORT).show() }最后{ 文档.close() } } 私人乐趣 savePdfToCache（上下文：上下文，文档：PdfDocument，文件名：字符串）：文件 { val dir = File(context.cacheDir, "pdf_exports").apply { mkdirs() } val sanitized = filename.replace(Regex("[^a-zA-Z0-9._-]"), "_") val 文件 = 文件（目录，“$sanitized.pdf”） file.outputStream().use { document.writeTo(it) } 返回文件 } 私人乐趣 sharePdf（上下文：上下文，文件：文件，标题：字符串）{ val uri = FileProvider.getUriForFile(context, "${context.packageName}.fileprovider", 文件) val 意图 = Intent(Intent.ACTION_SEND).apply { 类型=“应用程序/pdf” putExtra(Intent.EXTRA_STREAM, uri) putExtra(Intent.EXTRA_SUBJECT, 标题) addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION) } context.startActivity(Intent.createChooser(intent, context.getString(R.string.pdf_share))) } } ## 步骤 3：核心 PDF 生成器 `DmsPdfGenerator` 对象提供所有可重用的绘图函数。每个函数都采用一个“Canvas”（当前的 Y 位置）来绘制内容，然后返回新的 Y 位置。 ### 常量和类型对象 DmsPdfGenerator { // 以 PostScript 点为单位的 A4 尺寸常量值 A4_WIDTH = 595 常量值 A4_HEIGHT = 842 常量值 A4_LAND_WIDTH = 842 常量值 A4_LAND_HEIGHT = 595 常量 VAL MARGIN = 40f // 品牌颜色（根据项目自定义） val BRAND_RED = Color.rgb(198, 40, 40) // #C62828 val HEADER_BG = Color.rgb(176, 228, 252) // #B0E4FC（表头） val ALT_ROW = Color.rgb(248, 249, 250) // #F8F9FA（交替行） val SUMMARY_BG = Color.rgb(240, 244, 248) // 摘要卡背景 val ACCENT_BLUE = Color.rgb(32, 107, 196) // #206BC4（KPI 值） val TEXT_BLACK = Color.rgb(33, 37, 41) val TEXT_GRAY = Color.rgb(108, 117, 125) val DIVIDER_GRAY = Color.rgb(200, 200, 200) 数据类 FranchiseInfo( 值名称：字符串， val 地址：字符串？， val 电话：字符串？， val 电子邮件：字符串？， valtaxId：字符串？， val 货币：字符串）数据类 TableColumn( val 标头：字符串， val widthWeight：浮点数， val 对齐：Paint.Align = Paint.Align.LEFT ） } ### 页面管理对于 createDocument()：PDFDocument = PDFDocument() fun startPage(doc: PDFDocument, pageNum: Int, Landscape: Boolean = false): PDFDocument.Page { val w = if ( 横向 ) A4_LAND_WIDTH else A4_WIDTH val h = if ( 横向 ) A4_LAND_HEIGHT else A4_HEIGHT val pageInfo = PDFDocument 。页面信息。生成器（w，h，页码）。创造（）。返回文档。起始页（页面信息） } } 对于 newPageIfNeeded( doc: PDFDocument, currentPage: PDFDocument.Page, y：Float，pageNum：Int，landscape：Boolean，页脚用户：字符串 ): 三重 < PDFDocument 。页、浮点数、整数 > { val ph = if ( 横向 ) A4_LAND_HEIGHT else A4_HEIGHT if ( y < ph -- 50f -- MARGIN ) return Triple ( currentPage , y , pageNum ) // 用页脚结束当前页面 drawFooter ( currentPage . canvas , pageNum , -1 , footerUser , 如果（横向）A4_LAND_WIDTH，否则A4_WIDTH，ph） doc.finishPage(当前页) // 开始新页面 val newNum = 页数 + 1 val newPage = startPage ( doc , newNum , 横向 ) ; 返回三重 ( newPage , MARGIN + 10f , newNum ) } } ### 绘图函数每个函数在给定的 Y 位置绘制内容并返回新的 Y： // ── 信头 ── 有趣的drawLetterhead（canvas：Canvas，y：Float，logo：Bitmap？信息：特许经营信息，页面宽度：Int）：Float // 徽标 (50x50)、特许经营名称（红色 14 磅粗体）、地址/电话/电子邮件（9 磅灰色）、分隔线 // ── 报告标题 ── 有趣的drawReportTitle（画布：画布，y：浮动，标题：字符串，副标题：字符串？ = null , pageWidth : Int ): 浮动 // 居中标题（14pt 球大写），可选副标题（10pt 灰色） // ── 总结卡 ── 有趣的drawSummaryCards（画布：画布，y：浮动， items : List < Pair < String , String >> , pageWidth : Int ): Float // KPI 框行：标签（9pt 灰色）+ 值（13pt 粗体蓝色强调） // ── 数据表 ── 有趣的drawTable（画布：画布，y：浮动，列：列表，行：列表<列表<字符串>>，页宽：Int，总计行：列表<字符串>？ = null ): 浮动 // 标题行（浅蓝色背景）、数据行（交替）、可选总计页脚 // 通过\n支持多行单元格（第一行正常，第二行较小灰色） // ── 信息部分 ── fun drawInfoSection(canvas: Canvas, y: Float, title: String? items : List < Pair < String , String >> , pageWidth : Int ): Float // 详细信息屏幕的键值对（标签：值格式） // ── 状态徽章 ── 有趣的drawStatusBadge（画布：画布，y：浮动，状态：字符串， bgColor：Int，pageWidth：Int）：浮动 // 带有白色文本的居中彩色圆角矩形 // ── 图表位图 ── 有趣的drawChartBitmap（画布：画布，y：浮动，位图：位图，页宽 : Int ): 浮点数 // 缩放位图以页面为中心，最大高度 250pt // ── 页脚 ── 有趣的drawFooter（canvas：Canvas，pageNumber：Int，totalPages：Int，生成者：字符串，页面宽度：整数，页面高度：整数） // 底部“由 X 在 DATE 生成”（左）+“第 N 页，共 M”（右） ### 表实现（关键细节）表是最复杂的组件。主要特点：有趣的绘图表（ canvas：画布，y：浮动，列：列表，行：列表<列表<字符串>>，页面宽度：整数，总计行：列表<字符串>？ = 空 ): 浮点数 { val 内容宽度 = 页宽 - 2 * 边距 val TotalWeight = columns.sumOf { it.widthWeight.toDouble() }.toFloat() val 行高 = 18f val 单元格内边距 = 4f // 根据权重计算列位置 val colPositions = mutableListOf() var xPos = 保证金 columns.forEach { 列 -> colPositions.add(xPos) xPos += (col.widthWeight /totalWeight) * contentWidth } // 标题行（浅蓝色背景，粗体白色文本） // ... // 数据行（交替背景，多行支持） rows.forEachIndexed { rowIdx, 行 -> val hasMultiLine = row.any { it.contains('\n') } val thisRowHeight = if (hasMultiLine) rowHeight + 10f else rowHeight if (rowIdx % 2 == 1) drawAltBackground(...) row.forEachIndexed { colIdx, 值 -> if (value.contains('\n')) { // 多行：第一行正常 8pt，第二行 7pt 灰色 val 行 = value.split('\n', limit = 2) canvas.drawText(行[0], textX, currentY + 11f, bodyPaint) canvas.drawText(lines[1], textX, currentY + 21f, subPaint) } 否则{ canvas.drawText（值，textX，currentY + 11f，bodyPaint） } } 当前Y += thisRowHeight } // 可选总计行（与标题相同的背景） // ... } ## 步骤 4：每个模块的导出器每个导出器都是一个“对象”，每个屏幕都有一个功能。每个函数都遵循相同的模式：对象 SalesReportPdfExporter { private val formatter = NumberFormat.getNumberInstance(Locale.US).apply { 最小分数位数 = 2;最大分数位数 = 2 } private fun cfmt(c: String, v: Double) = "$c ${formatter.format(v)}" 有趣的导出热门卖家（上下文：上下文， authManager：AuthManager，报告：TopSellersReport，货币：字符串，开始日期：字符串，结束日期：字符串， dpcName：字符串？）{ val pdf = DmsPdfGenerator val doc = pdf.createDocument() val 景观 = true val pw = if (横向) DmsPdfGenerator.A4_LAND_WIDTH else DmsPdfGenerator.A4_WIDTH val ph = if (横向) DmsPdfGenerator.A4_LAND_HEIGHT else DmsPdfGenerator.A4_HEIGHT 尝试{ var page = pdf.startPage(doc, 1, 横向) var canvas = page.canvas var y = DmsPdfGenerator.MARGIN // 1.信头 val 徽标 = getBrandLogo(context) val 信息 = 特许经营信息(authManager) y = pdf.drawLetterhead（画布，y，徽标，信息，pw） // 2. 标题 + 副标题（日期范围、过滤器） y = pdf.drawReportTitle(canvas, y, "最畅销报告", buildSubtitle（上下文，开始日期，结束日期，dpcName），pw） // 3.摘要卡 val s = 报告.摘要 y = pdf.drawSummaryCards(画布, y, listOf( “卖家”到 s.totalDistributors.toString()， “发票”到 s.totalInvoices.toString()，将“收入”转换为 cfmt(货币, s.totalAmount), “BV”到 formatter.format(s.totalBv) ), 密码) // 4.数据表 val 列 = listOf( DmsPdfGenerator.TableColumn("#", 0.3f, Paint.Align.CENTER), DmsPdfGenerator.TableColumn("名称", 2f), DmsPdfGenerator.TableColumn("DPC", 0.8f), DmsPdfGenerator.TableColumn("发票", 0.6f, Paint.Align.RIGHT), DmsPdfGenerator.TableColumn("BV", 0.8f, Paint.Align.RIGHT), DmsPdfGenerator.TableColumn("金额", 1f, Paint.Align.RIGHT) ） val rows = report.rows.mapIndexed { idx, r -> listOf((idx+1).toString(), r.fullName ?: "-", r.dpcName ?: "-", r.totalInvoices.toString(), formatter.format(r.totalBv), cfmt(货币, r.totalAmount)) } y = pdf.drawTable(画布, y, 列, 行, pw, listOf( "", "总计", "", s.totalInvoices.toString(), formatter.format(s.totalBv), cfmt(货币, s.totalAmount) ）） // 5.页脚 pdf.drawFooter(canvas, 1, 1, authManager.getUsername() ?: "", pw, ph) doc.finishPage(页) // 6. 保存+分享 PdfExportHelper.exportAndShare（上下文，文档， "top_sellers_${startDate}_$endDate", "畅销商品报告") } catch (e: 异常) { 文档.close() Toast.makeText(上下文, context.getString(R.string.pdf_export_error), Toast.LENGTH_SHORT).show() } } // Helper: 从 AuthManager 构建特许经营信息私人乐趣特许经营信息（上午：AuthManager）= DmsPdfGenerator.FranchiseInfo（名称 = am.getFranchiseName() ?: "", 地址 = am.getFranchiseAddress(), 电话 = am.getFranchisePhone(), 电子邮件 = am.getFranchiseEmail(), 税号 = am.getFranchiseTaxId(), 货币 = am.getFranchiseCurrency() ?: "" ） } ## 步骤 5：PdfExportButton 组件可重复使用的 TopAppBar 操作按钮 - 比普通图标更明显。 @可组合有趣的 PdfExportButton( onClick: () -> 单位, 修饰符：修饰符=修饰符）{ 文本按钮( onClick = onClick, 修饰符 = 修饰符.padding(end = 4.dp), 形状 = RoundedCornerShape(8.dp), 颜色 = ButtonDefaults.textButtonColors( 内容颜色 = MaterialTheme.colorScheme.onPrimary ））{ 行(verticalAlignment = Alignment.CenterVertically) { 图标（Icons.Default.PictureAsPdf，contentDescription = stringResource（R.string.pdf_export），修饰符 = Modifier.size(18.dp)) 间隔（修饰符.宽度（4.dp））文本（文本=“PDF”，样式=MaterialTheme.typography.labelMedium） } } } ## 步骤 6：屏幕集成每个屏幕在其 TopAppBar 中添加 PDF 按钮并调用导出器。 ViewModel 的“authManager”必须是“internal”（而不是“private”），以便屏幕可以通过它。 // ViewModel: 公开 authManager @HiltViewModel 类 TopSellersViewModel @Inject 构造函数（私有val存储库：PosRepository， Internal val authManager: AuthManager // 内部的，非私有的 ) : ViewModel() { ... } // 屏幕：在 TopAppBar 操作中添加 PdfExportButton 顶部应用栏( 标题 = { Text(stringResource(R.string.report_top_sellers_title)) }, 行动={ if (uiState.report != null) { PdfExportButton(onClick = { SalesReportPdfExporter.exportTopSellers( 上下文，viewModel.authManager，uiState.report！！， uiState.currency、uiState.startDate、uiState.endDate、 uiState.selectedDpc?.name ） }) } }, 颜色 = TopAppBarDefaults.topAppBarColors( 容器颜色 = MaterialTheme.colorScheme.primary, titleContentColor = MaterialTheme.colorScheme.onPrimary, actionIconContentColor = MaterialTheme.colorScheme.onPrimary ）） ## 步骤 7：字符串资源导出 PDF 生成 PDF\u2026 PDF 导出成功导出 PDF 失败共享 PDF 由 %1$s 生成生成于 %1$s 第 %1$d 页，共 %2$d 期间：%1$s 至 %2$s DPC：%1$s 仓库：%1$s 报告摘要发票帐单收件人感谢您的惠顾！ ## 步骤 8：信头的特许经营信息登录 API 应返回特许经营联系信息。存储在 AuthManager 中： // AuthManager 密钥 KEY_FRANCHISE_ADDRESS = "特许经营地址" KEY_FRANCHISE_PHONE = "专营电话" KEY_FRANCHISE_EMAIL = "特许经营邮箱" KEY_FRANCHISE_TAX_ID = “特许经营税 ID” // 吸气剂 fun getFranchiseAddress()：字符串？ = securePreferences.getString(KEY_FRANCHISE_ADDRESS) fun getFranchisePhone()：字符串？ = securePreferences.getString(KEY_FRANCHISE_PHONE) fun getFranchiseEmail()：字符串？ = securePreferences.getString(KEY_FRANCHISE_EMAIL) fun getFranchiseTaxId()：字符串？ = securePreferences.getString(KEY_FRANCHISE_TAX_ID) 在登录期间从特许经营 DTO 填充“saveUserInfo()”。 ## PDF 设计规范 ### 信笺 [标志50x50] 特许经营名称 ← 14pt 粗体红色，大写 123 Main Street, City ← 9pt 灰色电话：+1 234 567 · info@co.com ← 9pt 灰色 ────────────────────────────────── ← 分隔线 ### 摘要卡 ┌──────────┬──────────┬──────────┬──────────┐ │ 标签 │ 标签 │ 标签 │ 标签 │ ← 9pt 灰色 │ 值 │ 值 │ 值 │ 值 │ ← 13pt 粗蓝色 └──────────┴──────────┴──────────┴──────────┘ ### 数据表 ┌────┬──────────────┬────────┬──────────┐ │ # │ 产品 │ 数量 │ 金额 │ ← 浅蓝色背景，粗体 ├────┼──────────────┼────────┼──────────┤ │ 1 │ 小部件 A │ 120 │ 500 美元 │ ← 白色 │ 2 │ 小部件 B │ 80 │ 320 美元 │ ← 灰色条纹 ├────┼──────────────┼────────┼──────────┤ │ │ 总计 │ 200 │ 820 美元 │ ← 浅蓝色 bg └────┴──────────────┴────────┴──────────┘ ### 页脚由管理员于 2026 年 2 月 17 日下午 2:30 生成第 1 页，共 3 页 ## 纵向与横向决策内容类型 |方向|原因 ---|---|--- 4 列或更少 |肖像|佩戴舒适 5+ 宽柱 |风景|需要水平空间发票明细|肖像|标准文档格式产品/经销商详细信息 |肖像|信息部分布局包含多列的列表 |风景|表格可读性 ## 模式与反模式 ### 做 * 对导出器使用“object”（无状态，无需 DI） * 将 `Context` 和 `AuthManager` 作为参数传递（未注入） * 使用“Paint.Align”进行列对齐（左、中、右） * 使用基于权重的列大小调整（按比例，适应页面宽度） * 当文本超过列宽时用“...”截断文本 * 通过名称+代码组合的“\n”分隔符支持多行单元格 * 将所有导出包装在 try-catch 中，并在出现错误时使用面向用户的 Toast * 在finally块中关闭`PdfDocument`（防止资源泄漏） * 清理文件名（用“_”替换特殊字符） * 使用缓存目录（由操作系统自动清理，无需存储权限） ### 不要 * 不要使用外部 PDF 库（iText AGPL、PDFBox 陈旧、OpenPDF 脆弱） * 不要对文本进行硬编码——将字符串资源用于任何面向用户的内容 * 不要跳过信头——品牌对于导出的文档很重要 * 不要忘记带有页码和“生成者”属性的页脚 * 不要使用“LazyColumn”屏幕截图作为 PDF 内容 — 使用 Canvas 绘制所有内容 * 如果屏幕需要 PDF 导出，请不要将 ViewModel 的 `authManager` 设为私有 * 不要在后台线程上创建 PDF - PdfDocument 使用 Canvas，对于典型的报告大小来说，它在主线程上的速度足够快 * 不要永久存储 PDF - 使用缓存目录，让操作系统管理清理 ## 与其他技能的整合 android-pdf-导出 ├── android-development（项目结构、MVVM、Hilt） ├── android-report-tables（ReportTable 数据输入 PDF 表格） ├── jetpack-compose-ui（PdfExportButton组件、TopAppBar集成） └── Dual-auth-rbac（AuthManager 为信头提供特许经营信息） **关键集成：** * `android-report-tables`：在 UI 中填充 `ReportTable` 的相同数据模型提供 PDF 表格行 * `dual-auth-rbac`：来自 AuthManager 的特许经营信息（姓名、地址、电话、电子邮件）赋予信笺抬头 * `jetpack-compose-ui`：`PdfExportButton` 遵循 Material 3 模式并适合 TopAppBar 操作 ## 清单 * 将 FileProvider 添加到 AndroidManifest.xml + 创建 `res/xml/file_paths.xml` * 创建`PdfExportHelper`（保存到缓存+通过Intent共享） * 使用绘图基元（信头、表格、卡片、页脚）创建“DmsPdfGenerator” * 确保登录 API 返回特许经营联系信息（地址、电话、电子邮件、tax_id） * 将特许经营信息存储在 AuthManager 中以供信头访问 * 创建每个模块的导出器对象，每个屏幕有一个函数 * 为 TopAppBar 创建可组合的“PdfExportButton” * 将 ViewModel 的`authManager`设置为`internal`（不是`private`）以用于屏幕访问 * 将 PDF 按钮添加到每个屏幕的 TopAppBar 操作中 * 添加 16 个 PDF 字符串资源（翻译为所有支持的语言） * 测试：导出 → 共享表打开 → PDF 在查看器中正确呈现

Android PDF 导出

包含技能