harmonyos-best-practices-mcp 0.1.0

package/data/docs/bpta-add-watermark.md

@@ -0,0 +1,379 @@
+# 水印添加
+
+> 来源: https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-add-watermark
+> 文档标识(fileName): bpta-add-watermark  
+> 目录(catalogName): best-practices  
+> 语言: cn  
+> 更新时间: 2026-06-23 03:36:07  
+> 导航地址: /hmos/hmos-dp1
+
+---
+#### 概述
+
+在软件开发中，水印是一种在应用页面、图片或文档中嵌入的标记，它通常采用文字或图案的形式展现。水印通常有以下用途：
+
+- 标识来源：可用于标识应用、各种文件的来源或作者，确保产权的归属。
+- 版权保护：可携带版权保护信息，有效防止他人篡改、盗用、非法复制。
+- 艺术效果：可作为一种艺术效果，为图片或应用增添独特的风格。
+
+本文通过图文与代码结合的方式，对以下几种常见的水印添加场景进行讲解，旨在让开发者理解水印添加的基本原理以及掌握开发的流程与细节。
+
+- [页面上添加水印](#section12388834480)
+- [图片上添加水印](#section987311343125)
+- [PDF文档添加水印](#section7418171112138)
+
+#### 页面上添加水印
+
+## 场景描述
+
+某个页面背景上添加水印文字，实现效果图如下。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/25/v3/ZwSU-gh_R7SL4_qHHGyAIw/zh-cn_image_0000002229451785.png?HW-CC-KV=V1&HW-CC-Date=20260623T075558Z&HW-CC-Expire=86400&HW-CC-Sign=9BD2380DA0D11080AD85E345E2BD1EA04335A7711424EE4FF756C2B9741B9BDF "点击放大")
+
+## 实现原理
+
+**关键技术**
+
+[Canvas](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-components-canvas-canvas)提供画布组件，用于自定义绘制图形。使用[CanvasRenderingContext2D](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-canvasrenderingcontext2d)对象在[Canvas](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-components-canvas-canvas)组件上进行绘制，其中[fillText()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-canvasrenderingcontext2d#filltext)方法用于绘制文本，[drawImage()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-canvasrenderingcontext2d#drawimage)方法用于图像绘制。
+
+**开发流程**
+
+1. 创建[Canvas](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-components-canvas-canvas)画布，在画布上绘制水印。
+2. 使用[Stack](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-stack)组件或[浮层overlay](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-overlay#overlay)属性，将画布与UI页面组件融合显示。
+
+## 开发步骤
+
+1. 封装水印组件
+   1. 创建Canvas组件，监听[Canvas.onReady](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-components-canvas-canvas#事件)事件，该事件回调在Canvas组件初始化完成时或大小变化时执行，在回调中进行水印绘制draw()方法的执行。并通过设置Canvas组件的[hitTestBehavior](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-hit-test-behavior#hittestbehavior)属性，使水印组件不影响其他组件的触摸测试，让页面能正常交互。
+
+      ```
+      @Component
+      export struct Watermark {
+        private settings: RenderingContextSettings = new RenderingContextSettings(true);
+        private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings);
+        // ...
+        build() {
+          Canvas(this.context)
+            .width('100%')
+            .height('100%')
+            .hitTestBehavior(HitTestMode.Transparent)
+            .onReady(() => this.draw())
+        }
+      }
+      ```
+   2. 实现绘制水印draw()方法。绘制的起点默认为坐标轴的原点（画布的左上角），通过坐标轴的平移及旋转，实现在画布的不同位置、不同角度绘制水印。如果水印有一定旋转角度，想保证第一个水印能完整显示，需要对绘制的起点做平移，平移距离通过旋转角度及水印宽高计算。
+      - 旋转角度大于0，由下图可知，水印沿x轴方向平移距离positionX = tan(θ) * 水印高度，即绘制起点为(positionX, 0)。
+
+        ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/40/v3/0B0L4fKJTmmURlAacxd5Ww/zh-cn_image_0000002229337289.png?HW-CC-KV=V1&HW-CC-Date=20260623T075558Z&HW-CC-Expire=86400&HW-CC-Sign=806A816B994171286636F27740C01E505B9C3BA7BB93D081335875C1949A5E5C "点击放大")
+      - 旋转角度小于0，由下图可知，水印沿y轴方向平移距离positionY = tan(θ) * 水印宽度，即绘制起点为(0, positionY)。
+
+        ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/5f/v3/NVFMq32fTvKvuY-c-kEMTA/zh-cn_image_0000002229337285.png?HW-CC-KV=V1&HW-CC-Date=20260623T075558Z&HW-CC-Expire=86400&HW-CC-Sign=249323B300929CCE70BBD3D3772E82BAC2DC5FB124C431B22FC2632DF815B486 "点击放大")
+
+      最终通过[CanvasRenderingContext2D.fillText()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-canvasrenderingcontext2d#filltext)方法进行水印文字的绘制。
+
+      ```
+      @Prop watermarkWidth: number = 120;
+      @Prop watermarkHeight: number = 120;
+      @Prop watermarkText: string = this.getWatermarkText();
+      @Prop rotationAngle: number = -30;
+      @Prop fillColor: string | number | CanvasGradient | CanvasPattern = '#10000000';
+      @Prop font: string = '16vp';
+
+      draw() {
+        this.context.fillStyle = this.fillColor;
+        this.context.font = this.font;
+        const colCount = Math.ceil(this.context.width / this.watermarkWidth);
+        const rowCount = Math.ceil(this.context.height / this.watermarkHeight);
+        for (let col = 0; col <= colCount; col++) {
+          let row = 0;
+          for (; row <= rowCount; row++) {
+            const angle = this.rotationAngle * Math.PI / 180;
+            this.context.rotate(angle);
+            const positionX = this.rotationAngle > 0 ? this.watermarkHeight * Math.tan(angle) : 0;
+            const positionY = this.rotationAngle > 0 ? 0 : this.watermarkWidth * Math.tan(-angle);
+            this.context.fillText(this.watermarkText, positionX, positionY);
+            this.context.rotate(-angle);
+            this.context.translate(0, this.watermarkHeight);
+          }
+          this.context.translate(0, -this.watermarkHeight * row);
+          this.context.translate(this.watermarkWidth, 0);
+        }
+      }
+      ```
+2. 将水印组件与UI页面组件融合显示。
+
+   方式一：使用Stack将水印组件叠加在UI组件上层。
+
+   ```
+   Stack({ alignContent: Alignment.Center }) {
+     Column() {
+       Image($r('app.media.empty'))
+         .width(110)
+         .height(88)
+         // ...
+     }
+     Watermark({ rotationAngle: 20 })
+   }
+   ```
+
+   方式二：设置UI组件的overlay属性，使水印组件作为UI组件的浮层显示。注意watermarkBuilder中嵌套了一层父元素Column，所以需要同时设置Column的[hitTestBehavior](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-hit-test-behavior#hittestbehavior)属性，使浮层下方页面能正常交互。
+
+   ```
+   @Builder
+   watermarkBuilder() {
+     Column() {
+       Watermark()
+     }
+     .hitTestBehavior(HitTestMode.Transparent)
+   }
+   build() {
+     // ...
+       Column() {
+         Image($r('app.media.empty'))
+           .width(110)
+           .height(88)
+           // ...
+       }
+       .justifyContent(FlexAlign.Center)
+       .alignItems(HorizontalAlign.Center)
+       .layoutWeight(1)
+       .overlay(this.watermarkBuilder())
+       // ...
+   }
+   ```
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/d7/v3/eQjnUxfgSjmdKVXeprNldA/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260623T075558Z&HW-CC-Expire=86400&HW-CC-Sign=5883C63433C65CB828C3832D80BC3E73A1F474396BC54D03421E91F1DB2627A7) 
+
+如果需要多个页面或应用全局添加水印，可将上述方式二中的watermarkBuilder封装到一个单独的文件，export出一个全局的watermarkBuilder。在需要添加水印页面的根节点上添加.overlay绑定watermarkBuilder即可。
+
+#### 图片上添加水印
+
+## 场景描述
+
+保存的图片、拍照生成的图片等场景，需要添加水印。实现效果图如下。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/3f/v3/exK2Qs7-Rm60-hfxan93cg/zh-cn_image_0000002229451781.png?HW-CC-KV=V1&HW-CC-Date=20260623T075558Z&HW-CC-Expire=86400&HW-CC-Sign=F9E1259111C264657A92A039E177C677E29298B5744E079C080EE073C4DDA334 "点击放大")
+
+## 实现原理
+
+**关键技术**
+
+[OffscreenCanvas](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-components-offscreencanvas)提供离屏画布，与[Canvas](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-components-canvas-canvas)使用场景区别在于是否需要将画布渲染在屏幕上。使用[OffscreenCanvasRenderingContext2D](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-offscreencanvasrenderingcontext2d)在[OffscreenCanvas](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-components-offscreencanvas)上进行离屏绘制，其中[fillText()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-offscreencanvasrenderingcontext2d#filltext)方法用于绘制文本，[drawImage()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-offscreencanvasrenderingcontext2d#drawimage)方法用于图像绘制。
+
+**开发流程**
+
+1. 解析图片得到pixelMap数据。
+2. 创建与图片宽高一致的[OffscreenCanvas](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-components-offscreencanvas)离屏画布。
+3. 将图片和水印依次绘制到离屏画布上。
+4. 获取离屏画布的pixelMap数据。
+5. 将pixelMap数据写入文件中。
+
+## 开发步骤
+
+1. 解析图片得到pixelMap数据。
+   1. 使用[resourceManager.getMediaContent()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-resource-manager#getmediacontent9-1)方法获取图片内容，得到ArrayBuffer数据。使用[image.createImageSource(buf: ArrayBuffer)](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-image-f#imagecreateimagesource9-2)方法创建图片源实例。
+
+      ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/b3/v3/IimCugPKQjmAG3jP_Ul7AQ/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260623T075558Z&HW-CC-Expire=86400&HW-CC-Sign=D33C623914CFB13690B0437D517F005E0E3492B655CD600631828BC9F18F514C) 
+
+      ImagePixelMap为自定义类型：{ pixelMap: image.PixelMap, width: number, height: number }。
+
+      ```
+      async getImagePixelMap(resource: Resource): Promise<ImagePixelMap | undefined> {
+        let result: ImagePixelMap | undefined = undefined;
+        try {
+          const data: Uint8Array =
+            await this.getUIContext().getHostContext()?.resourceManager.getMediaContent(resource.id) as Uint8Array;
+          const arrayBuffer: ArrayBuffer = data.buffer.slice(data.byteOffset, data.byteLength + data.byteOffset);
+          const imageSource: image.ImageSource = image.createImageSource(arrayBuffer);
+          result = await imageSource2PixelMap(imageSource);
+        } catch (e) {
+          let err = e as BusinessError;
+          hilog.error(0x0000, TAG, `failed code=${err.code}, message=${err.message}`);
+        }
+        return result;
+      }
+      ```
+   2. 使用[ImageSource.getImageInfo()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-image-imagesource#getimageinfo-2)方法获取图片宽、高信息，使用[ImageSource.createPixelMap()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-image-imagesource#createpixelmap7)方法创建PixelMap对象。
+
+      ```
+      export async function imageSource2PixelMap(imageSource: image.ImageSource): Promise<ImagePixelMap> {
+        const imageInfo: image.ImageInfo = await imageSource.getImageInfo();
+        const height = imageInfo.size.height;
+        const width = imageInfo.size.width;
+        const options: image.DecodingOptions = {
+          editable: true,
+          desiredSize: { height, width }
+        };
+        const pixelMap: PixelMap = await imageSource.createPixelMap(options);
+        const result: ImagePixelMap = { pixelMap, width, height };
+        return result;
+      }
+      ```
+2. 通过[OffscreenCanvas](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-components-offscreencanvas)离屏画布绘制图片及水印，得到融合水印后的pixelMap数据。
+   1. 创建与图片宽高一致的[OffscreenCanvas](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-components-offscreencanvas)离屏画布，这里注意单位保持一致。
+   2. 使用[OffscreenCanvasRenderingContext2D.drawImage()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-offscreencanvasrenderingcontext2d#drawimage)将图片绘制到离屏画布上。
+   3. 使用[OffscreenCanvasRenderingContext2D.fillText()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-offscreencanvasrenderingcontext2d#filltext)将水印绘制在离屏画布的指定位置。
+   4. 使用[OffscreenCanvasRenderingContext2D.getPixelMap()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-offscreencanvasrenderingcontext2d#getpixelmap)以当前离屏画布指定区域内的像素创建PixelMap对象。
+
+      ```
+      export function addWatermark(
+        imagePixelMap: ImagePixelMap,
+        text: string = 'watermark',
+        drawWatermark?: (OffscreenContext: OffscreenCanvasRenderingContext2D) => void
+      ): image.PixelMap {
+        const height = uiContext?.px2vp(imagePixelMap.height) as number;
+        const width = uiContext?.px2vp(imagePixelMap.width) as number;
+        const offScreenCanvas = new OffscreenCanvas(width, height);
+        const offScreenContext = offScreenCanvas.getContext('2d');
+        offScreenContext.drawImage(imagePixelMap.pixelMap, 0, 0, width, height);
+        if (drawWatermark) {
+          drawWatermark(offScreenContext);
+        } else {
+          let displayWidth: number = 0;
+          try {
+            displayWidth = display.getDefaultDisplaySync().width;
+          } catch (e) {
+            let err = e as BusinessError;
+            hilog.error(0x0000, TAG, `failed code=${err.code}, message=${err.message}`);
+          }
+          const vpWidth = uiContext?.px2vp(displayWidth) ?? displayWidth;
+          const imageScale = width / vpWidth;
+          offScreenContext.textAlign = 'right';
+          offScreenContext.fillStyle = '#A2FFFFFF';
+          offScreenContext.font = 12 * imageScale + 'vp';
+          const padding = 5 * imageScale;
+          offScreenContext.fillText(text, width - padding, height - padding);
+        }
+        return offScreenContext.getPixelMap(0, 0, width, height);
+      }
+      ```
+3. 将添加水印后得到的pixelMap数据写入文件中。
+
+   ```
+   export async function saveToFile(pixelMap: image.PixelMap, context: Context): Promise<void> {
+     try {
+       const phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
+       const filePath = await phAccessHelper.createAsset(photoAccessHelper.PhotoType.IMAGE, 'png');
+       const imagePacker = image.createImagePacker();
+       const imageBuffer = await imagePacker.packToData(pixelMap, {
+         format: 'image/png',
+         quality: 100
+       });
+       const mode = fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE;
+       fd = (await fileIo.open(filePath, mode)).fd;
+       await fileIo.truncate(fd);
+       await fileIo.write(fd, imageBuffer);
+     } catch (err) {
+       hilog.error(0x0000, TAG, 'saveToFile error：', JSON.stringify(err) ?? '');
+     } finally {
+       try {
+         if (fd) {
+           fileIo.close(fd);
+         }
+       } catch (e) {
+         let err = e as BusinessError;
+         hilog.error(0x0000, TAG, `close failed code=${err.code}, message=${err.message}`);
+       }
+     }
+   }
+   ```
+
+#### PDF文档添加水印
+
+## 场景描述
+
+在PDF预览页面点击添加水印按钮，生成带水印的PDF文档，并显示在预览页面中。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/c9/v3/CMuGFRSXSsWD5CmkvRGKTw/zh-cn_image_0000002229337293.png?HW-CC-KV=V1&HW-CC-Date=20260623T075558Z&HW-CC-Expire=86400&HW-CC-Sign=A902D53A3ABF9B77B88E71D35277522ECFF6C070810E1720F9D18381EEDD15EC "点击放大")
+
+## 实现原理
+
+**关键技术**
+
+[pdfService](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/pdf-arkts-pdfservice)模块为应用提供统一管理PDF页面的页眉页脚、水印、背景、批注、书签的能力。[TextWatermarkInfo](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/pdf-arkts-pdfservice#textwatermarkinfo)类和[ImageWatermarkInfo](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/pdf-arkts-pdfservice#imagewatermarkinfo)分别提供创建文本水印和图片水印的能力。[PdfDocument](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/pdf-arkts-pdfservice#pdfdocument)类提供与文档相关能力，其中[addWatermark()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/pdf-arkts-pdfservice#addwatermark)方法用于添加水印。
+
+**开发流程**
+
+1. 将应用侧PDF文件写入沙箱中。
+2. 使用[pdfService](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/pdf-arkts-pdfservice)模块相关API加载指定沙箱路径的PDF并添加水印。
+
+## 开发步骤
+
+1. 使用[getRawFileContentSync()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-resource-manager#getrawfilecontentsync10)方法获取resource/rawfile目录下的PDF文件内容，使用[writeSync()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-file-fs#writesync10)方法写入沙箱中。
+
+   ```
+   savePdfToSandbox(): string {
+     const filePath = this.getPdfSandboxPath();
+     try {
+       fileIo.accessSync(filePath);
+       const content: Uint8Array = this.getUIContext().getHostContext()?.resourceManager.getRawFileContentSync('watermark.pdf') as Uint8Array;
+       const file = fileIo.openSync(filePath, fileIo.OpenMode.WRITE_ONLY | fileIo.OpenMode.CREATE | fileIo.OpenMode.TRUNC);
+       fileIo.writeSync(file.fd, content.buffer);
+       fileIo.closeSync(file.fd);
+     } catch (e) {
+       let err = e as BusinessError;
+       hilog.error(0x0000, TAG, `savePdfToSandbox failed code=${err.code}, message=${err.message}`);
+     }
+     return filePath;
+   }
+   ```
+2. 使用[PdfController](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/pdf-arkts-pdfviewmanage#pdfcontroller)控制器中的[loadDocument()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/pdf-arkts-pdfservice#loaddocument)方法通过沙箱路径加载文件，显示到PDF预览组件[PdfView](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/pdf-arkts-pdfview-component)中。
+
+   ```
+   private controller: pdfViewManager.PdfController = new pdfViewManager.PdfController();
+   // ...
+   aboutToAppear(): void {
+     const filePath = this.savePdfToSandbox();
+     this.controller.loadDocument(filePath);
+   }
+   // ...
+   build() {
+     // ...
+         PdfView({
+           controller: this.controller,
+           pageFit: pdfService.PageFit.FIT_WIDTH
+         })
+           // ...
+   ```
+3. 通过文本水印类TextWatermarkInfo创建水印对象，设置水印内容、字体、颜色、位置等相关属性；图片水印对象通过ImageWatermarkInfo创建。
+
+   ```
+   getWatermarkInfo() {
+     const watermarkInfo: pdfService.TextWatermarkInfo = new pdfService.TextWatermarkInfo();
+     watermarkInfo.watermarkType = pdfService.WatermarkType.WATERMARK_TEXT;
+     watermarkInfo.content = 'This is Watermark';
+     watermarkInfo.textSize = 32;
+     watermarkInfo.textColor = 200;
+     watermarkInfo.rotation = 45;
+     watermarkInfo.opacity = 0.3;
+     return watermarkInfo;
+   }
+   ```
+4. 通过PDF文档类PdfDocument创建文档对象，使用文档对象的loadDocument()方法加载文档，addWatermark()方法添加水印、[saveDocument()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/pdf-arkts-pdfservice#savedocument)方法将添加水印后的文档保存到沙箱中。
+
+   ```
+   addWatermark() {
+     const filePath = this.getPdfSandboxPath();
+     let pdfDocument: pdfService.PdfDocument = new pdfService.PdfDocument();
+     pdfDocument.loadDocument(filePath);
+     pdfDocument.addWatermark(this.getWatermarkInfo(), 0, pdfDocument.getPageCount(), true, true);
+     const watermarkFilePath = this.getAddedWatermarkPdfSandboxPath();
+     pdfDocument.saveDocument(watermarkFilePath);
+     this.showInPdfView(watermarkFilePath);
+   }
+   ```
+5. 将沙箱中添加水印后的文档加载到PDF预览器中。
+
+   ```
+   async showInPdfView(filePath: string) {
+     this.hasWatermark = true;
+     // release before reload avoid crash.
+     this.controller.releaseDocument();
+     await this.controller.loadDocument(filePath);
+     this.controller.setPageFit(pdfService.PageFit.FIT_WIDTH);
+   }
+   ```
+
+#### 示例代码
+
+- [实现添加水印功能](https://gitcode.com/harmonyos_samples/watermark)

package/data/docs/bpta-ads-jump.md

@@ -0,0 +1,67 @@
+# 广告跳转
+
+> 来源: https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-ads-jump
+> 文档标识(fileName): bpta-ads-jump  
+> 目录(catalogName): best-practices  
+> 语言: cn  
+> 更新时间: 2026-06-23 03:35:01  
+> 导航地址: /hmos/hmos-dp1
+
+---
+#### 概述
+
+在移动应用或Web开发中，广告跳转是一种常见的商业模式，通过引导用户点击广告并跳转到目标页面（例如应用下载、商品详情、活动页等）来实现流量变现或推广。
+
+典型场景：例如视频应用作为广告载体，用户在开屏广告中点击商品广告后，系统自动跳转到商城应用的商品详情页。这样既提升了广告转化率，也优化了用户体验。
+
+[](https://contentcenter-videovali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_300_3/4d/v3/Ml6UClqIS66HyhB5IFomkg/zh-cn_media_0000002284717440.mp4?HW-CC-KV=V1&HW-CC-Date=20260623T075538Z&HW-CC-Expire=86400&HW-CC-Sign=750992E248E25DE54C88A3E2905E82C6F499A45FDBA75E38459FEF70C132FFFE)
+
+本文以广告目标方（如商城应用）的开发为主，介绍商城应用如何通过App Linking技术，支持视频应用等外部广告载体高效拉起商城应用商品页，并完善未安装、延迟跳转等各种链路，从而实现完整的广告变现闭环。
+
+#### 实现原理
+
+广告跳转链路涉及两个应用，具体如下：
+
+- 广告载体方（如视频应用）：承担广告展示与落地页跳转功能。
+- 广告目标方（如商城应用）：被外部应用拉起，承接点击流量至商品详情页。
+
+广告跳转的流程图如下所示。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/1b/v3/4StvzceKTA6nbuF2OlJOlQ/zh-cn_image_0000002319470037.png?HW-CC-KV=V1&HW-CC-Date=20260623T075538Z&HW-CC-Expire=86400&HW-CC-Sign=F347F06927D0F24E90A8A2EAE294C887BF7FB78794FBE558377B5E83F811F653 "点击放大")
+
+跳转过程基于[App Linking](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-linking-startup)能力，分为几种情况：
+
+1. 商城应用已安装
+
+   用户在视频应用广告页点击商品，系统通过App Linking直接拉起商城应用并跳转到指定商品详情页。
+2. 商城应用未安装，配置直达应用市场
+
+   点击广告后由系统自动跳转至商城应用在应用市场的详情页，用户下载安装后，首次打开即可通过延迟链接直接定位到对应商品页。
+3. 商城应用未安装，未配置直达应用市场
+
+   点击广告后，系统拉起商城应用的Web页面（商品详情页），用户可直接浏览或通过页面引导下载安装商城应用。后续如完成安装，仍能保留原始跳转意图，实现直达商品页。
+
+#### 开发步骤
+
+1. [配置App Linking服务](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-social-share#section109826570198)。
+   - 在AGC（AppGallery Connect）后台为商城应用开通[App Linking](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-linking-startup)能力，正确配置商品详情页的深度链接与参数。
+   - 确认所有需要被广告载体（如视频应用）跳转的页面均能通过App Linking唯一链接定位。
+2. 开发商品详情Web页面
+   - 实现商品详情的Web页面，保证当商城应用未安装时，点击跳转链接可以展示同样的商品信息。
+   - 在Web页面中，可以提供“打开商城应用”“下载商城应用”等引导按钮，增强用户转化率。
+   - 参考[Web页面开发与部署](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-social-share#section157709544229)完成部署与配置。
+
+   ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/1e/v3/EBxC2VujSPeCYpYk2PatIQ/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260623T075538Z&HW-CC-Expire=86400&HW-CC-Sign=6CC2B9068DAF67C16FBAB5E53D84DB0EDC1EA6F965581EB08C26138AC6BE59C4) 
+
+   如果广告载体方（如视频应用）希望在自身应用内直接打开商城应用的商品详情Web页面，可以在调用[openLink()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-inner-application-uiabilitycontext#openlink12)接口时，将参数appLinkingOnly设置为true。这样当无法拉起商城应用时，系统不会自动跳转到浏览器打开Web页面，而是通过失败回调返回结果。
+
+   广告载体方（如视频应用）可在回调中自行处理异常，例如手动跳转到商城应用的商品详情Web页面，实现更灵活的跳转控制。
+3. 配置直达应用市场能力（可选）
+   - 若目标是让用户优先安装商城应用以获得完整体验，建议在App Linking配置中启用[直达应用市场](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/applinking-direct-to-ag)能力。
+   - 用户点击广告，如果商城应用未安装，将直接进入商城应用的应用市场页面，无须经过Web中转。
+4. 实现延迟链接能力
+   - 配置并实现[延迟链接](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/applinking-deferredlink)（Deferred Link）功能。
+   - 用户在广告链路中下载安装商城应用后，首次打开应用可自动恢复跳转到指定商品页，保证广告流量完整转化。
+5. 向广告载体方（如视频应用）提供标准App Linking跳转链接
+
+   将每一个商品的App Linking链接提供给广告载体（如视频应用），广告点击后调用openLink()接口进行跳转。