From 766476bfb46481007d892fb8a86ac425fb4c6aaf Mon Sep 17 00:00:00 2001 From: liujixin Date: Tue, 2 Sep 2025 10:48:48 +0800 Subject: [PATCH] JSdoc updata Signed-off-by: liujixin --- api/@internal/component/ets/web.d.ts | 112 +++++++++++++++------------ api/@ohos.web.webview.d.ts | 17 ++-- 2 files changed, 75 insertions(+), 54 deletions(-) diff --git a/api/@internal/component/ets/web.d.ts b/api/@internal/component/ets/web.d.ts index 528698fb1c..8461c5cb6e 100644 --- a/api/@internal/component/ets/web.d.ts +++ b/api/@internal/component/ets/web.d.ts @@ -4563,7 +4563,7 @@ declare class EventResult { constructor(); /** - * Sets the event consumption result. + * Sets the gesture event consumption result. * * @param { boolean } result - Whether to consume the gesture event. * {@code true} Indicates the consumption of the gesture event. @@ -5239,7 +5239,7 @@ declare interface NativeEmbedInfo { id?: string; /** - * Only when enableEmbedMode is true and type is marked as native/xxx will be recognized as a same layer component. + * Type of the same-layer tag. The value is in lowercase. * * @type { ?string } * @syscap SystemCapability.Web.Webview.Core @@ -5259,7 +5259,8 @@ declare interface NativeEmbedInfo { src?: string; /** - * The coordinate position of embed element relative to the webComponent. + * Position of the same-layer tag relative to the Web component in the screen coordinate system, + * which is different from the standard Position. The unit is px. * * @type { ?Position } * @syscap SystemCapability.Web.Webview.Core @@ -5269,7 +5270,7 @@ declare interface NativeEmbedInfo { position?: Position; /** - * The embed tag width. + * The embed tag width, in px. * * @type { ?number } * @syscap SystemCapability.Web.Webview.Core @@ -5279,7 +5280,7 @@ declare interface NativeEmbedInfo { width?: number; /** - * The embed tag height. + * The embed tag height, in px. * * @type { ?number } * @syscap SystemCapability.Web.Webview.Core @@ -5299,7 +5300,7 @@ declare interface NativeEmbedInfo { url?: string; /** - * The embed tag name. + * The embed tag name, which is in uppercase. * * @type { ?string } * @syscap SystemCapability.Web.Webview.Core @@ -5309,7 +5310,8 @@ declare interface NativeEmbedInfo { tag?: string; /** - * The embed param list information used by object tag. + * List of key-value pairs contained in the object tag that form a map of the Object type. + * Use the methods provided by the Object type, such as embed.info?.param?.["name"] to operate the map object. * * @type { ?Map } * @syscap SystemCapability.Web.Webview.Core @@ -5328,7 +5330,7 @@ declare interface NativeEmbedInfo { * @since 11 */ /** - * Defines the Embed Data info. + * Provides detailed information about the changes of the same-layer tag lifecycle. * * @typedef NativeEmbedDataInfo * @syscap SystemCapability.Web.Webview.Core @@ -5337,7 +5339,7 @@ declare interface NativeEmbedInfo { */ declare interface NativeEmbedDataInfo { /** - * The embed status. + * Lifecycle status of the same-layer tag. * * @type { ?NativeEmbedStatus } * @syscap SystemCapability.Web.Webview.Core @@ -5347,7 +5349,7 @@ declare interface NativeEmbedDataInfo { status?: NativeEmbedStatus; /** - * The surface id. + * Psurfaceid of the NativeImage. * * @type { ?string } * @syscap SystemCapability.Web.Webview.Core @@ -5357,7 +5359,7 @@ declare interface NativeEmbedDataInfo { surfaceId?: string; /** - * The embed id. + * Unique id of the same-layer tag. * * @type { ?string } * @syscap SystemCapability.Web.Webview.Core @@ -5367,7 +5369,7 @@ declare interface NativeEmbedDataInfo { embedId?: string; /** - * The embed info. + * Detailed information about the same-layer tag. * * @type { ?NativeEmbedInfo } * @syscap SystemCapability.Web.Webview.Core @@ -5378,7 +5380,7 @@ declare interface NativeEmbedDataInfo { } /** - * Defines the Embed Visibility info. + * Provides visibility information about the same-layer tag. * * @typedef NativeEmbedVisibilityInfo * @syscap SystemCapability.Web.Webview.Core @@ -5386,7 +5388,8 @@ declare interface NativeEmbedDataInfo { */ declare interface NativeEmbedVisibilityInfo { /** - * The embed visibility. + * Whether the same-layer tag is visible. + * The value true indicates that the same-layer tag is visible, and false indicates the opposite. * * @type { boolean } * @syscap SystemCapability.Web.Webview.Core @@ -5395,7 +5398,7 @@ declare interface NativeEmbedVisibilityInfo { visibility: boolean; /** - * The embed id. + * ID of the same-layer rendered tag. * * @type { string } * @syscap SystemCapability.Web.Webview.Core @@ -5413,7 +5416,7 @@ declare interface NativeEmbedVisibilityInfo { * @since 11 */ /** - * Defines the user touch info. + * Provides touch information of the same-layer tag. * * @typedef NativeEmbedTouchInfo * @syscap SystemCapability.Web.Webview.Core @@ -5432,7 +5435,7 @@ declare interface NativeEmbedTouchInfo { embedId?: string; /** - * An event sent when the state of contacts with a touch-sensitive surface changes. + * Touch action information. * * @type { ?TouchEvent } * @syscap SystemCapability.Web.Webview.Core @@ -5442,7 +5445,7 @@ declare interface NativeEmbedTouchInfo { touchEvent?: TouchEvent; /** - * Handle the user's touch result. + * Gesture event consumption result. * * @type { ?EventResult } * @syscap SystemCapability.Web.Webview.Core @@ -5489,7 +5492,7 @@ declare interface NativeEmbedMouseInfo { } /** - * Defines the first content paint rendering of web page. + * Provides detailed information about the first meaningful paint. * * @typedef FirstMeaningfulPaint * @syscap SystemCapability.Web.Webview.Core @@ -5498,7 +5501,7 @@ declare interface NativeEmbedMouseInfo { */ declare interface FirstMeaningfulPaint { /** - * Start time of navigation. + * Start time of navigation, in microseconds. * * @type { ?number } * @syscap SystemCapability.Web.Webview.Core @@ -5508,7 +5511,7 @@ declare interface FirstMeaningfulPaint { navigationStartTime?: number; /** - * Paint time of first meaningful content. + * Paint time of first meaningful content, in milliseconds. * * @type { ?number } * @syscap SystemCapability.Web.Webview.Core @@ -5528,7 +5531,7 @@ declare interface FirstMeaningfulPaint { */ declare interface LargestContentfulPaint { /** - * Start time of navigation. + * Start time of navigation, in microseconds. * * @type { ?number } * @syscap SystemCapability.Web.Webview.Core @@ -5538,7 +5541,7 @@ declare interface LargestContentfulPaint { navigationStartTime?: number; /** - * Paint time of largest image. + * Paint time of largest image, in milliseconds. * * @type { ?number } * @syscap SystemCapability.Web.Webview.Core @@ -5548,7 +5551,7 @@ declare interface LargestContentfulPaint { largestImagePaintTime?: number; /** - * Paint time of largest text. + * Paint time of largest text, in milliseconds. * * @type { ?number } * @syscap SystemCapability.Web.Webview.Core @@ -5558,7 +5561,7 @@ declare interface LargestContentfulPaint { largestTextPaintTime?: number; /** - * Bits per pixel of image. + * Bits per pixel of image, in milliseconds. * * @type { ?number } * @syscap SystemCapability.Web.Webview.Core @@ -5568,7 +5571,7 @@ declare interface LargestContentfulPaint { imageBPP?: number; /** - * Load start time of largest image. + * Load start time of largest image, in milliseconds. * * @type { ?number } * @syscap SystemCapability.Web.Webview.Core @@ -5578,7 +5581,7 @@ declare interface LargestContentfulPaint { largestImageLoadStartTime?: number; /** - * Load end time of largest image. + * Number of pixels of the maximum image. * * @type { ?number } * @syscap SystemCapability.Web.Webview.Core @@ -7942,7 +7945,7 @@ declare class WebAttribute extends CommonMethod { /** * Sets the ratio of the text zoom. * - * @param { number } textZoomRatio The ratio of the text zoom. The default value is 100, ranging from 1 to +∞. + * @param { number } textZoomRatio Text zoom ratio to set. The value is an integer. The value range is (0, 2147483647]. * @returns { WebAttribute } * @syscap SystemCapability.Web.Webview.Core * @since 9 @@ -7950,7 +7953,7 @@ declare class WebAttribute extends CommonMethod { /** * Sets the ratio of the text zoom. * - * @param { number } textZoomRatio The ratio of the text zoom. The default value is 100, ranging from 1 to +∞. + * @param { number } textZoomRatio Text zoom ratio to set. The value is an integer. The value range is (0, 2147483647]. * @returns { WebAttribute } * @syscap SystemCapability.Web.Webview.Core * @atomicservice @@ -8032,12 +8035,10 @@ declare class WebAttribute extends CommonMethod { *

* * @param { boolean } enabled Whether the viewport property of the meta tag is enabled. - * {@code true} means support the viewport attribute of the meta tag, - * the viewport property of the meta tag is not enabled. - * This means that the property will not be parsed and a default layout will be used.; - * {@code false} means not support the viewport attribute of the meta tag, - * the viewport property of the meta tag is enabled. - * This means that the property will be parsed and used for the layout. + * {@code true} means support the viewport attribute of the meta tag is enabled and parsed, + * and the layout is performed based on the viewport attribute. + * {@code false} means not support the viewport attribute of the meta tag is disabled and not parsed, + * and the default layout is used. * Default value: true. * @returns { WebAttribute } * @syscap SystemCapability.Web.Webview.Core @@ -9337,10 +9338,10 @@ declare class WebAttribute extends CommonMethod { * @since 9 */ /** - * Sets the standard font family for the web page. + * Sets a serif font family for the web page. * - * @param { string } family Sets the standard font family for the web page. - * Default value: sans-serif. + * @param { string } family Serif font family to set. + * Default value: serif. * @returns { WebAttribute } * @syscap SystemCapability.Web.Webview.Core * @atomicservice @@ -9437,7 +9438,7 @@ declare class WebAttribute extends CommonMethod { * @since 9 */ /** - * Sets the default font size for the web page. + * Sets the default fixed font size for the web page. * * @param { number } size Default fixed font size to set, in px. * The value ranges from -2^31 to 2^31-1. In actual rendering, @@ -9868,9 +9869,9 @@ declare class WebAttribute extends CommonMethod { onFirstContentfulPaint(callback: Callback): WebAttribute; /** - * Called when the First rendering of meaningful content time(FMP) + * Triggered when the first meaningful paint occurs on the web page. * - * @param { OnFirstMeaningfulPaintCallback } callback Function Triggered when the firstMeaningfulPaint. + * @param { OnFirstMeaningfulPaintCallback } callback Callback invoked when the First Meaningful Paint occurs on the web page. * @returns { WebAttribute } * @syscap SystemCapability.Web.Webview.Core * @atomicservice @@ -9879,9 +9880,9 @@ declare class WebAttribute extends CommonMethod { onFirstMeaningfulPaint(callback: OnFirstMeaningfulPaintCallback): WebAttribute; /** - * Called when the Maximum content rendering time(LCP). + * Triggered when the largest content paint occurs on the web page. * - * @param { OnLargestContentfulPaintCallback } callback Function Triggered when the largestContentfulPaint. + * @param { OnLargestContentfulPaintCallback } callback Callback invoked when the largest content paint occurs on the web page. * @returns { WebAttribute } * @syscap SystemCapability.Web.Webview.Core * @atomicservice @@ -10076,7 +10077,7 @@ declare class WebAttribute extends CommonMethod { * - Frequent changes to the page width and height will trigger a re-layout of the Web component, * which can affect the user experience. * - Waterfall web pages are not supported (drop down to the bottom to load more). - * - Only height adaptation is supported(VH units are not supported). Width adaptation is not supported. + * - Only height adaptation is supported. Width adaptation is not supported. * - Because the height is adaptive to the web page height, * the component height cannot be changed by modifying the component height attribute. *

@@ -10125,7 +10126,7 @@ declare class WebAttribute extends CommonMethod { nestedScroll(value: NestedScrollOptions | NestedScrollOptionsExt): WebAttribute; /** - * Sets the enable native embed mode for web. + * Sets whether to enable the same-layer rendering feature. * *

API Note: * Performance Note: @@ -10133,7 +10134,8 @@ declare class WebAttribute extends CommonMethod { * see [Rendering Native Components on the Web Using Same-Layer Rendering]{@link https://developer.huawei.com/consumer/en/doc/best-practices/bpta-render-web-using-same-layer-render} *

* - * @param { boolean } mode - True if it needs to enable native embed mode. + * @param { boolean } mode - Whether to enable the same-layer rendering feature. + * The value true means to enable the same-layer rendering feature, and false means the opposite. * @returns { WebAttribute } * @syscap SystemCapability.Web.Webview.Core * @atomicservice @@ -10149,7 +10151,7 @@ declare class WebAttribute extends CommonMethod { * the ArkWeb kernel identifies the type as a non-same-layer tag.
* This API is also controlled by the enableNativeEmbedMode API and * does not take effect if same-layer rendering is not enabled. When this API is not used, - * the ArkWeb engine recognizes the embed tags with the "native/" prefix as same-layer tags. + * the ArkWeb kernel recognizes the embed tags with the "native/" prefix as same-layer tags. * * @param { string } tag - Tag name. * @param { string } type - Type of the tag, The kernel matches this parameter with a prefix. @@ -10178,14 +10180,14 @@ declare class WebAttribute extends CommonMethod { onNativeEmbedLifecycleChange(callback: (event: NativeEmbedDataInfo) => void): WebAttribute; /** - * Called when the visibility of a same-layer tag (such as an Embed tag or an Object tag) on a web page changes in the viewport. + * Called when the visibility of a same-layer tag (such as an embed tag or an object tag) on a web page changes in the viewport. * By default, the same-layer tag is invisible. If the rendering tag is visible when you access the page for the first time, * the callback is triggered; otherwise, it is not triggered. That is, if the same-layer tag changes from a non-zero value to 0 x 0, * the callback is triggered. If the rendering tag size changes from 0 x 0 to a non-zero value, the callback is not triggered. * If all the same-layer tags are invisible, they are reported as invisible. If all the same-layer rendering tags or part of them are visible, * they are reported as invisible. * - * @param { OnNativeEmbedVisibilityChangeCallback } callback - Callback triggered when embed visibility changes. + * @param { OnNativeEmbedVisibilityChangeCallback } callback - Callback invoked when the visibility of a same-layer tag changes. * @returns { WebAttribute } * @syscap SystemCapability.Web.Webview.Core * @since 12 @@ -10244,6 +10246,17 @@ declare class WebAttribute extends CommonMethod { /** * Sets whether automatic text resizing is enabled. + * After the automatic text font size adjustment takes effect, + * the font size will be automatically increased to 16px~32px + * for text with too small font size to avoid the readability problem of + * small fonts due to the lack of mobile adaptation for devices with small screens (default viewport width < 980px). + * + *

API Note:
+ * Prerequisites for the automatic adjustment of text font size to take effect: + * 1.The device forms are: Phone, Tablet, Wearable, TV. + * 2.Web component viewport width < 980px. + * 3.The page text is large, and the font size * number of characters of the page text is ≥ 3920. + * 4.There is no metaViewport setting on the frontend, or no "width" and "initial-scale" attributes in the metaViewport setting. * * @param { boolean } textAutosizing - Whether automatic text resizing is enabled. * {@code true} means enable text autosizing; @@ -10448,6 +10461,7 @@ declare class WebAttribute extends CommonMethod { * Sets whether to enable AVSession for web pages. * * @param { boolean } enabled Whether to enable AVSession. The value true means to enable AVSession, and false means the opposite. + * False when passing in undefined and null. * @returns { WebAttribute } * @syscap SystemCapability.Web.Webview.Core * @since 18 diff --git a/api/@ohos.web.webview.d.ts b/api/@ohos.web.webview.d.ts index db30044a20..ea69cb464f 100644 --- a/api/@ohos.web.webview.d.ts +++ b/api/@ohos.web.webview.d.ts @@ -3089,7 +3089,11 @@ declare namespace webview { id?: string; /** - * Size of the web. + * Size for web rendering. + * The maximum size is 16000 px × 16000 px. The length unit can be px, vp, or %. + * The length unit must be the consistent across parameters. The default unit is vp. + * If the size exceeds the specifications, the maximum size is returned. + * (Example: width: '100px', height: '200px' or width: '20%', height'30%'. If only digits are written, the unit is vp.) * * @type { ?SizeOptions } * @syscap SystemCapability.Web.Webview.Core @@ -3100,7 +3104,7 @@ declare namespace webview { } /** - * Defines the snapshot result. + * Represents a full drawing result. * * @typedef SnapshotResult * @syscap SystemCapability.Web.Webview.Core @@ -3120,7 +3124,9 @@ declare namespace webview { /** * The status of the snapshot. - * + * The value can be true (normal) or false (failure). If the full drawing result fails to be obtained, + * the width and height of the returned size are both 0, and the map is empty. + * * @type { ?boolean } * @syscap SystemCapability.Web.Webview.Core * @atomicservice @@ -3129,7 +3135,8 @@ declare namespace webview { status?: boolean; /** - * Size of the web. + * Actual size drawn on the web page. + * The value is of the number type, and the unit is vp. * * @type { ?SizeOptions } * @syscap SystemCapability.Web.Webview.Core @@ -3139,7 +3146,7 @@ declare namespace webview { size?: SizeOptions; /** - * The image in PixelMap format. + * Full drawing result in image.PixelMap format. * * @type { ?image.PixelMap } * @syscap SystemCapability.Web.Webview.Core -- Gitee