搞鸿蒙应用开发的朋友尤其是企业开发者身份的做到“分享”这块十有八九会碰到一个比写代码本身更磨人的环节——配置目标应用名单。我前段时间在公司内部的一个HarmonyOS NEXT项目里接手Share Kit集成功能代码半小时写完反而是“目标应用名单”这一栏折腾了一整天分享面板要么不按预期过滤要么目标App压根不出现最后翻文档、查审核状态、对包名才发现问题全出在AGC侧的企业应用配置上。这篇就专门把Share Kit系列里的企业应用“目标应用名单”配置环节讲透适合正在做鸿蒙应用分享功能、且账号是企业开发者身份的同学参考。先说清楚它是什么、解决什么问题。Share Kit是鸿蒙提供的系统级分享能力让应用能通过系统分享面板把文本、图片、文件等数据分享到其他已接入Share Kit的应用“目标应用名单”则是企业应用在AGCAppGallery Connect后台维护的一份“允许分享到哪些应用”的清单。配置它的核心目的是管控分享范围——应用只能分享到名单内的目标应用避免企业内部数据被分享到无关App。后面我会把个人应用和企业应用的差异、配置流程、代码侧对齐方式和常见坑一起梳理出来包你在配置这步不再反复折腾。1. 企业应用为什么要配置目标应用名单1.1 Share Kit的分享链路与名单在其中的位置先把这个功能的链路捋清楚。用户在鸿蒙设备上点击“分享”你的应用调用Share Kit的接口系统弹出一个分享面板面板里列出若干个可以接收分享内容的App用户选中之后系统拉起目标App并传数据。就这么一条链路看起来简单实际上系统要判断“该展示哪几个App”时会同时参考两个维度的信息。从接收方角度来看一个App需要在module.json5里通过skills声明自己支持哪些分享动作、能接收哪些数据类型同时也要在AGC侧开通Share Kit服务。从分享方也就是我们正在开发的这个应用角度来看如果我们配置了“目标应用名单”系统在完成接收方匹配后还会按这份名单再过滤一遍名单之外的应用哪怕它声明了能接收分享也不会出现在你的分享面板里。这个“再过滤”的动作是关键中的关键。个人开发者应用不配名单默认分享面板会把所有已接入Share Kit的应用都列出来这在普通工具类App里没什么问题但企业场景完全不一样。企业应用往往涉及内部文档、经营数据、账号信息如果用户随手一点分享面板里跳出一堆第三方社交、网盘、笔记类应用数据流向就完全失控了。配置目标应用名单本质上是把“能接收我分享内容的应用集合”从“所有已接入的应用”收敛成“经过审批的固定清单”。1.2 个人应用与企业应用的配置差异我最早接触Share Kit时有个误区以为目标应用名单是所有应用都要配的后来在AGC后台对比个人账号和企业账号才发现差别个人开发者的应用分享范围默认走宽口径系统把已接入Share Kit的App都展示出来除非你主动去配置限制企业开发者的应用在分享服务的能力范围内需要显式维护目标应用名单名单没配好分享能力就不完整。这里说的“企业应用”从应用类型看至少包含两类一是企业开发者账号在应用市场上发布的商用App二是企业内部自用、通过受控渠道分发的企业专属应用。两类应用在分发方式上不同但在Share Kit的目标应用名单逻辑上是统一的——都要求企业主体认证后在AGC侧明确“谁可以接收我的分享”。如果你是以公司主体完成认证、在AGC后台看到应用类型是“企业应用”那这篇内容对你都适用。1.3 为什么名单要放在云端而不是写死在代码里这个问题我经常被同事问到名单里的目标应用为什么不能在代码里直接写个数组反正分享前我自己过滤一遍不就行了理论上当然可以但现实中不推荐。第一名单在云端配置你调整分享范围不用重新出包发版审核生效后所有版本的应用同步生效。第二企业应用一般有合规审计要求云端名单配合AGC后台可以追溯“谁在什么时间改了什么”比代码里埋一个过滤逻辑要透明得多。第三系统会在拉起分享面板时根据云端名单做服务端校验如果只靠客户端过滤那签名不一致或者被篡改的包很容易绕过。所以名单放在AGC后台不单是一个配置习惯问题更是分享链路里一道官方管控防线。这道防线也有代价云端配置的生效需要走审核流程有周期不能指望提交后立刻生效。所以我才一直强调做企业应用的团队必须把名单配置当作正式开发任务排期而不是上线前的临时动作否则很容易卡版本。2. 配置目标应用名单的完整流程2.1 配置前的前置条件自查进AGC配置之前先把下面的条件核对一遍缺哪一项后面都会卡住。顺手整理了一个自查清单可以直接对着检查检查项说明常见缺失表现企业开发者认证账号已完成企业主体认证营业执照、对公账户验证等后台不显示企业应用相关能力应用信息完整包名、签名、版本信息已提交应用状态正常添加目标应用时搜索不到自己的应用Share Kit服务开通AGC对应应用下已开通Share Kit服务目标应用名单入口不可用目标应用包名清单已整理好要分享到的应用包名和用途配置时反复提交审核这里有个经验供参考。目标应用包名清单最好在项目需求阶段就拉出来跟业务方逐个确认“为什么需要分享到这个App”。我见过不少团队在配置时临时问产品“到底要分享到哪几个”结果凑了一堆用不上的包名审核反而容易被驳回。原因很简单企业应用的名单不是越全越好而是越准越好审批方看到的应该是一份可解释的分享关系清单而不是来者不拒的大杂烩。2.2 AGC后台的逐步配置操作不同控制台版本的菜单层级会有一些差别但核心路径是稳定的。我以当前主流版本的操作为例按步骤走一遍。第一步登录AppGallery Connect进入“我的应用”选择你正在开发的那款企业应用。第二步在应用左侧导航栏进入“开发服务”或者在增长能力相关模块里找到“分享服务Share Kit”进入后能看到分享能力概览页。第三步找到“目标应用名单”或“分享范围设置”入口点击进入名单管理页。这里会展示当前已配置的目标应用列表以及每个应用的审核状态。第四步添加目标应用。常见有三种添加方式通过应用名称搜索、通过包名精确添加、从推荐列表里勾选。推荐列表里通常包含系统预置应用和已接入Share Kit的常用应用第三方应用更多依赖前两种方式。第五步配置生效范围。部分版本支持针对不同的分享数据格式文本、图片、文件等设置不同的目标应用集合比如文本可以分享到A和B图片只能分享到A按业务需求勾选就行。第六步提交审核。配置完成之后提交AGC会把目标应用名单作为一个变更项提交给审核。审核通过后名单会同步到服务端并按规则在所有版本中生效。逐步走完其实很快真正花时间是前期的包名整理和审核等待。实际用时大概是这样菜单操作十五分钟审核等待看运气从少数几个小时的极速通过到两三天都有可能所以千万别把它当成上线当天的操作项。2.3 三种添加方式怎么选我一向建议优先用包名精确添加其次是推荐列表最后才是名称搜索。为什么这么说包名是应用在系统里的唯一标识精确添加可以避免“名字搜索出来好几个同名应用分不清该选哪个”的问题。搜索名称往往会出现推广名、显示名、历史名混杂的情况企业应用的审计记录里如果包名写错了后面排查分享面板不显示目标App时你根本没法判断是配置问题还是匹配问题。推荐列表适合添加系统预置应用比如备忘录、邮件这类。系统应用在包名搜索里不一定搜得到但推荐列表已经帮你归好类勾选就行了。至于批量导入那是名单数量很多的场景比如企业内部要覆盖几十个业务系统App按模板整理好之后再导入比一个一个点效率高得多。就算这样导入之后也要逐个检查包名和审核状态别指望一把梭完事。3. 名单背后的工程实现与代码侧对齐3.1 分享方代码与云端名单的联动配置完名单之后代码侧其实不需要为名单做额外过滤——系统在拉起分享面板时已经把名单逻辑处理好。分享方要做的是正常调用Share Kit的分享接口把需要分享的数据交给系统就行。以HarmonyOS NEXT的TypeScript接口为例大概是这样的调用方式具体的API签名会跟随官方SDK版本迭代这里给的是稳定核心写法import { systemShare } from kit.ShareKit; import { Want } from kit.AbilityKit; let data: systemShare.SharedData { shareType: systemShare.SharedDataType.URI, data: file://docs/example.docx }; let want: Want { bundleName: com.example.targetapp }; systemShare.systemShare(data, want) .then(() { // 分享面板已拉起 }) .catch((err) { // 处理分享失败 });注意一个细节即使你的应用配置了目标应用名单调用分享接口时仍然可以传want指定某个目标应用但最终用户看到的还是一个系统面板里面展示的是“名单内且匹配当前数据类型”的应用。也就是说名单是“过滤”want是“提示”两者并不冲突。面板拉起后系统已经帮你把不可分享的App隐藏掉代码层面不需要再写任何判断逻辑。3.2 接收方目标应用需要做什么才能被面板收录这一点容易被忽略你把某个App加进名单只是“允许它出现在你的分享面板里”但如果这个App自己没声明能接收分享数据它照样不会出现。所以做企业应用配置时往往不只是你的研发在忙接收方App的研发也得配合改配置。接收方需要在module.json5里通过skills声明支持分享动作和数据类型一个典型的配置片段长这样{ module: { skills: [ { entities: [entity.system.share], actions: [ohos.want.action.viewData], uris: [ { scheme: file, type: text/plain }, { scheme: file, type: image/* } ] } ] } }entities里的entity.system.share表示这个应用参与系统分享actions里的ohos.want.action.viewData表示可以打开数据内容uris里的type则定义接收什么类型的数据。分享文本、分享图片、分享文件对应到接收方是不同类型和scheme的组合哪一项没声明对分享内容就会在拉起时失败。这段配置的真实作用是向系统注册“我能接收什么”。目标应用名单解决的是“允许谁分享给我”skills解决的是“我接得了什么”两个条件同时满足了你的企业分享链路才会顺畅。不少团队只盯着名单配置忽略接收方侧的声明结果两个应用都配好了面板里还是找不到人就是这个原因。3.3 配置生效与灰度验证名单提交审核通过之后不是每个用户的设备上都能立刻看到效果特别是应用还在灰度阶段时。我的做法是在名单配置通过后先用一台已经安装最新版本应用的真机做全流程验证如果是灰度发布阶段最好把测试设备所在的灰度通道也核对一遍避免出现“测试机分享面板正常正式环境用户反馈看不到目标应用”的情况。另外提一个高频问题目标应用还没正式上架能不能先在名单里配置实际经验是AGC侧通常要求目标应用处于可检索、可校验的状态比如已完成上架或至少已进入审核流程。如果目标应用是公司内部自用App、还没走公开上架路径那就得先把AGC上的应用创建、版本提交这些基础步骤走完不然搜索不到也添加不了这点务必提前评估。4. 常见问题与排查技巧4.1 配置了名单但分享面板里看不到目标应用这个问题在社区和群里被问得最多华为自己的论坛里也经常有类似帖子。排查顺序很重要我一般按下面的表格进行表现可能原因排查动作目标应用没出现在分享面板名单还在审核中去AGC看目标应用名单的审核状态目标应用没出现在分享面板包名填错或填写不完整跟目标应用方核对确认包名、签名目标应用没出现在分享面板目标应用未接入Share Kit确认目标应用已开通分享服务目标应用没出现在分享面板目标应用未声明对应数据类型检查目标应用module.json5的skills配置目标应用没出现在分享面板当前应用版本还未生效名单确认版本已通过审核并分发到当前环境配置里最容易被忽略的坑就是包名的大小写和签名差异。鸿蒙包里包名是大小写敏感的我遇到过有人把目标应用的包名从文档里复制出来时一个字母的大小写被改了结果怎么排查都找不到原因。建议每次添加完包名都跟目标应用方打开AGC后台再核对一遍这是最省时间的做法。4.2 搜索不到目标应用时怎么兜底用名称搜索搜不到目标应用通常只有三种情况。第一种目标应用没有接入Share Kit系统列表不会收录它第二种目标应用虽然接入了但还没达到AGC可检索状态第三种名称匹配问题搜索用的显示名和实际推广名不一致。解决思路很简单先跟目标应用的开发者确认包名用包名精确添加如果包名都添加不了那说明目标应用在AGC侧的接入状态有问题找对方确认Share Kit开通情况。别在名称搜索上死磕包名才是唯一准确的主键。另外系统预置应用不要走搜索从推荐列表里找。备忘录、邮件、图库这些都预置在列表中不光是包名难记类型也比较特殊手填很容易出错推荐列表就是给这类应用准备的。4.3 分享后目标应用收不到内容的排查方向前面所有问题最终都可能指向一个表现目标应用出现在了分享面板用户也确实点了分享但内容到了对方那边要么打不开要么直接丢失。这类问题的排查方向跟“分享面板不展示应用”完全不一样重点看三个地方。第一先确认数据类型匹配。你分享的是text/plain目标应用skills里声明的是image/*系统要么不拉起它要么拉起后无法处理数据。第二看action是否一致。接收方声明的是ohos.want.action.viewData分享方传递的动作要和它能处理的动作对齐。第三看文件格式和大小。某些文件类型或超大文件在系统传递过程中可能被限制这个在不同机型上表现不一致换一台设备复现能更快定位。这类问题最麻烦的地方在于单看AGC后台看不出问题必须真机联调。我们项目的做法是准备两台设备一台分享方一台接收方把整个流程录屏每一步的系统日志串起来看。拉到系统层日志后基本都能定位到是类型不匹配还是声明缺失。4.4 名单维护的长期经验配置完不代表结束名单是需要日常维护的。我们的团队现在保持一个很简单但有效的习惯每次调整名单在项目的版本记录里记一条包括目标应用包名、调整原因、提交人、审核通过时间每季度清理一次长期不用的目标应用避免无效包名堆积。还有一个容易被忽略的点目标应用如果改了包名或者换了签名原来配置的名单会失效需要在AGC侧更新。这种变化往往不是你的团队能第一时间感知的所以跟目标应用方保持一个信息同步的通道非常必要。最简单的办法就是列一个共享表格记录每个对接应用的负责人和变更通知日期谁改了包名、谁换了签名至少保证有一个可触达的沟通机制。5. 踩过这些坑之后我的配置顺序建议如果让我重新做一个企业应用的Share Kit集成配置顺序一定是先拉目标应用清单表格再配AGC名单最后写代码。清单表格要包含包名、接入状态、负责人、用途四个字段AGC名单在功能开发启动时就提交审核不要等代码写完了再提交代码侧的skills配置、分享调用在名单审核等待期内并行推进。我个人在实际项目里体会最深的是Share Kit的代码复杂度其实不高真正决定上线节奏的往往是这类云端配置的审批周期和多方协作。你提前一天把名单提交上去可能就少一次加班到凌晨的版本联调你漏配了一个包名可能用户在验收时打开分享面板就是找不到那款目标应用。这份看似“就几步操作”的配置做扎实了能给整个团队省下大量排查时间。如果这篇踩坑记录能让你少走几个弯路那就值了。
