From 804041e9303c5008ccf508501aface892957af66 Mon Sep 17 00:00:00 2001 From: zengyawen Date: Wed, 16 Mar 2022 16:30:52 +0800 Subject: [PATCH] update docs Signed-off-by: zengyawen --- .../application-dev-website-en.md | 581 +++++++++ en/application-dev/media/Readme-EN.md | 5 - .../application-dev-website.md | 11 - .../reference/apis/Readme-CN.md | 4 + .../reference/apis/js-apis-pasteboard.md | 1047 ++++++++++++++++ .../reference/apis/js-apis-request.md | 1102 +++++++++++++++++ .../reference/apis/js-apis-screen-lock.md | 168 +++ .../reference/apis/js-apis-system-time.md | 373 +++++- .../reference/apis/js-apis-wallpaper.md | 569 +++++++++ 9 files changed, 3807 insertions(+), 53 deletions(-) create mode 100644 en/application-dev/application-dev-website-en.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-pasteboard.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-request.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-screen-lock.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-wallpaper.md diff --git a/en/application-dev/application-dev-website-en.md b/en/application-dev/application-dev-website-en.md new file mode 100644 index 0000000000..9b294db417 --- /dev/null +++ b/en/application-dev/application-dev-website-en.md @@ -0,0 +1,581 @@ +# Application Development + +[Application Development Overview](application-dev-guide.md) + +- Learn About OpenHarmony + - [OpenHarmony Project](../OpenHarmony-Overview.md) + - [Glossary ](../device-dev/glossary/glossary.md) + - [OpenHarmony Release Notes](../release-notes/Readme.md) +- OpenHarmony Release Notes + + - OpenHarmony 3.x Releases + + - [OpenHarmony v3.1 Beta (2021-12-31)](../release-notes/OpenHarmony-v3.1-beta.md) + - [OpenHarmony v3.0.1 LTS (2022-01-12)](../release-notes/OpenHarmony-v3.0.1-LTS.md) + - [OpenHarmony v3.0 LTS (2021-09-30)](../release-notes/OpenHarmony-v3.0-LTS.md) + + - OpenHarmony 2.x Releases + + - [OpenHarmony v2.2 beta2 (2021-08-04)](../release-notes/OpenHarmony-v2.2-beta2.md) + - [OpenHarmony 2.0 Canary (2021-06-01)](../release-notes/OpenHarmony-2-0-Canary.md) + + - OpenHarmony 1.x Releases + + - [OpenHarmony v1.1.4 LTS (2022-02-11)](../release-notes/OpenHarmony-v1-1-4-LTS.md) + - [OpenHarmony v1.1.3 LTS (2021-09-30)](../release-notes/OpenHarmony-v1-1-3-LTS.md) + - [OpenHarmony v1.1.2 LTS (2021-08-04)](../release-notes/OpenHarmony-v1.1.2-LTS.md) + - [OpenHarmony 1.1.1 LTS (2021-06-22)](../release-notes/OpenHarmony-1-1-1-LTS.md) + - [OpenHarmony 1.1.0 LTS (2021-04-01)](../release-notes/OpenHarmony-1-1-0-LTS.md) + - [OpenHarmony 1.0 (2020-09-10)](../release-notes/OpenHarmony-1-0.md) +- Quick Start + - [Getting Started with Application Development](quick-start/Readme-EN.md) +- Basics + + - [DevEco Studio \(OpenHarmony\) User Guide](quick-start/deveco-studio-user-guide-for-openharmony.md) + - [Overview](quick-start/deveco-studio-overview.md) + - [Version Change History](quick-start/deveco-studio-release-notes.md) + - [Configuring the OpenHarmony SDK](quick-start/configuring-openharmony-sdk.md) + - [Creating an OpenHarmony Project](quick-start/create-openharmony-project.md) + - [Using the Project Wizard to Create a Project](quick-start/use-wizard-to-create-project.md) + - [Importing a Sample to Create a Project](quick-start/import-sample-to-create-project.md) + + - [Configuring the OpenHarmony App Signature](quick-start/configuring-openharmony-app-signature.md) + - [Installing and Running Your OpenHarmony App](quick-start/installing-openharmony-app.md) + + - [Directory Structure](quick-start/package-structure.md) +- Development + - [ArkUI](ui/Readme-EN.md) +- UI + + - JavaScript-based Web-Like Development Paradigm + - [Overview](ui/ui-js-overview.md) + - Framework + - [File Organization](ui/js-framework-file.md) + - ["js" Tag](ui/js-framework-js-tag.md) + - [app.js](ui/js-framework-js-file.md) + - Syntax + - [HML](ui/js-framework-syntax-hml.md) + - [CSS](ui/js-framework-syntax-css.md) + - [JavaScript](ui/js-framework-syntax-js.md) + - [Lifecycle](ui/js-framework-lifecycle.md) + - [Resource Limitations and Access](ui/js-framework-resource-restriction.md) + - [Multi-Language Capability](ui/js-framework-multiple-languages.md) + - Building the UI + - [Component Overview](ui/ui-js-building-ui-component.md) + - Building the Layout + - [Layout Description](ui/ui-js-building-ui-layout-intro.md) + - [Adding Title and Paragraph Text](ui/ui-js-building-ui-layout-text.md) + - [Adding an Image](ui/ui-js-building-ui-layout-image.md) + - [Adding a Comment](ui/ui-js-building-ui-layout-comment.md) + - [Adding a Container](ui/ui-js-building-ui-layout-external-container.md) + - [Adding Interactions](ui/ui-js-building-ui-interactions.md) + - [Developing Animations](ui/ui-js-building-ui-animation.md) + - [Defining Events](ui/ui-js-building-ui-event.md) + - [Defining Page Routes](ui/ui-js-building-ui-routes.md) + - Common Component Development Guidelines + - [Text](ui/ui-js-components-text.md) + - [Input](ui/ui-js-components-input.md) + - [Button](ui/ui-js-components-button.md) + - [List](ui/ui-js-components-list.md) + - [Picker](ui/ui-js-components-picker.md) + - [Dialog](ui/ui-js-components-dialog.md) + - [Form](ui/ui-js-components-form.md) + - [Stepper](ui/ui-js-components-stepper.md) + - [Tabs](ui/ui-js-component-tabs.md) + - [Image](ui/ui-js-components-images.md) + - Animation Development Guidelines + - CSS Animation + - [Defining Attribute Style Animations](ui/ui-js-animate-attribute-style.md) + - [Defining Animations with the transform Attribute](ui/ui-js-animate-transform.md) + - [Defining Animations with the background-position Attribute](ui/ui-js-animate-background-position-style.md) + - JS Animation + - [Component Animation](ui/ui-js-animate-component.md) + - Interpolator Animation + - [Animation Effect](ui/ui-js-animate-dynamic-effects.md) + - [Animation Frame](ui/ui-js-animate-frame.md) + - [Custom Components](ui/ui-js-custom-components.md) + - TypeScript-based Declarative Development Paradigm + - [Overview](ui/ui-ts-overview.md) + - Framework Overview + - File Organization + - [Directory Structure](ui/ts-framework-directory.md) + - [Rules for Accessing Application Code Files](ui/ts-framework-file-access-rules.md) + - ["js" Tag](ui/ts-framework-js-tag.md) + - Resource Access + - [Media Resource Types](ui/ts-media-resource-type.md) + - [Pixel Units](ui/ts-pixel-units.md) + - [Types](ui/ts-types.md) + - Declarative Syntax + - [Overview](ui/ts-syntax-intro.md) + - General UI Description Specifications + - [Basic Concepts](ui/ts-general-ui-concepts.md) + - Declarative UI Description Specifications + - [Parameterless Configuration](ui/ts-parameterless-configuration.md) + - [Configuration with Mandatory Parameters](ui/ts-configuration-with-mandatory-parameters.md) + - [Attribution Configuration](ui/ts-attribution-configuration.md) + - [Event Configuration](ui/ts-event-configuration.md) + - [Child Component Configuration](ui/ts-child-component-configuration.md) + - Componentization + - [@Component](ui/ts-component-based-component.md) + - [@Entry](ui/ts-component-based-entry.md) + - [@Preview](ui/ts-component-based-preview.md) + - [@Builder](ui/ts-component-based-builder.md) + - [@Extend](ui/ts-component-based-extend.md) + - [@CustomDialog](ui/ts-component-based-customdialog.md) + - About UI State Management + - [Basic Concepts](ui/ts-ui-state-mgmt-concepts.md) + - Managing Component States + - [@State](ui/ts-component-states-state.md) + - [@Prop](ui/ts-component-states-prop.md) + - [@Link](ui/ts-component-states-link.md) + - Managing Application States + - [AppStorage](ui/ts-application-states-appstorage.md) + - [PersistentStorage](ui/ts-application-states-apis-persistentstorage.md) + - [Environment](ui/ts-application-states-apis-environment.md) + - Managing Other States + - [@observed and @objectLink](ui/ts-other-states-observed-objectlink.md) + - [@Consume and @Provide](ui/ts-other-states-consume-provide.md) + - [@Watch](ui/ts-other-states-watch.md) + - About Rendering Control Syntax + - [if/else](ui/ts-rending-control-syntax-if-else.md) + - [ForEach](ui/ts-rending-control-syntax-foreach.md) + - [LazyForEach](ui/ts-rending-control-syntax-lazyforeach.md) + - About @Component + - [build Function](ui/ts-function-build.md) + - [Custom Component Initialization](ui/ts-custom-component-initialization.md) + - [Custom Component Lifecycle Callbacks](ui/ts-custom-component-lifecycle-callbacks.md) + - [Example: Component Creation and Re-Initialization](ui/ts-component-creation-re-initialization.md) + - [Syntactic Sugar](ui/ts-syntactic-sugar.md) + - Experiencing the Declarative UI + - [Creating a Declarative UI Project](ui/ui-ts-creating-project.md) + - [Getting to Know Components](ui/ui-ts-components.md) + - [Creating a Simple Page](ui/ui-ts-creating-simple-page.md) + - Defining Page Layout and Connection + - [Building a Food Data Model](ui/ui-ts-building-data-model.md) + - [Building a Food Category List Layout](ui/ui-ts-building-category-list-layout.md) + - [Building a Food Category Grid Layout](ui/ui-ts-building-category-grid-layout.md) + - [Implementing Page Redirection and Data Transmission](ui/ui-ts-page-redirection-data-transmission.md) + - Basic Functions + - [Agent-Powered Scheduled Reminders ](background-agent-scheduled-reminder/Readme-EN.md) + - [Overview](background-agent-scheduled-reminder/background-agent-scheduled-reminder-overview.md) + - [Development Guidelines](background-agent-scheduled-reminder/background-agent-scheduled-reminder-guide.md) + - [Background Task Management ](background-task-management/Readme-EN.md) + - [Background Task Management Overview](background-task-management/background-task-overview.md) + - [Background Task Management Development](background-task-management/background-task-dev-guide.md) + - [WebGL](webgl/Readme-EN.md) + - [WebGL Overview](webgl/webgl-overview.md) + - [WebGL Development](webgl/webgl-guidelines.md) + - [Media](media/Readme-EN.md) + - Audio + + - [Audio Overview](media/audio-overview.md) + + - [Audio Playback Development](media/audio-playback.md) + + - [Audio Playback Development Using AudioRenderer](media/audio-renderer.md) + + - [Audio Management Development](media/audio-management.md) + + - [Audio Recording Development](media/audio-recorder.md) + + - [Audio Recorder Development Using AudioCapturer](media/audio-capturer) + - Video + + - [Video Playback Development](media/video-playback.md) + + - [Video Recording Development](media/video-recorder.md) + - [Security](security/Readme-EN.md) + - User Authentication + - [User Authentication Overview](security/userauth-overview.md) + - [User Authentication Development](security/userauth-guidelines.md) + - [Connectivity](connectivity/Readme-EN.md) + - [IPC & RPC](connectivity/ipc-rpc.md) + - [IPC & RPC Overview](connectivity/ipc-rpc-overview.md) + - [IPC & RPC Development Guidelines](connectivity/ipc-rpc-development-guideline.md) + - [Subscribing to State Changes of a Remote Object](connectivity/subscribe-remote-state.md) + - [Data Management](database/Readme-EN.md) + - Distributed Data Service + - [Distributed Data Service Overview](database/database-mdds-overview.md) + - [Distributed Data Service Development](database/database-mdds-guidelines.md) + - Relational Database Overview + - [RDB Overview](database/database-relational-overview.md) + - [RDB Development](database/database-relational-guidelines.md) + - Lightweight Data Store + - [Lightweight Data Store Overview](database/database-preference-overview.md) + - [Lightweight Data Store Development](database/database-preference-guidelines.md) + - [Device](device/Readme-EN.md) + - USB Service + - [USB Service Overview](device/usb-overview.md) + - [USB Service Development](device/usb-guidelines.md) + - Location + - [Location Overview](device/device-location-overview.md) + - [Obtaining Device Location Information](device/device-location-info.md) + - [Geocoding and Reverse Geocoding Capabilities](device/device-location-geocoding.md) + - [DFX](dfx/Readme-EN.md) + - Application Event Logging + - [Overview of Application Event Logging](dfx/hiappevent-overview.md) + - [Development Guidelines on Application Event Logging](dfx/hiappevent-guidelines.md) +- Tools + - [DevEco Studio \(OpenHarmony\) User Guide](quick-start/deveco-studio-user-guide-for-openharmony.md) + - [Overview](quick-start/deveco-studio-overview.md) + - [Version Change History](quick-start/deveco-studio-release-notes.md) + - [Configuring the OpenHarmony SDK](quick-start/configuring-openharmony-sdk.md) + - [Creating an OpenHarmony Project](quick-start/create-openharmony-project.md) + - [Configuring the OpenHarmony App Signature](quick-start/configuring-openharmony-app-signature.md) + - [Installing and Running Your OpenHarmony App](quick-start/installing-openharmony-app.md) +- Hands-On Tutorials + - [Samples](https://gitee.com/openharmony/app_samples/blob/master/README.md) +- API References + - [Compent Reference (JavaScript-based Web-like Development Paradigm)](reference/arkui-js/Readme-EN.md) + - [Components](reference/arkui-js/js-components.md) + - [Common](reference/arkui-js/js-components-common.md) + - [Universal Attributes](reference/arkui-js/js-components-common-attributes.md) + - [Universal Styles](reference/arkui-js/js-components-common-styles.md) + - [Universal Events](reference/arkui-js/js-components-common-events.md) + - [Universal Methods](reference/arkui-js/js-components-common-methods.md) + - [Animation Styles](reference/arkui-js/js-components-common-animation.md) + - [Gradient Styles](reference/arkui-js/js-components-common-gradient.md) + - [Transition Styles](reference/arkui-js/js-components-common-transition.md) + - [Media Query](reference/arkui-js/js-components-common-mediaquery.md) + - [Custom Font Styles](reference/arkui-js/js-components-common-customizing-font.md) + - [Atomic Layout](reference/arkui-js/js-components-common-atomic-layout.md) + + - [Container Component](reference/arkui-js/js-components-container.md) + - [badge](reference/arkui-js/js-components-container-badge.md) + - [dialog](reference/arkui-js/js-components-container-dialog.md) + - [div](reference/arkui-js/js-components-container-div.md) + - [form](reference/arkui-js/js-components-container-form.md) + - [list](reference/arkui-js/js-components-container-list.md) + - [list-item](reference/arkui-js/js-components-container-list-item.md) + - [list-item-group](reference/arkui-js/js-components-container-list-item-group.md) + - [panel](reference/arkui-js/js-components-container-panel.md) + - [popup](reference/arkui-js/js-components-container-popup.md) + - [refresh](reference/arkui-js/js-components-container-refresh.md) + - [stack](reference/arkui-js/js-components-container-stack.md) + - [stepper](reference/arkui-js/js-components-container-stepper.md) + - [stepper-item](reference/arkui-js/js-components-container-stepper-item.md) + - [swiper](reference/arkui-js/js-components-container-swiper.md) + - [tabs](reference/arkui-js/js-components-container-tabs.md) + - [tab-bar](reference/arkui-js/js-components-container-tab-bar.md) + - [tab-content](reference/arkui-js/js-components-container-tab-content.md) + + - [Basic Components](reference/arkui-js/js-components-basic.md) + - [button](reference/arkui-js/js-components-basic-button.md) + - [chart](reference/arkui-js/js-components-basic-chart.md) + - [divider](reference/arkui-js/js-components-basic-divider.md) + - [image](reference/arkui-js/js-components-basic-image.md) + - [image-animator](reference/arkui-js/js-components-basic-image-animator.md) + - [input](reference/arkui-js/js-components-basic-input.md) + - [label](reference/arkui-js/js-components-basic-label.md) + - [marquee](reference/arkui-js/js-components-basic-marquee.md) + - [menu](reference/arkui-js/js-components-basic-menu.md) + - [option](reference/arkui-js/js-components-basic-option.md) + - [picker](reference/arkui-js/js-components-basic-picker.md) + - [picker-view](reference/arkui-js/js-components-basic-picker-view.md) + - [piece](reference/arkui-js/js-components-basic-piece.md) + - [progress](reference/arkui-js/js-components-basic-progress.md) + - [qrcode](reference/arkui-js/js-components-basic-qrcode.md) + - [rating](reference/arkui-js/js-components-basic-rating.md) + - [richtext](reference/arkui-js/js-components-basic-richtext.md) + - [search](reference/arkui-js/js-components-basic-search.md) + - [select](reference/arkui-js/js-components-basic-select.md) + - [slider](reference/arkui-js/js-components-basic-slider.md) + - [span](reference/arkui-js/js-components-basic-span.md) + - [switch](reference/arkui-js/js-components-basic-switch.md) + - [text](reference/arkui-js/js-components-basic-text.md) + - [textarea](reference/arkui-js/js-components-basic-textarea.md) + - [toolbar](reference/arkui-js/js-components-basic-toolbar.md) + - [toolbar-item](reference/arkui-js/js-components-basic-toolbar-item.md) + - [toggle](reference/arkui-js/js-components-basic-toggle.md) + + - [Media Components](reference/arkui-js/js-components-media.md) + - [video](reference/arkui-js/js-components-media-video.md) + + - [Canvas Components](reference/arkui-js/js-components-canvas.md) + - [canvas](reference/arkui-js/js-components-canvas-canvas.md) + - [CanvasRenderingContext2D](reference/arkui-js/js-components-canvas-canvasrenderingcontext2d.md) + - [Image](reference/arkui-js/js-components-canvas-image.md) + - [CanvasGradient](reference/arkui-js/js-components-canvas-canvasgradient.md) + - [ImageData](reference/arkui-js/js-components-canvas-imagedata.md) + - [Path2D](reference/arkui-js/js-components-canvas-path2d.md) + - [ImageBitmap](reference/arkui-js/js-components-canvas-imagebitmap.md) + - [OffscreenCanvas](reference/arkui-js/js-components-canvas-offscreencanvas.md) + - [OffscreenCanvasRenderingContext2D](reference/arkui-js/js-offscreencanvasrenderingcontext2d.md) + + - [Grid](reference/arkui-js/js-components-grid.md) + - [Basic Concepts](reference/arkui-js/js-components-grid-basic-concepts.md) + - [grid-container](reference/arkui-js/js-components-grid-container.md) + - [grid-row](reference/arkui-js/js-components-grid-row.md) + - [grid-col](reference/arkui-js/js-components-grid-col.md) + + - [SVG Components](reference/arkui-js/js-svg.md) + - [Universal Attributes](reference/arkui-js/js-components-svg-common-attributes.md) + - [svg](reference/arkui-js/js-components-svg.md) + - [rect](reference/arkui-js/js-components-svg-rect.md) + - [circle](reference/arkui-js/js-components-svg-circle.md) + - [ellipse](reference/arkui-js/js-components-svg-ellipse.md) + - [path](reference/arkui-js/js-components-svg-path.md) + - [line](reference/arkui-js/js-components-svg-line.md) + - [polyline](reference/arkui-js/js-components-svg-polyline.md) + - [polygon](reference/arkui-js/js-components-svg-polygon.md) + - [text](reference/arkui-js/js-components-svg-text.md) + - [tspan](reference/arkui-js/js-components-svg-tspan.md) + - [textPath](reference/arkui-js/js-components-svg-textpath.md) + - [animate](reference/arkui-js/js-components-svg-animate.md) + - [animateMotion](reference/arkui-js/js-components-svg-animatemotion.md) + - [animateTransform](reference/arkui-js/js-components-svg-animatetransform.md) + + - [Custom Components](reference/arkui-js/js-components-custom.md) + - [Basic Usage](reference/arkui-js/js-components-custom-basic-usage.md) + - [Custom Events](reference/arkui-js/js-components-custom-events.md) + - [props](reference/arkui-js/js-components-custom-props.md) + - [Event Parameter](reference/arkui-js/js-components-custom-event-parameter.md) + - [slot](reference/arkui-js/js-components-custom-slot.md) + - [Lifecycle Definition](reference/arkui-js/js-components-custom-lifecycle.md) + + - [Appendix](reference/arkui-js/js-appendix.md) + - [Type Attributes](reference/arkui-js/js-appendix-types.md) + - [Compent Reference (TypeScript-based Declarative Development Paradigm)](reference/arkui-ts/Readme-EN.md) + - [Components](reference/arkui-ts/ts-components.md) + - [Universal Components](reference/arkui-ts/ts-universal-components.md) + - [Universal Events](reference/arkui-ts/ts-universal-events.md) + - [Click Event](reference/arkui-ts/ts-universal-events-click.md) + - [Touch](reference/arkui-ts/ts-universal-events-touch.md) + - [Show/Hide Event](reference/arkui-ts/ts-universal-events-show-hide.md) + - [Key Event](reference/arkui-ts/ts-universal-events-key.md) + - [Component Area Change Event](reference/arkui-ts/ts-universal-events-component-area-change.md) + + - [Universal Attributes](reference/arkui-ts/ts-universal-attributes.md) + - [Size](reference/arkui-ts/ts-universal-attributes-size.md) + - [Location](reference/arkui-ts/ts-universal-attributes-location.md) + - [Layout Constraints](reference/arkui-ts/ts-universal-attributes-layout-constraints.md) + - [Flex Layout](reference/arkui-ts/ts-universal-attributes-flex-layout.md) + - [Border Configuration](reference/arkui-ts/ts-universal-attributes-border.md) + - [Background](reference/arkui-ts/ts-universal-attributes-background.md) + - [Opacity](reference/arkui-ts/ts-universal-attributes-opacity.md) + - [Visibility](reference/arkui-ts/ts-universal-attributes-visibility.md) + - [Enable/Disable](reference/arkui-ts/ts-universal-attributes-enable.md) + - [Overlay](reference/arkui-ts/ts-universal-attributes-overlay.md) + - [Z-order Control](reference/arkui-ts/ts-universal-attributes-z-order.md) + - [Transformation](reference/arkui-ts/ts-universal-attributes-transformation.md) + - [Image Effect Configuration](reference/arkui-ts/ts-universal-attributes-image-effect.md) + - [Shape Clipping](reference/arkui-ts/ts-universal-attributes-sharp-clipping.md) + - [Text Style](reference/arkui-ts/ts-universal-attributes-text-style.md) + - [Grid](reference/arkui-ts/ts-universal-attributes-grid.md) + - [Gradient Color](reference/arkui-ts/ts-universal-attributes-gradient-color.md) + - [Popup Control](reference/arkui-ts/ts-universal-attributes-popup.md) + - [Menu Control](reference/arkui-ts/ts-universal-attributes-menu.md) + - [Click Control](reference/arkui-ts/ts-universal-attributes-touchable.md) + - [Touch Target](reference/arkui-ts/ts-universal-attributes-response-region.md) + + - [Gesture Processing](reference/arkui-ts/ts-gesture-processing.md) + - [Gesture Binding Methods](reference/arkui-ts/ts-gesture-settings.md) + - [Basic Gestures](reference/arkui-ts/ts-basic-gestures.md) + - [TapGesture](reference/arkui-ts/ts-basic-gestures-tapgesture.md) + - [LongPressGesture](reference/arkui-ts/ts-basic-gestures-longpressgesture.md) + - [PanGesture](reference/arkui-ts/ts-basic-gestures-pangesture.md) + - [PinchGesture](reference/arkui-ts/ts-basic-gestures-pinchgesture.md) + - [RotationGesture](reference/arkui-ts/ts-basic-gestures-rotationgesture.md) + - [SwipeGesture](reference/arkui-ts/ts-basic-gestures-swipegesture.md) + + - [Combined Gestures](reference/arkui-ts/ts-combined-gestures.md) + + - [Basic Components](reference/arkui-ts/ts-basic-components.md) + - [Blank](reference/arkui-ts/ts-basic-components-blank.md) + - [Button](reference/arkui-ts/ts-basic-components-button.md) + - [DataPanel](reference/arkui-ts/ts-basic-components-datapanel.md) + - [Divider](reference/arkui-ts/ts-basic-components-divider.md) + - [Gauge](reference/arkui-ts/ts-basic-components-gauge.md) + - [Image](reference/arkui-ts/ts-basic-components-image.md) + - [ImageAnimator](reference/arkui-ts/ts-basic-components-imageanimator.md) + - [LoadingProgress](reference/arkui-ts/ts-basic-components-loadingprogress.md) + - [Marquee](reference/arkui-ts/ts-basic-components-marquee.md) + - [Progress](reference/arkui-ts/ts-basic-components-progress.md) + - [QRCode](reference/arkui-ts/ts-basic-components-qrcode.md) + - [Rating](reference/arkui-ts/ts-basic-components-rating.md) + - [Select](reference/arkui-ts/ts-basic-components-select.md) + - [Slider](reference/arkui-ts/ts-basic-components-slider.md) + - [Span](reference/arkui-ts/ts-basic-components-span.md) + - [Text](reference/arkui-ts/ts-basic-components-text.md) + - [TextArea](reference/arkui-ts/ts-basic-components-textarea.md) + - [TextInput](reference/arkui-ts/ts-basic-components-textinput.md) + - [Toggle](reference/arkui-ts/ts-basic-components-toggle.md) + - [TextClock](reference/arkui-ts/ts-basic-components-textclock.md) + + - [Container Components](reference/arkui-ts/ts-components-container.md) + - [AlphabetIndexer](reference/arkui-ts/ts-container-alphabet-indexer.md) + - [Badge](reference/arkui-ts/ts-container-badge.md) + - [Column](reference/arkui-ts/ts-container-column.md) + - [ColumnSplit](reference/arkui-ts/ts-container-columnsplit.md) + - [Counter](reference/arkui-ts/ts-container-counter.md) + - [Flex](reference/arkui-ts/ts-container-flex.md) + - [GridContainer](reference/arkui-ts/ts-container-gridcontainer.md) + - [Grid](reference/arkui-ts/ts-container-grid.md) + - [GridItem](reference/arkui-ts/ts-container-griditem.md) + - [List](reference/arkui-ts/ts-container-list.md) + - [ListItem](reference/arkui-ts/ts-container-listitem.md) + - [Navigator](reference/arkui-ts/ts-container-navigator.md) + - [Navigation](reference/arkui-ts/ts-container-navigation.md) + - [Panel](reference/arkui-ts/ts-container-panel.md) + - [Row](reference/arkui-ts/ts-container-row.md) + - [RowSplit](reference/arkui-ts/ts-container-rowsplit.md) + - [Scroll](reference/arkui-ts/ts-container-scroll.md) + - [ScrollBar](reference/arkui-ts/ts-container-scrollbar.md) + - [Stack](reference/arkui-ts/ts-container-stack.md) + - [Swiper](reference/arkui-ts/ts-container-swiper.md) + - [Tabs](reference/arkui-ts/ts-container-tabs.md) + - [TabContent](reference/arkui-ts/ts-container-tabcontent.md) + + - [Refresh](reference/arkui-ts/ts-container-refresh.md) + - [Drawing Components](reference/arkui-ts/ts-drawing-components.md) + + - [Circle](reference/arkui-ts/ts-drawing-components-circle.md) + - [Ellipse](reference/arkui-ts/ts-drawing-components-ellipse.md) + - [Line](reference/arkui-ts/ts-drawing-components-line.md) + - [Polyline](reference/arkui-ts/ts-drawing-components-polyline.md) + - [Polygon](reference/arkui-ts/ts-drawing-components-polygon.md) + - [Path](reference/arkui-ts/ts-drawing-components-path.md) + - [Rect](reference/arkui-ts/ts-drawing-components-rect.md) + - [Shape](reference/arkui-ts/ts-drawing-components-shape.md) + + - [Canvas Components](reference/arkui-ts/ts-components-canvas.md) + - [Canvas](reference/arkui-ts/ts-components-canvas-canvas.md) + - [CanvasRenderingContext2D](reference/arkui-ts/ts-canvasrenderingcontext2d.md) + - [OffscreenCanvasRenderingConxt2D](reference/arkui-ts/ts-offscreencanvasrenderingcontext2d.md) + - [Lottie](reference/arkui-ts/ts-components-canvas-lottie.md) + - [Path2D](reference/arkui-ts/ts-components-canvas-path2d.md) + - [CanvasGradient](reference/arkui-ts/ts-components-canvas-canvasgradient.md) + - [ImageBitmap](reference/arkui-ts/ts-components-canvas-imagebitmap.md) + - [ImageData](reference/arkui-ts/ts-components-canvas-imagedata.md) + - [Animation](reference/arkui-ts/ts-animation.md) + - [Attribute Animation](reference/arkui-ts/ts-animatorproperty.md) + - [Explicit Animation](reference/arkui-ts/ts-explicit-animation.md) + - [Transition Animation](reference/arkui-ts/ts-transition-animation.md) + - [Page Transition](reference/arkui-ts/ts-page-transition-animation.md) + - [Component Transition](reference/arkui-ts/ts-transition-animation-component.md) + - [Transition of Shared Elements](reference/arkui-ts/ts-transition-animation-shared-elements.md) + + - [Motion Path Animation](reference/arkui-ts/ts-motion-path-animation.md) + - [Matrix Transformation](reference/arkui-ts/ts-matrix-transformation.md) + - [Interpolation Calculation](reference/arkui-ts/ts-interpolation-calculation.md) + + - [Global UI Methods](reference/arkui-ts/ts-global-ui-methods.md) + - [Alert Dialog Box](reference/arkui-ts/ts-methods-alert-dialog-box.md) + - [Custom Dialog box](reference/arkui-ts/ts-methods-custom-dialog-box.md) + - [Image Cache](reference/arkui-ts/ts-methods-image-cache.md) + - [Media Query](reference/arkui-ts/ts-methods-media-query.md) + - [List Selection Dialog Box](reference/arkui-ts/ts-methods-action-sheet.md) + + - [Appendix](reference/arkui-ts/ts-appendix.md) + + - [Built-in Enums](reference/arkui-ts/ts-appendix-enums.md) + - [APIs](reference/apis/Readme-EN.md) + - Ability Framework + - [FeatureAbility Module](reference/apis/js-apis-featureAbility.md) + - [ParticleAbility Module](reference/apis/js-apis-particleAbility.md) + - [DataAbilityHelper Module](reference/apis/js-apis-dataAbilityHelper.md) + - [DataUriUtils Module](reference/apis/js-apis-DataUriUtils.md) + - [Bundle Module](reference/apis/js-apis-Bundle.md) + - [Context Module](reference/apis/js-apis-Context.md) + - Event Notification + - [CommonEvent Module](reference/apis/js-apis-commonEvent.md) + - [Notification Module](reference/apis/js-apis-notification.md) + - [Reminder Agent](reference/apis/js-apis-reminderAgent.md) + - Resource Management + - [Resource Manager](reference/apis/js-apis-resource-manager.md) + - [Internationalization \(intl\) ](reference/apis/js-apis-intl.md) + - [Internationalization \(i18n\) ](reference/apis/js-apis-i18n.md) + - Media + - [Audio Management](reference/apis/js-apis-audio.md) + - [Media](reference/apis/js-apis-media.md) + - Security + - [User Authentication](reference/apis/js-apis-useriam-userauth.md) + - [Access Control](reference/apis/js-apis-abilityAccessCtrl.md) + - Data Management + - [Lightweight Storage (deprecated since 8)](reference/apis/js-apis-data-storage.md) + - [Distributed Data Management](reference/apis/js-apis-distributed-data.md) + - [Relational Database](reference/apis/js-apis-data-rdb.md) + - [Result Set](reference/apis/js-apis-data-resultset.md) + - [DataAbilityPredicates](reference/apis/js-apis-data-ability.md) + - [Settings](reference/apis/js-apis-settings.md) + - File Management + - [File Management](reference/apis/js-apis-fileio.md) + - [Statfs](reference/apis/js-apis-statfs.md) + - [Environment](reference/apis/js-apis-environment.md) + - [Public File Access and Management](reference/apis/js-apis-filemanager.md) + - [App Storage Statistics](reference/apis/js-apis-storage-statistics.md) + - [Volume Management](reference/apis/js-apis-volumemanager.md) + - Account Management + - [Distributed Account Management](reference/apis/js-apis-distributed-account.md) + - [App Account Management](reference/apis/js-apis-appAccount.md) + - Telephony Service + - [Call](reference/apis/js-apis-call.md) + - [SMS](reference/apis/js-apis-sms.md) + - [SIM Management](reference/apis/js-apis-sim.md) + - [Radio](reference/apis/js-apis-radio.md) + - [observer](reference/apis/js-apis-observer.md) + - [Cellular Data](reference/apis/js-apis-telephony-data.md) + - Network and Connectivity + - [WLAN](reference/apis/js-apis-wifi.md) + - [Bluetooth](reference/apis/js-apis-bluetooth.md) + - [RPC](reference/apis/js-apis-rpc.md) + - Device Management + - [Sensor](reference/apis/js-apis-sensor.md) + - [Vibrator](reference/apis/js-apis-vibrator.md) + - [Brightness](reference/apis/js-apis-brightness.md) + - [Battery Info](reference/apis/js-apis-battery-info.md) + - [Power Management](reference/apis/js-apis-power.md) + - [Thermal Management](reference/apis/js-apis-thermal.md) + - [Running Lock](reference/apis/js-apis-runninglock.md) + - [Device Info](reference/apis/js-apis-device-info.md) + - [systemParameter](reference/apis/js-apis-system-parameter.md) + - [Device Management](reference/apis/js-apis-device-manager.md) + - [Window](reference/apis/js-apis-window.md) + - [Display](reference/apis/js-apis-display.md) + - [Update](reference/apis/js-apis-update.md) + - [USB](reference/apis/js-apis-usb.md) + - [Location](reference/apis/js-apis-geolocation.md) + - Basic Features + - [Application Context](reference/apis/js-apis-basic-features-app-context.md) + - [Console Logs](reference/apis/js-apis-basic-features-logs.md) + - [Page Routing](reference/apis/js-apis-basic-features-routes.md) + - [Pop-up Window](reference/apis/js-apis-basic-features-pop-up.md) + - [Application Configuration](reference/apis/js-apis-basic-features-configuration.md) + - [Timer](reference/apis/js-apis-basic-features-timer.md) + - [Setting the System Time](reference/apis/js-apis-system-time.md) + - [Animation](reference/apis/js-apis-basic-features-animator.md) + - [WebGL](reference/apis/js-apis-webgl.md) + - [WebGL2](reference/apis/js-apis-webgl2.md) + - [Screenshot](reference/apis/js-apis-screenshot.md) + - DFX + - [HiAppEvent](reference/apis/js-apis-hiappevent.md) + - [Performance Tracing](reference/apis/js-apis-hitracemeter.md) + - [Fault Logger](reference/apis/js-apis-faultLogger.md) + - [Distributed Call Chain Tracing](reference/apis/js-apis-hitracechain.md) + - [HiLog](reference/apis/js-apis-hilog.md) + - [HiChecker](reference/apis/js-apis-hichecker.md) + - [HiDebug](reference/apis/js-apis-hidebug.md) + - Language Base Class Library + - [Obtaining Process Information](reference/apis/js-apis-process.md) + - [URL String Parsing](reference/apis/js-apis-url.md) + - [URI String Parsing](reference/apis/js-apis-uri.md) + - [Util](reference/apis/js-apis-util.md) + - [XML Parsing and Generation](reference/apis/js-apis-xml.md) + - [XML-to-JavaScript Conversion](reference/apis/js-apis-convertxml.md) + - [Worker Startup](reference/apis/js-apis-worker.md) + - [Linear Container ArrayList](reference/apis/js-apis-arraylist.md) + - [Linear Container Deque](reference/apis/js-apis-deque.md) + - [Linear Container List](reference/apis/js-apis-list.md) + - [Linear Container LinkedList](reference/apis/js-apis-linkedlist.md) + - [Linear Container Queue](reference/apis/js-apis-queue.md) + - [Linear Container Stack](reference/apis/js-apis-stack.md) + - [Linear Container Vector](reference/apis/js-apis-vector.md) + - [Nonlinear Container HashSet](reference/apis/js-apis-hashset.md) + - [Nonlinear Container HashMap](reference/apis/js-apis-hashmap.md) + - [Nonlinear Container PlainArray](reference/apis/js-apis-plainarray.md) + - [Nonlinear Container TreeMap](reference/apis/js-apis-treemap.md) + - [Nonlinear Container TreeSet](reference/apis/js-apis-treeset.md) + - [Nonlinear Container LightWeightMap](reference/apis/js-apis-lightweightmap.md) + - [Nonlinear Container LightWeightSet](reference/apis/js-apis-lightweightset.md) +- Contribution + - [How to Contribute](../contribute/documentation-contribution.md) \ No newline at end of file diff --git a/en/application-dev/media/Readme-EN.md b/en/application-dev/media/Readme-EN.md index 512b228d02..1ffa6f76d5 100755 --- a/en/application-dev/media/Readme-EN.md +++ b/en/application-dev/media/Readme-EN.md @@ -13,13 +13,8 @@ - [Audio Recording Development](audio-recorder.md) - [Audio Recorder Development Using AudioCapturer](audio-capturer) - - Video - [Video Playback Development](video-playback.md) - [Video Recording Development](video-recorder.md) - -- Sound - - - [SoundManager Development](sound-manager.md) diff --git a/zh-cn/application-dev/application-dev-website.md b/zh-cn/application-dev/application-dev-website.md index 8f77189f0c..22a7977fb9 100644 --- a/zh-cn/application-dev/application-dev-website.md +++ b/zh-cn/application-dev/application-dev-website.md @@ -1,14 +1,9 @@ # 应用开发 - [应用开发导读](application-dev-guide.md) - - 了解OpenHarmony - [了解OpenHarmony开源项目](../OpenHarmony-Overview_zh.md) - - - [了解OpenHarmony系统](../readme) - - [术语](../device-dev/glossary/glossary.md) - - [版本说明](../release-notes/Readme.md) - OpenHarmony 3.x Releases @@ -30,7 +25,6 @@ - [OpenHarmony 1.1.1 LTS (2021-06-22)](../release-notes/OpenHarmony-1-1-1-LTS.md) - [OpenHarmony 1.1.0 LTS (2021-04-01)](../release-notes/OpenHarmony-1-1-0-LTS.md) - [OpenHarmony 1.0 (2020-09-10)](../release-notes/OpenHarmony-1-0.md) - - 快速开始 - [应用开发快速入门](quick-start/Readme-CN.md) - DevEco Studio（OpenHarmony）使用指南 @@ -43,7 +37,6 @@ - [配置OpenHarmony应用签名信息](quick-start/configuring-openharmony-app-signature.md) - [安装运行OpenHarmony应用](quick-start/installing-openharmony-app.md) - [应用开发包结构说明](quick-start/quick-start/package-structure.md) - - 开发 - [Ability开发](ability/Readme-CN.md) - [Ability框架概述](ability/ability-brief.md) @@ -262,7 +255,6 @@ - 分布式跟踪 - [分布式跟踪概述](dfx/hitracechain-overview.md) - [分布式跟踪开发指导](dfx/hitracechain-guidelines.md) - - 工具 - [DevEco Studio（OpenHarmony）使用指南](quick-start/deveco-studio-user-guide-for-openharmony.md) - [概述](quick-start/deveco-studio-overview.md) @@ -271,12 +263,10 @@ - [创建OpenHarmony工程](quick-start/create-openharmony-project.md) - [配置OpenHarmony应用签名信息](quick-start/configuring-openharmony-app-signature.md) - [安装运行OpenHarmony应用](quick-start/installing-openharmony-app.md) - - 示例教程 - [示例代码](https://gitee.com/openharmony/app_samples/blob/master/README_zh.md) - [Codelabs](https://gitee.com/openharmony/codelabs/blob/master/README.md) - - API参考 - [组件参考（基于JS扩展的类Web开发范式）](reference/arkui-js/Readme-CN.md) - 组件 @@ -644,7 +634,6 @@ - 定制管理 - [配置策略](reference/apis/js-apis-config-policy.md) - [企业设备管理](reference/apis/js-apis-enterprise-device-manager.md) - - 贡献 - [参与贡献](../contribute/贡献文档.md) \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/Readme-CN.md b/zh-cn/application-dev/reference/apis/Readme-CN.md index e7da78c843..ff67949950 100644 --- a/zh-cn/application-dev/reference/apis/Readme-CN.md +++ b/zh-cn/application-dev/reference/apis/Readme-CN.md @@ -54,6 +54,7 @@ - [Socket连接](js-apis-socket.md) - [WebSocket连接](js-apis-webSocket.md) - [数据请求](js-apis-http.md) + - [上传下载](js-apis-request.md) - 通信与连接 - [WLAN](js-apis-wifi.md) - [Bluetooth](js-apis-bluetooth.md) @@ -81,7 +82,10 @@ - [弹窗](js-apis-basic-features-pop-up.md) - [应用配置](js-apis-basic-features-configuration.md) - [定时器](js-apis-basic-features-timer.md) + - [锁屏管理](js-apis-screen-lock.md) - [设置系统时间](js-apis-system-time.md) + - [壁纸](js-apis-wallpaper.md) + - [剪贴板](js-apis-pasteboard.md) - [动画](js-apis-basic-features-animator.md) - [WebGL](js-apis-webgl.md) - [WebGL2](js-apis-webgl2.md) diff --git a/zh-cn/application-dev/reference/apis/js-apis-pasteboard.md b/zh-cn/application-dev/reference/apis/js-apis-pasteboard.md new file mode 100644 index 0000000000..169bf06fbf --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-pasteboard.md @@ -0,0 +1,1047 @@ +# 剪贴板 + + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + +## 导入模块 + + +``` +import pasteboard from '@ohos.pasteboard'; +``` + + +## 属性 + +**系统能力**: 以下各项对应的系统能力均为SystemCapability.Miscservices.Pasteboard。 + +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| -------- | -------- | -------- | -------- | -------- | +| MAX_RECORD_NUM 7+ | number | 是 | 否 | 单个PasteData中所能包含的Record的数量上限。 | +| MIMETYPE_TEXT_HTML7+ | string | 是 | 否 | HTML text文本的MIME类型定义。 | +| MIMETYPE_TEXT_WANT7+ | string | 是 | 否 | Want的MIME类型定义。 | +| MIMETYPE_TEXT_PLAIN7+ | string | 是 | 否 | Plain text文本的MIME类型定义。 | +| MIMETYPE_TEXT_URI7+ | string | 是 | 否 | URI文本的MIME类型定义。 | + + +## pasteboard.createPlainTextData + +createPlainTextData(text:string): PasteData + +构建一个纯文本剪贴板内容对象。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | text | string | 是 | 纯文本数据。 | + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | [PasteData](#pastedata) | 包含此内容的剪贴板内容对象。 | + +- 示例 + + ``` + var pasteData = pasteboard.createPlainTextData("content"); + ``` + + +## pasteboard.createHtmlData7+ + +createHtmlData(htmlText:string): PasteData + +构建一个html文本剪贴板内容对象。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | htmlText | string | 是 | 待保存的HTML文本内容。 | + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | [PasteData](#pastedata) | 包含此内容的剪贴板内容对象。 | + +- 示例 + + ``` + var html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; + var pasteData = pasteboard.createHtmlData(html); + ``` + + +## pasteboard.createWantData7+ + +createWantData(want:Want): PasteData + +构建一个want剪贴板内容对象。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | want | [ERROR:Invalid link:zh-cn_topic_0000001153972080.xml#xref16101652152415,link:zh-cn_topic_0000001153498376.xml#section249133711278](zh-cn_topic_0000001153498376.xml#section249133711278) | 是 | 待保存的Want内容。 | + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | [PasteData](#pastedata) | 包含此内容的剪贴板内容对象。 | + +- 示例 + + ``` + var object = { + bundleName: "com.huawei.aafwk.test", + abilityName: "com.huawei.aafwk.test.TwoAbility" + }; + var pasteData = pasteboard.createWantData(object); + ``` + + +## pasteboard.createUriData7+ + +createUriData(uri:string): PasteData + +构建一个URI剪贴板内容对象。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | uri | string | 是 | 待保存的URI内容。 | + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | [PasteData](#pastedata) | 包含此内容的剪贴板内容对象。 | + +- 示例 + + ``` + var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1?user.txt"); + ``` + + +## pasteboard.createPlainTextRecord7+ + +createPlainTextRecord(text:string): PasteDataRecord + +创建一条文本类型的内容条目。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | text | string | 是 | 纯文本内容。 | + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | [PasteDataRecord](#pastedatarecord7) | 一条新建的纯文本内容条目。 | + +- 示例 + + ``` + var record = pasteboard.createPlainTextRecord("hello"); + ``` + + +## pasteboard.createHtmlTextRecord7+ + +createHtmlTextRecord(htmlText:string): PasteDataRecord + +创建一条HTML内容的条目。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | htmlText | string | 是 | 文本内容。 | + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | [PasteDataRecord](#pastedatarecord7) | 一条新建的HTML内容条目。 | + +- 示例 + + ``` + var html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; + var record = pasteboard.createHtmlTextRecord(html); + ``` + + +## pasteboard.createWantRecord7+ + +createWantRecord(want:Want): PasteDataRecord + +创建一条Want内容条目。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | want | [ERROR:Invalid link:zh-cn_topic_0000001153972080.xml#xref1929278214,link:zh-cn_topic_0000001153498376.xml#section249133711278](zh-cn_topic_0000001153498376.xml#section249133711278) | 是 | Want类型数据。 | + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | [PasteDataRecord](#pastedatarecord7) | 一条新建的Want内容条目 | + +- 示例 + + ``` + var object = { + bundleName: "com.huawei.aafwk.test", + abilityName: "com.huawei.aafwk.test.TwoAbility" + }; + var record = pasteboard.createWantRecord(object); + ``` + + +## pasteboard.createUriRecord7+ + +createUriRecord(uri:string): PasteDataRecord + +创建一条URI内容的条目。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | uri | string | 是 | URI内容。 | + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | [PasteDataRecord](#pastedatarecord7) | 一条新建的URI内容条目。 | + +- 示例 + + ``` + var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt"); + ``` + + +## PasteDataProperty7+ + +定义了剪贴板中所有内容条目的属性，包含时间戳、数据类型以及一些附加数据等。 + +**系统能力**: 以下各项对应的系统能力均为SystemCapability.Miscservices.Pasteboard。 + + | 名称 | 参数类型 | 可读 | 可写 | 说明 | +| -------- | -------- | -------- | -------- | -------- | +| additions | {[key: string]: object} | 是 | 是 | 设置的其他附加属性数据。 | +| mimeTypes | Array<string> | 是 | 否 | 剪贴板内容条目的数据类型, 非重复的类型列表。 | +| tag | string | 是 | 是 | 用户自定义标签。 | +| timestamp | number | 是 | 否 | 剪贴板数据的写入时间戳（毫秒）。 | +| localOnly | boolean | 是 | 是 | 配置剪贴板内容的“仅在本地”标志位。
- 默认情况为true。
- 配置为true时，表示内容仅在本地，不会在设备之间传递。
- 配置为false时，表示内容将在设备间传递。 | + + +## PasteDataRecord7+ + +对于剪贴板中内容记录的抽象定义，称之为条目。剪贴板内容部分由一个或者多个条目构成，例如一条文本内容、一份HTML、一个URI或者一个Want。 + + +### 属性 + +**系统能力**: 以下各项对应的系统能力均为SystemCapability.Miscservices.Pasteboard。 + +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| -------- | -------- | -------- | -------- | -------- | +| htmlText7+ | string | 是 | 否 | HTML文本内容。 | +| want7+ | [ERROR:Invalid link:zh-cn_topic_0000001153972080.xml#xref97376211378,link:zh-cn_topic_0000001153498376.xml#section249133711278](zh-cn_topic_0000001153498376.xml#section249133711278) | 是 | 否 | Want文本内容。 | +| mimeType7+ | string | 是 | 否 | 数据类型。 | +| plainText7+ | string | 是 | 否 | 文本内容。 | +| uri7+ | string | 是 | 否 | URI内容。 | + + +### convertToText7+ + +convertToText(): Promise<string> + +实例方法，将一个PasteData中的内容强制转换为文本内容，并使用Promise异步方式返回结果。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | Promise<void> | 异步回调函数，调用成功则返回强制转换的文本内容，调用失败则返回error信息。 | + +- 示例 + + ``` + var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt"); + record.convertToText().then((data) => { + console.info('convertToText success data : ' + JSON.stringify(data)); + }).catch((error) => { + console.error('convertToText failed because ' + JSON.stringify(error)); + }); + ``` + + +### convertToText7+ + +convertToText(callback: AsyncCallback<string>): void + +实例方法，将一个PasteData中的内容强制转换为文本内容，并使用callback方式返回结果。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<string> | 是 | 回调函数，调用成功则返回强制转换的文本内容，调用失败则返回error信息。 | + +- 示例 + + ``` + var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt"); + record.convertToText((err, data) => { + if (err) { + console.error('convertToText failed because ' + JSON.stringify(err)); + return; + } + console.info('convertToText success data : ' + JSON.stringify(data)); + }); + ``` + + +## PasteData + +在调用PasteData的接口前，需要先获取一个PasteData对象。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + + +### getPrimaryText + + +getPrimaryText(): string + + +获取首个条目的纯文本内容。 + + +**系统能力**: SystemCapability.Miscservices.Pasteboard + + +- 参数 + 无 + + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | string | 纯文本内容。 | + +- 示例 + + ``` + var pasteData = pasteboard.createPlainTextData("hello"); + var plainText = pasteData.getPrimaryText(); + ``` + + +### getPrimaryHtml7+ + +getPrimaryHtml(): string + +获取首个条目的HTML文本内容。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | string | HTML文本数据。 | + +- 示例 + + ``` + var html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; + var pasteData = pasteboard.createHtmlData(html); + var htmlText = pasteData.getPrimaryHtml(); + ``` + + +### getPrimaryWant7+ + +getPrimaryWant(): Want + +获取首个条目的Want对象内容。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | [ERROR:Invalid link:zh-cn_topic_0000001153972080.xml#xref731715497254,link:zh-cn_topic_0000001153498376.xml#section249133711278](zh-cn_topic_0000001153498376.xml#section249133711278) | Want对象内容。 | + +- 示例 + + ``` + var object = { + bundleName: "com.huawei.aafwk.test", + abilityName: "com.huawei.aafwk.test.TwoAbility" + }; + var pasteData = pasteboard.createWantData(object); + var want = pasteData.getPrimaryWant(); + ``` + + +### getPrimaryUri7+ + +getPrimaryUri(): string + +获取首个条目的URI文本内容。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | string | URI文本内容。 | + +- 示例 + + ``` + var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1?user.txt); + var uri = pasteData.getPrimaryUri(); + ``` + + +### addTextRecord7+ + +addTextRecord(text: string): void + +向当前剪贴板内容中添加一条纯文本条目，并将MIME_TEXT_PLAIN添加到[PasteDataProperty](#pastedataproperty7)的mimeTypes中。入参均不能为空，否则添加失败。 + +剪贴板内容中添加的条目达到数量上限128后，后续的添加操作无效。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | text | string | 是 | 纯文本内容。 | + +- 示例 + + ``` + var pasteData = pasteboard.createPlainTextData("hello"); + pasteData.addTextRecord("good"); + ``` + + +### addHtmlRecord7+ + +addHtmlRecord(htmlText: string): void + +向当前剪贴板内容中添加一条HTML文本条目，并将MIMETYPE_TEXT_HTML添加到[PasteDataProperty](#pastedataproperty7)的mimeTypes中。入参均不能为空，否则添加失败。 + +剪贴板内容中添加的条目达到数量上限128后，后续的添加操作无效。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | htmlText | string | 是 | HTML格式的文本内容。 | + +- 示例 + + ``` + var pasteData = pasteboard.createPlainTextData("hello"); + var html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; + pasteData.addHtmlRecord(html); + ``` + + +### addWantRecord7+ + +addWantRecord(want: [ERROR:Invalid link:zh-cn_topic_0000001153972080.xml#xref13369155013717,link:zh-cn_topic_0000001153498376.xml#section249133711278](zh-cn_topic_0000001153498376.xml#section249133711278)): void + +向当前剪贴板内容中添加一条Want条目，并将MIMETYPE_TEXT_INTENT添加到[PasteDataProperty](#pastedataproperty7)的mimeTypes中。入参均不能为空，否则添加失败。 + +剪贴板内容中添加的条目达到数量上限128后，后续的添加操作无效。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | want | [ERROR:Invalid link:zh-cn_topic_0000001153972080.xml#xref179262227253,link:zh-cn_topic_0000001153498376.xml#section249133711278](zh-cn_topic_0000001153498376.xml#section249133711278) | 是 | Want对象内容。 | + +- 示例 + + ``` + var pasteData = pasteboard.createPlainTextData("hello"); + var object = { + bundleName: "com.huawei.aafwk.test", + abilityName: "com.huawei.aafwk.test.TwoAbility" + }; + pasteData.addWantRecord(object); + ``` + + +### addUriRecord7+ + +addUriRecord(uri: string): void + +向当前剪贴板内容中添加一条URI条目，并将MIMETYPE_TEXT_URI添加到[PasteDataProperty](#pastedataproperty7)的mimeTypes中。入参均不能为空，否则添加失败。 + +剪贴板内容中添加的条目达到数量上限128后，后续的添加操作无效。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | uri | string | 是 | URI文本内容。 | + +- 示例 + + ``` + var pasteData = pasteboard.createPlainTextData("hello"); + pasteData.addUriRecord("dataability:///com.example.myapplication1?user.txt"); + ``` + + +### addRecord7+ + +addRecord(record: PasteDataRecord): void + +向当前剪贴板内容中添加一条条目，同时也会将条目类型添加到[PasteDataProperty](#pastedataproperty7)的mimeTypes中。入参均不能为空，否则添加失败。 + +剪贴板内容中添加的条目达到数量上限128后，后续的添加操作无效。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | record | [PasteDataRecord](#pastedatarecord7) | 是 | 待添加的条目。 | + +- 示例 + + ``` + var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1?user.txt"); + var textRecord = pasteboard.createPlainTextRecord("hello"); + var html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; + var htmlRecord = pasteboard.createHtmlTextRecord(html); + pasteData.addRecord(textRecord); + pasteData.addRecord(htmlRecord); + ``` + + +### getMimeTypes7+ + +getMimeTypes(): Array<string> + +获取剪贴板中[PasteDataProperty](#pastedataproperty7)的mimeTypes列表，当剪贴板内容为空时，返回列表为空。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | Array<string> | 非重复的类型列表。 | + +- 示例 + + ``` + var pasteData = pasteboard.createPlainTextData("hello"); + var types = pasteData.getMimeTypes(); + ``` + + +### getPrimaryMimeType7+ + +getPrimaryMimeType(): string + +获取首个条目的数据类型。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | string | 首个条目的数据类型。 | + +- 示例 + + ``` + var pasteData = pasteboard.createPlainTextData("hello"); + var type = pasteData.getPrimaryMimeType(); + ``` + + +### getProperty7+ + +getProperty(): PasteDataProperty + +获取属性描述对象。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | [PasteDataProperty](#pastedataproperty7) | 属性描述对象。 | + +- 示例 + + ``` + var pasteData = pasteboard.createPlainTextData("hello"); + var property = pasteData.getProperty(); + ``` + + +### getRecordAt7+ + +getRecordAt(index: number): PasteDataRecord + +获取指定下标的条目。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | index | number | 是 | 指定条目的下标。 | + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | [PasteDataRecord](#pastedatarecord7) | 指定下标的条目。 | + +- 示例 + + ``` + var pasteData = pasteboard.createPlainTextData("hello"); + var record = pasteData.getRecordAt(0); + ``` + + +### getRecordCount7+ + +getRecordCount(): number + +获取剪贴板中条目的个数。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | number | 条目的个数。 | + +- 示例 + + ``` + var pasteData = pasteboard.createPlainTextData("hello"); + var count = pasteData.getRecordCount(); + ``` + + +### getTag7+ + +getTag(): string + +获取用户自定义的标签内容，如果没有设置用户自定义的标签内容将返回空。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | string | 获取用户自定义的标签内容，如果没有设置用户自定义的标签内容将返回空。 | + +- 示例 + + ``` + var pasteData = pasteboard.createPlainTextData("hello"); + var tag = pasteData.getTag(); + ``` + + +### hasMimeType7+ + +hasMimeType(mimeType: string): boolean + +检查内容中是否有指定的数据类型。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | mimeType | string | 是 | 待查询的数据类型。 | + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | boolean | 有指定的数据类型返回true，否则返回false。 | + +- 示例 + + ``` + var pasteData = pasteboard.createPlainTextData("hello"); + var hasType = pasteData.hasMimeType(pasteboard.MIMETYPE_TEXT_PLAIN); + ``` + + +### removeRecordAt7+ + +removeRecordAt(index: number): boolean + +移除指定下标的条目。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | index | number | 是 | 指定的下标。 | + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | boolean | 成功移除返回true，失败返回false。 | + +- 示例 + + ``` + var pasteData = pasteboard.createPlainTextData("hello"); + var isRemove = pasteData.removeRecordAt(0); + ``` + + +### replaceRecordAt7+ + +replaceRecordAt(index: number, record: PasteDataRecord): boolean + +替换指定下标的条目。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | index | number | 是 | 指定的下标。 | + | record | [PasteDataRecord](#pastedatarecord7) | 是 | 替换后的条目。 | + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | boolean | 成功替换返回true，失败返回false。 | + +- 示例 + + ``` + var pasteData = pasteboard.createPlainTextData("hello"); + var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt"); + var isReplace = pasteData.replaceRecordAt(0, record); + ``` + + +## pasteboard.getSystemPasteboard + +getSystemPasteboard(): SystemPasteboard + +获取系统剪切板。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | [SystemPasteboard](#systempasteboard) | 系统剪切板对象。 | + +- 示例 + + ``` + var systemPasteboard = pasteboard.getSystemPasteboard(); + ``` + + +## SystemPasteboard + + 在调用SystemPasteboard的接口前，需要先通过[getSystemPasteboard](#pasteboardgetsystempasteboard)获取系统剪切板。 + +``` +var systemPasteboard = pasteboard.getSystemPasteboard(); +``` + + +### setPasteData + +setPasteData(pasteData:PasteData, callback:AsyncCallback<void>): void + +将数据写入系统剪切板，并使用callback方式返回结果。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | pasteData | [PasteData](#pastedata) | 是 | PasteData对象。 | + | callback | AsyncCallback<void> | 是 | 回调函数，表示是否成功将数据写入系统剪切板。 | + +- 示例 + + ``` + var pasteData = pasteboard.createPlainTextData("content"); + var systemPasteboard = pasteboard.getSystemPasteboard(); + systemPasteboard.setPasteData(pasteData, (error, data) => { + if (error) { + console.error('Failed to setPasteData. Cause: ' + error.message); + return; + } + console.info('setPasteData successfully.'); + }); + ``` + + +### setPasteData + +setPasteData(pasteData:PasteData): Promise<void> + +将数据写入系统剪切板，并使用Promise异步方式返回结果。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 说明 | + | -------- | -------- | -------- | + | pasteData | [PasteData](#pastedata) | PasteData对象。 | + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | Promise<void> | 异步回调函数，表示是否成功将数据写入系统剪切板。 | + +- 示例 + + ``` + var pasteData = pasteboard.createPlainTextData("content"); + var systemPasteboard = pasteboard.getSystemPasteboard(); + systemPasteboard.setPasteData(pasteData).then((data) => { + console.info('setPasteData success.'); + }).catch((error) => { + console.error('Failed to setPasteData. Cause: ' + error.message); + }); + ``` + + +### getPasteData + +getPasteData( callback:AsyncCallback<PasteData>): void + +读取系统剪切板内容，并使用callback方式返回结果。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<[PasteData](#pastedata)> | 是 | 回调函数，返回系统剪切板数据。 | + +- 示例 + + ``` + var systemPasteboard = pasteboard.getSystemPasteboard(); + systemPasteboard.getPasteData((error, pasteData) => { + if (error) { + console.error('Failed to getPasteData. Cause: ' + error.message); + return; + } + var text = pasteData.getPrimaryText(); + }); + ``` + + +### getPasteData + +getPasteData(): Promise<PasteData> + +读取系统剪切板内容，并使用Promise异步方式返回结果。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | Promise<[PasteData](#pastedata)> | 异步回调函数，调返回系统剪切板数据。 | + +- 示例 + + ``` + var systemPasteboard = pasteboard.getSystemPasteboard(); + systemPasteboard.getPasteData().then((pasteData) => { + var text = pasteData.getPrimaryText(); + }).catch((error) => { + console.error('Failed to getPasteData. Cause: ' + error.message); + }) + ``` + + +### on('update')7+ + +on(type: 'update', callback: () =>void ): void + +订阅系统剪贴板内容变化事件，当系统剪贴板中内容变化时触发用户程序的回调。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 取值为'update'，表示系统剪贴板内容变化事件。 | + | callback | function | 是 | 剪贴板中内容变化时触发的用户程序的回调。 | + +- 示例 + + ``` + var systemPasteboard = pasteboard.getSystemPasteboard(); + var listener = ()=>{ + console.info('The system pasteboard has changed'); + }; + systemPasteboard.on('update', listener); + ``` + + +### off('update')7+ + +off(type: 'update', callback？: () =>void ): void + +取消订阅系统剪贴板内容变化事件。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 取值为'update'，表示系统剪贴板内容变化事件。 | + | callback | function | 否 | 剪贴板中内容变化时触发的用户程序的回调。 | + +- 示例 + + ``` + systemPasteboard.off('update', listener); + ``` + + +### hasPasteData7+ + +hasPasteData(callback: AsyncCallback<boolean>): void + +判断系统剪切板中是否有内容，并使用callback异步方式返回结果。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<boolean> | 是 | 返回为true表示系统剪切板中有内容，返回false表示系统剪切板中没有内容。 | + +- 示例 + + ``` + systemPasteboard.hasPasteData((err, data) => { + if (err) { + console.error('failed to hasPasteData because ' + JSON.stringify(err)); + return; + } + console.info('success hasPasteData : ' + JSON.stringify(data)); + }); + ``` + + +### hasPasteData7+ + +hasPasteData(): Promise<boolean> + +判断系统剪切板中是否有内容，并使用Promise异步方式返回结果。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | Promise<boolean> | 返回为true表示系统剪切板中有内容，返回false表示系统剪切板中没有内容。 | + +- 示例 + + ``` + systemPasteboard.hasPasteData().then((data) => { + console.info('success hasPasteData : ' + JSON.stringify(data)); + }).catch((error) => { + console.error('failed to hasPasteData because ' + JSON.stringify(error)); + }); + ``` + + +### clear7+ + +clear(callback: AsyncCallback<void>): void + +清空系统剪切板内容，并使用callback异步方式返回结果。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<void> | 是 | 回调函数，表示是否成功清空系统剪切板内容。 | + +- 示例 + + ``` + systemPasteboard.clear((err, data) => { + if (err) { + console.error('failed to clear because ' + JSON.stringify(err)); + return; + } + console.info('success clear'); + }); + ``` + + +### clear7+ + +clear(): Promise<void> + +清空系统剪切板内容，并使用Promise异步方式返回结果。 + +**系统能力**: SystemCapability.Miscservices.Pasteboard + +- 返回值 + | 类型 | 说明 | + | -------- | -------- | + | Promise<void> | 异步回调函数，表示是否成功清空系统剪切板内容。 | + +- 示例 + + ``` + systemPasteboard.clear().then((data) => { + console.info('success clear'); + }).catch((error) => { + console.error('failed to clear because ' + JSON.stringify(error)); + }); + ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-request.md b/zh-cn/application-dev/reference/apis/js-apis-request.md new file mode 100644 index 0000000000..b853b07257 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-request.md @@ -0,0 +1,1102 @@ +# 上传下载(新) + + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + +## 导入模块 + + +``` +import request from '@ohos.request'; +``` + + +## 限制与约束 + +- 默认支持https，如果要支持http，需要在config.json里增加network标签，属性标识 "cleartextTraffic": true。即： + + ``` + "deviceConfig": { + "default": { + "network": { + "cleartextTraffic": true + } + ... + } + } + ``` + + +## 常量 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。 + +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| -------- | -------- | -------- | -------- | -------- | +| NETWORK_MOBILE | number | 是 | 否 | 使用蜂窝网络时允许下载的位标志。 | +| NETWORK_WIFI | number | 是 | 否 | 使用WLAN时允许下载的位标志。 | +| ERROR_CANNOT_RESUME7+ | number | 是 | 否 | 某些临时错误导致的恢复下载失败。 | +| ERROR_DEVICE_NOT_FOUND7+ | number | 是 | 否 | 找不到SD卡等存储设备。 | +| ERROR_FILE_ALREADY_EXISTS7+ | number | 是 | 否 | 要下载的文件已存在，下载会话不能覆盖现有文件。 | +| ERROR_FILE_ERROR7+ | number | 是 | 否 | 文件操作失败。 | +| ERROR_HTTP_DATA_ERROR7+ | number | 是 | 否 | HTTP传输失败。 | +| ERROR_INSUFFICIENT_SPACE7+ | number | 是 | 否 | 存储空间不足。 | +| ERROR_TOO_MANY_REDIRECTS7+ | number | 是 | 否 | 网络重定向过多导致的错误。 | +| ERROR_UNHANDLED_HTTP_CODE7+ | number | 是 | 否 | 无法识别的HTTP代码。 | +| ERROR_UNKNOWN7+ | number | 是 | 否 | 未知错误。 | +| PAUSED_QUEUED_FOR_WIFI7+ | number | 是 | 否 | 下载被暂停并等待WLAN连接，因为文件大小超过了使用蜂窝网络的会话允许的最大值。 | +| PAUSED_UNKNOWN7+ | number | 是 | 否 | 未知原因导致暂停下载。 | +| PAUSED_WAITING_FOR_NETWORK7+ | number | 是 | 否 | 由于网络问题（例如网络断开）而暂停下载。 | +| PAUSED_WAITING_TO_RETRY7+ | number | 是 | 否 | 发生网络错误，将重试下载会话。 | +| SESSION_FAILED7+ | number | 是 | 否 | 下载会话已失败，将不会重试。 | +| SESSION_PAUSED7+ | number | 是 | 否 | 下载会话已暂停。 | +| SESSION_PENDING7+ | number | 是 | 否 | 正在调度下载会话。 | +| SESSION_RUNNING7+ | number | 是 | 否 | 下载会话正在进行中。 | +| SESSION_SUCCESSFUL7+ | number | 是 | 否 | 下载会话已完成。 | + + +## request.upload + +upload(config: UploadConfig): Promise<UploadTask> + +上传，异步方法，使用promise形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Upload + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | config | [UploadConfig](#uploadconfig) | 是 | 上传的配置信息。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<[UploadTask](#uploadtask)> | 返回上传任务。 | + +- 示例： + + ``` + request.upload({ url: 'https://patch' }).then((data) => { + uploadTask = data; + }).catch((err) => { + console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); + }) + ``` + + +## request.upload + +upload(config: UploadConfig, callback: AsyncCallback<UploadTask>): void + +上传，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Upload + +- 参数 + | 参数名 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | config | [UploadConfig](#uploadconfig) | 是 | 上传的配置信息。 | + | callback | AsyncCallback<[UploadTask](#uploadtask)> | 否 | 回调函数，异步返回UploadTask对象。 | + +- 示例： + + ``` + request.upload({ url: 'https://patch' }, (err, data) => { + if (err) { + console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); + return; + } + uploadTask = data; + }); + ``` + + +## UploadTask + +上传任务，使用下列方法前，需要先获取UploadTask对象。 + + +### on('progress') + +on(type: 'progress', callback:AsyncCallback <uploadedSize: number, totalSize: number> => void): void + +开启上传任务监听，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Upload + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 订阅的事件类型，取值为'progress'（上传的进度信息）。 | + | callback | function | 是 | 上传进度的回调函数。 | + + 回调函数的参数： + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | uploadedSize | number | 是 | 当前已上传文件大小，单位为KB。 | + | totalSize | number | 是 | 上传文件的总大小，单位为KB。 | + +- 示例： + + ``` + uploadTask.on('progress', callback); + callback(uploadedSize, totalSize) { + console.info("upload totalSize:" + totalSize + " uploadedSize:" + uploadedSize); + } + ``` + + +### on('headerReceive')7+ + +on(type: 'headerReceive', callback: AsyncCallback<object> => void): void + +开启上传任务监听，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Upload + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 订阅的事件类型，取值为'headerReceive'（接收响应头）。 | + | callback | AsyncCallback<object> | 是 | HTTP Response Header事件的回调函数。 | + + 回调函数的参数： + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | headers | object | 是 | HTTP Response Header。 | + +- 示例： + + ``` + uploadTask.on('headerReceive', callback); + callback(headers){ + console.info("upOnHeader headers:" + JSON.stringify(headers)); + } + ``` + + +### off('progress') + +off(type: 'progress', callback:AsyncCallback<uploadedSize: number, totalSize: number>=> void): void + +关闭上传任务监听，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Upload + +- 参数： + | 参数名 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 取消订阅的事件类型，取值为'progress'（上传的进度信息）。 | + | callback | function | 否 | 上传任务的回调函数。 | + + 回调函数的参数： + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | uploadedSize | number | 是 | 当前已上传文件的大小，单位为KB。 | + | totalSize | number | 是 | 上传文件的总大小，单位为KB。 | + +- 示例： + + ``` + uploadTask.off('progress', callback); + callback(uploadedSize, totalSize) { + console.info('uploadedSize: ' + uploadedSize, 'totalSize: ' + totalSize); + } + ``` + + +### off('headerReceive')7+ + +off(type: 'headerReceive', callback:AsyncCallback<object> => void): void + +关闭上传任务监听，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Upload + +- 参数： + | 参数名 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 取消订阅的事件类型，取值为'headerReceive'（接收响应头）。 | + | callback | AsyncCallback<object> | 否 | HTTP Response Header事件的回调函数。 | + + 回调函数的参数： + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | headers | object | 是 | HTTP Response Header。 | + +- 示例： + + ``` + uploadTask.off('headerReceive', callback); + callback(headers) { + console.info("upOnHeader headers:" + JSON.stringify(headers)); + } + ``` + + +### remove + +remove(): Promise<boolean> + +移除上传的任务，异步方法，使用promise形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Upload + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<boolean> | 移除任务是否成功。true：成功，false：不成功。 | + +- 示例 + + ``` + uploadTask.remove().then((result) => { + if (result) { + console.info('Upload task removed successfully. '); + } else { + console.error('Failed to remove the upload task. '); + } + }).catch((err) => { + console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err)); + }); + ``` + + +### remove + +remove(callback: AsyncCallback<boolean>): void + +移除上传的任务，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Upload + +- 参数 + | 参数名 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<boolean> | 是 | 移除任务的回调函数。 | + +- 示例 + + ``` + uploadTask.remove((err, result) => { + if (err) { + console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err)); + return; + } + if (result) { + console.info('Upload task removed successfully.'); + } else { + console.error('Failed to remove the upload task.'); + } + }); + ``` + + +## UploadConfig + +**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。 + + | 名称 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| url | string | 是 | 资源地址。 | +| header | object | 否 | 添加要包含在上载请求中的HTTP或HTTPS标志头。 | +| method | string | 否 | 请求方法：POST、PUT。缺省为POST。 | +| files | Array<[File](#file)> | 是 | 要上传的文件列表。请使用 multipart/form-data提交。 | +| data | Array<[RequestData](#requestdata)> | 否 | 请求的表单数据。 | + + +## File + +**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。 + + | 名称 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| filename | string | 否 | multipart提交时，请求头中的文件名。 | +| name | string | 否 | multipart提交时，表单项目的名称，缺省为file。 | +| url | string | 是 | 文件的本地存储路径。
支持“dataability”和“internal”两种协议类型，但“internal”仅支持临时目录，示例：
dataability:///com.domainname.dataability.persondata/person/10/file.txt
internal://cache/path/to/file.txt | +| type | string | 否 | 文件的内容类型，默认根据文件名或路径的后缀获取。 | + + +## RequestData + +**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。 + + | 名称 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| name | string | 是 | 表示表单元素的名称。 | +| value | string | 是 | 表示表单元素的值。 | + + +## request.download + +download(config: DownloadConfig): Promise<DownloadTask> + +下载，异步方法，使用promise形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<[DownloadTask](#downloadtask)> | 返回下载任务。 | + +- 示例 + + ``` + request.download({ url: 'https://xxxx/xxxx.hap' }).then((data) => { + downloadTask = data; + }).catch((err) => { + console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); + }) + ``` + + +## request.download + +download(config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void + +下载，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +- 参数 + | 参数名 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | + | callback | AsyncCallback<[DownloadTask](#downloadtask)> | 否 | 下载接口的回调函数。 | + +- 示例 + + ``` + request.download({ url: 'https://xxxx/xxxxx.hap', + filePath: 'xxx/xxxxx.hap'}, (err, data) => { + if (err) { + console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); + return; + } + downloadTask = data; + }); + ``` + + +## DownloadTask + +下载任务。 + + +### on('progress') + +on(type: 'progress', callback:AsyncCallback<receivedSize: number, totalSize: number> => void): void + +开启下载任务监听，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 订阅的事件类型，取值为'progress'（下载的进度信息）。 | + | callback | function | 是 | 下载的回调函数。 | + + 回调函数的参数： + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | receivedSize | number | 是 | 当前下载的进度，单位为KB。 | + | totalSize | number | 是 | 下载文件的总大小，单位为KB。 | + +- 示例： + + ``` + request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> { + if (err) { + console.error('Fail to request download. Cause:' + err); + return; + } + downloadTask = data; + downloadTask.on('progress', download_callback); + }); + download_callback(receivedSize, totalSize) { + console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize); + } + ``` + + +### off('progress') + +off(type: 'progress', callback: AsyncCallback<receivedSize: number, totalSize: number> => void): void + +关闭下载任务监听，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +- 参数： + | 参数名 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 取消订阅的事件类型，取值为'progress'（下载的进度信息）。 | + | callback | function | 否 | 下载任务的回调函数。 | + + 回调函数的参数： + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | receivedSize | number | 是 | 当前下载的进度。 | + | totalSize | number | 是 | 下载文件的总大小。 | + +- 示例： + + ``` + request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> { + if (err) { + console.error('Fail to request download. Cause:' + err); + return; + } + downloadTask = data; + downloadTask .off('progress', download_callback); + }); + download_callback(receivedSize, totalSize) { + console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize); + } + ``` + + +### on('complete')7+ + +on(type: 'complete', callback:AsyncCallback<> => void): void + +开启下载任务完成监听，异步方法，使用callback形式返回。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 订阅的事件类型，取值为'complete'（下载任务完成）。 | + | callback | function | 是 | 下载完成的回调函数。 | + +- 示例： + + ``` + request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> { + if (err) { + console.error('Fail to request download. Cause:' + err); + return; + } + downloadTask= data; + downloadTask.on('complete',callback); + }); + callback() { + console.info('Download task completed.'); + } + ``` + + +### off('complete')7+ + +off(type: 'complete', callback:AsyncCallback<> => void): void + +取消下载任务完成监听，异步方法，使用callback形式返回。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 取消订阅的事件类型，取值为'complete'（下载任务完成）。 | + | callback | function | 否 | 取消下载完成的回调函数。 | + +- 示例： + + ``` + request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> { + if (err) { + console.error('Fail to request download. Cause:' + JSON.stringify(err)); + return; + } + downloadTask = data; + downloadTask.off('complete',callback); + }); + callback() { + console.info('Download task completed.'); + } + ``` + + +### on('fail')7+ + +on(type: 'fail', callback:AsyncCallback<err: number> => void): void + +开启下载任务失败监听，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 订阅的事件类型，取值为'fail'（下载失败）。 | + | callback | function | 是 | 下载失败的回调函数。 | + + 回调函数的参数： + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | err | number | 是 | 下载失败的错误码，错误原因见[ERROR.*](#常量)。 | + +- 示例 + + ``` + request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> { + if (err) { + console.error('Fail to request download. Cause:' + err); + return; + } + downloadTask = data; + downloadTask.on('fail', callBack); + }); + callBack(err) { + console.info('Download task failed. Cause:' + err); + } + ``` + + +### off('fail')7+ + +off(type: 'fail', callback:AsyncCallback<err: number> => void): void + +取消下载任务失败监听，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 取消订阅的事件类型，取值为'fail'（下载失败）。 | + | callback | function | 否 | 取消下载失败的回调函数。 | + + 回调函数的参数 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | err | number | 是 | 下载失败的错误码。错误原因见[ERROR_*](#常量)。 | + +- 示例 + + ``` + request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> { + if (err) { + console.error('Fail to request download. Cause:' + err); + return; + } + downloadTask = data; + downloadTask.off('fail', callBack); + }); + callBack(err) { + console.info('Download task failed. Cause:' + err); + } + ``` + + +### on('pause')7+ + +on(type: 'pause', callback:AsyncCallback<> => void): void + +开启下载任务暂停监听，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 订阅的事件类型，取值为'pause'（下载暂停）。 | + | callback | function | 是 | 下载暂停的回调函数。 | + +- 示例： + + ``` + request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> { + if (err) { + console.error('Failed to pause the download task. Cause:' + err); + return; + } + downloadTask = data; + downloadTask.on('pause', callBack); + }); + callBack() { + console.info('Download task paused.'); + } + ``` + + +### off('pause')7+ + +off(type: 'pause', callback:AsyncCallback<> => void): void + +取消下载任务暂停监听，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 取消订阅的事件类型，取值为'pause'（下载暂停）。 | + | callback | function | 否 | 取消下载暂停的回调函数。 | + +- 示例： + + ``` + request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> { + if (err) { + console.error('Failed to pause the download task. Cause:' + err); + return; + } + downloadTask = data; + downloadTask.off('pause', callBack); + }); + callBack() { + console.info('Download task paused.'); + } + ``` + + +### on('remove')7+ + +on(type: 'remove', callback:AsyncCallback<> => void): void + +开启下载任务移除监听，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 订阅的事件类型，取值为'remove'（下载任务移除）。 | + | callback | function | 是 | 下载移除的回调函数。 | + +- 示例: + + ``` + request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> { + if (err) { + console.error('Failed to remove the download task. Cause:' + err); + return; + } + downloadTask = data; + downloadTask.on('remove', callBack); + }); + callBack() { + console.info('Download task removed.'); + } + ``` + + +### off('remove')7+ + +off(type: 'remove', callback:AsyncCallback<> => void): void + +取消下载任务移除监听，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 取消订阅的事件类型，取值为'remove'（下载任务移除）。 | + | callback | function | 否 | 取消下载移除的回调函数。 | + +- 示例： + + ``` + request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> { + if (err) { + console.error('Failed to remove the download task. Cause:' + JSON.stringify(err)); + } + downloadTask = data; + downloadTask.off('remove', callBack); + }); + callBack() { + console.info('Download task removed.'); + } + ``` + + +### remove + +remove(): Promise<boolean> + +移除下载的任务，异步方法，使用promise形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<boolean> | 移除任务是否成功。 | + +- 示例 + + ``` + downloadTask.remove().then((result) => { + if (result) { + console.info('Download task removed.'); + } else { + console.error('Failed to remove the download task.'); + } + }).catch ((err) => { + console.error('Failed to remove the download task.'); + }); + ``` + + +### remove + +remove(callback: AsyncCallback<boolean>): void + +移除下载的任务，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +- 参数 + | 参数名 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<boolean> | 是 | 移除任务是否成功。 | + +- 示例 + + ``` + downloadTask.remove((err, result)=>{ + if(err) { + console.error('Failed to remove the download task.'); + return; + } + if (result) { + console.info('Download task removed.'); + } else { + console.error('Failed to remove the download task.'); + } + }); + ``` + + +### query7+ + +query(): Promise<DownloadInfo> + +查询下载任务，异步方法，使用promise形式返回DownloadInfo里的信息。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +- 参数： + | 类型 | 说明 | + | -------- | -------- | + | Promise<[DownloadInfo](#downloadinfo)> | 查询下载任务信息。 | + +- 示例 + + ``` + downloadTask.query().then((downloadInfo) => { + console.info('Download task queried. Data:' + JSON.stringfy(downloadInfo)) + }) .catch((err) => { + console.error('Failed to query the download task. Cause:' + err) + }); + ``` + + +### query7+ + +query(callback: AsyncCallback<DownloadInfo>): void + +查询下载的任务，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +- 参数： + | 参数名 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<[DownloadInfo](#downloadinfo)> | 是 | 查询下载任务的回调函数。 | + +- 示例： + + ``` + downloadTask.query((err, downloadInfo)=>{ + if(err) { + console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); + } else { + console.info('download query success. data:'+ JSON.stringify(downloadInfo)); + } + }); + ``` + + +### queryMimeType7+ + +queryMimeType(): Promise<string> + +查询下载的任务的 MimeType，异步方法，使用promise形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<string> | 查询下载任务的MimeType。 | + +- 示例 + + ``` + downloadTask.queryMimeType().then((data) => { + console.info('Download task queried. Data:' + JSON.stringify(data)); + }).catch((err) => { + console.error('Failed to query the download MimeType. Cause:' + JSON.stringify(err)) + }); + ``` + + +### queryMimeType7+ + +queryMimeType(callback: AsyncCallback<string>): void; + +查询下载的任务的 MimeType，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +- 参数 + | 参数名 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<string> | 是 | 查询下载任务的MimeType的回调函数。 | + +- 示例 + + ``` + downloadTask.queryMimeType((err, data)=>{ + if(err) { + console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); + } else { + console.info('Download task queried. data:' + JSON.stringify(data)); + } + }); + ``` + + +### pause7+ + +pause(): Promise<boolean> + +暂停下载任务，异步方法，使用promise形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<boolean> | 暂停下载任务是否成功。 | + +- 示例 + + ``` + downloadTask.pause().then((result) => { + if (result) { + console.info('Download task paused. '); + } else { + console.error('Failed to pause the download task. Cause:' + JSON.stringify(result)); + } + }).catch((err) => { + console.error('Failed to pause the download task. Cause:' + JSON.stringify(err)); + }); + ``` + + +### pause7+ + +pause(callback: AsyncCallback<boolean>): void + +暂停下载任务，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +- 参数 + | 参数名 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<boolean> | 是 | 暂停下载任务的回调函数。 | + +- 示例 + + ``` + downloadTask.pause((err, result)=>{ + if(err) { + console.error('Failed to pause the download task. Cause:' + JSON.stringify(err)); + return; + } + if (result) { + console.info('Download task paused. '); + } else { + console.error('Failed to pause the download task. Cause:' + JSON.stringify(result)); + } + }); + ``` + + +### resume7+ + +resume(): Promise<boolean> + +重新启动暂停的下载任务，异步方法，使用promise形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +- 参数： + | 类型 | 说明 | + | -------- | -------- | + | Promise<boolean> | 重新启动暂停的下载任务是否成功。 | + +- 示例 + + ``` + downloadTask.resume().then((result) => { + if (result) { + console.info('Download task resumed.') + } else { + console.error('Failed to resume the download task. '); + } + console.info('Download task resumed.') + }).catch((err) => { + console.error('Failed to resume the download task. Cause:' + err); + }); + ``` + + +### resume7+ + +resume(callback: AsyncCallback<boolean>): void + +重新启动暂停的下载任务，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +- 参数 + | 参数名 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<boolean> | 是 | 重新启动暂停的下载任务的回调函数。 | + +- 示例 + + ``` + downloadTask.resume((err, result)=>{ + if (err) { + console.error('Failed to resume the download task. Cause:' + err); + return; + } + if (result) { + console.info('Download task resumed.'); + } else { + console.error('Failed to resume the download task.'); + } + }); + ``` + + +## DownloadConfig + +**系统能力**: SystemCapability.MiscServices.Download + +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| url | string | 是 | 资源地址。 | +| header | object | 否 | 添加要包含在下载请求中的HTTP或HTTPS标志头。 | +| enableMetered | boolean | 否 | 允许在按流量计费的连接下下载。 | +| enableRoaming | boolean | 否 | 允许在漫游网络中下载。 | +| description | string | 否 | 设置下载会话的描述。 | +| filePath7+ | string | 否 | 设置下载路径（默认在[ERROR:Invalid link:zh-cn_topic_0000001135742582.xml#xref8132147102215,link:zh-cn_topic_0000001127125012.xml#section1856519365229](zh-cn_topic_0000001127125012.xml#section1856519365229)路径下）。
- filePath:'workspace/test.txt'：默认路径下创建workspace路径，并将文件存储在workspace路径下。
- filePath:'test.txt'：将文件存储在默认路径下。
- filePath:'workspace/'：默认路径下创建workspace路径，并将文件存储在workspace路径下。 | +| networkType | number | 否 | 设置允许下载的网络类型。 | +| title | string | 否 | 设置下载会话标题。 | + + +## DownloadInfo + +**系统能力**: SystemCapability.MiscServices.Download + + | 名称 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| downloadId | number | 是 | 下载的文件ID。 | +| failedReason | number | 否 | 下载失败原因，可以是任何[ERROR_*](#常量)常量。 | +| fileName | string | 是 | 下载的文件名。 | +| filePath | string | 是 | 存储文件的URI。 | +| pausedReason | number | 否 | 会话暂停的原因，可以是任何[PAUSED_*](#常量)常量。 | +| status | number | 是 | 下载状态代码，可以是任何[SESSION_*](#常量)常量。 | +| targetURI | string | 是 | 下载文件的URI。 | +| downloadTitle | string | 是 | 下载的文件的标题。 | +| downloadTotalBytes | number | 是 | 下载的文件的总大小（int bytes）。 | +| description | string | 是 | 待下载文件的描述信息。 | +| downloadedBytes | number | 是 | 实时下载大小（int  bytes）。 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-screen-lock.md b/zh-cn/application-dev/reference/apis/js-apis-screen-lock.md new file mode 100644 index 0000000000..ccb5244b06 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-screen-lock.md @@ -0,0 +1,168 @@ +# 锁屏管理 + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + +## 导入模块 + + +``` +import screenlock from '@ohos.screenLock'; +``` + + +## screenlock.isScreenLocked + +isScreenLocked(callback: AsyncCallback<boolean>): void + +判断屏幕是否锁屏，使用callback作为异步方法。 + +**系统能力**: SystemCapability.MiscServices.ScreenLock + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<boolean> | 是 | 回调函数，返回true表示屏幕已锁屏，返回false表示屏幕未锁屏。 | + +- 示例： + + ``` + screenlock.isScreenLocked((err, data)=>{ + if (err) { + console.error('isScreenLocked callback error -> ${JSON.stringify(err)}'); + return; + } + console.info('isScreenLocked callback success data -> ${JSON.stringify(data)}'); + }); + ``` + + +## screenlock.isScreenLocked + +isScreenLocked(): Promise<boolean> + +判断屏幕是否锁屏，使用Promise作为异步方法。 + +**系统能力**: SystemCapability.MiscServices.ScreenLock + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<boolean> | 以Promise形式返回结果。 | + +- 示例： + + ``` + screenlock.isScreenLocked().then((data) => { + console.log('isScreenLocked success: data -> ${JSON.stringify(data)}'); + }).catch((err) => { + console.error('isScreenLocked fail, promise: err -> ${JSON.stringify(err)}'); + }); + ``` + + +## screenlock.isSecureMode + +isSecureMode(callback: AsyncCallback<boolean>): void + + +判断设备是否处于安全模式下，使用callback作为异步方法。 + + +**系统能力**: SystemCapability.MiscServices.ScreenLock + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示屏幕处于安全模式下，返回false表示屏幕当前不在安全模式下。 | + +- 示例： + + ``` + screenlock.isSecureMode((err, data)=>{ + if (err) { + console.error('isSecureMode callback error -> ${JSON.stringify(err)}'); + return; + } + console.info('isSecureMode callback success data -> ${JSON.stringify(err)}'); + }); + ``` + + +## screenlock.isSecureMode + +isSecureMode(): Promise<boolean> + +判断设备是否处于安全模式下，使用Promise作为异步方法。 + +**系统能力**: SystemCapability.MiscServices.ScreenLock + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<boolean> | 以Promise形式返回结果。 | + +- 示例： + + ``` + screenlock.isSecureMode().then((data) => { + console.log('isSecureMode success: data->${JSON.stringify(data)}'); + }).catch((err) => { + console.error('isSecureMode fail, promise: err->${JSON.stringify(err)}'); + }); + ``` + + +## screenlock.unlockScreen + +unlockScreen(callback: AsyncCallback<void>): void + + +解锁屏幕，使用callback作为异步方法。 + + +**系统能力**: SystemCapability.MiscServices.ScreenLock + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<void> | 是 | 回调函数，失败时返回错误信息。 | + +- 示例： + + ``` + screenlock.unlockScreen((err)=>{ + if (err) { + console.error('unlockScreen callback error -> ${JSON.stringify(err)}'); + return; + } + console.info('unlockScreen callback success'); + }); + ``` + + +## screenlock.unlockScreen + +unlockScreen(): Promise<void> + +解锁屏幕，使用Promise作为异步方法。 + +**系统能力**: SystemCapability.MiscServices.ScreenLock + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<void> | 以Promise形式返回结果。 | + +- 示例： + + ``` + screenlock.unlockScreen().then(() => { + console.log('unlockScreen success'); + }).catch((err) => { + console.error('unlockScreen fail, promise: err->${JSON.stringify(err)}'); + }); + ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-system-time.md b/zh-cn/application-dev/reference/apis/js-apis-system-time.md index 93fc83af0d..b2389c5b57 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-system-time.md +++ b/zh-cn/application-dev/reference/apis/js-apis-system-time.md @@ -6,6 +6,7 @@ ## 导入模块 + ``` import systemTime from '@ohos.systemTime'; ``` @@ -15,15 +16,20 @@ import systemTime from '@ohos.systemTime'; setTime(time : number, callback : AsyncCallback<void>) : void -设置系统时间，需要ohos.permission.SET_TIME权限。 +设置系统时间。 + +**需要权限：**ohos.permission.SET_TIME + +**系统能力**: SystemCapability.Miscservices.Time - 参数： - | 参数名 | 类型 | 必填 | 说明 | + | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | time | number | 是 | 目标时间戳（毫秒）。 | - | callback | AsyncCallback<void> | 是 | 回调函数，可以在回调函数中处理接口返回值。 | + | time | number | 是 | 目标时间戳（毫秒）。 | + | callback | AsyncCallback<void> | 是 | 回调函数，可以在回调函数中处理接口返回值。 | - 示例： + ``` // time对应的时间为2021-01-20 02:36:25 var time = 1611081385000; @@ -32,7 +38,7 @@ setTime(time : number, callback : AsyncCallback<void>) : void console.error(`failed to systemTime.setTime because ` + JSON.stringify(error)); return; } - console.log(`success to systemTime.setTime: ` + JSON.stringify(data)); + console.log(`systemTime.setTime success data : ` + JSON.stringify(data)); }); ``` @@ -41,51 +47,229 @@ setTime(time : number, callback : AsyncCallback<void>) : void setTime(time : number) : Promise<void> -设置系统时间，需要ohos.permission.SET_TIME权限。 +设置系统时间。 + +**需要权限：**ohos.permission.SET_TIME + +**系统能力**: SystemCapability.Miscservices.Time - 参数： - | 参数名 | 类型 | 必填 | 说明 | + | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | time | number | 是 | 目标时间戳（毫秒）。 | + | time | number | 是 | 目标时间戳（毫秒）。 | - 返回值： - | 类型 | 说明 | + | 类型 | 说明 | | -------- | -------- | - | Promise<void> | 返回的异步回调函数。 | + | Promise<void> | 返回的异步回调函数。 | - 示例： + ``` // time对应的时间为2021-01-20 02:36:25 var time = 1611081385000; systemTime.setTime(time).then((data) => { - console.log(`success to systemTime.setTime: ` + JSON.stringify(data)); + console.log(`systemTime.setTime success data : ` + JSON.stringify(data)); }).catch((error) => { console.error(`failed to systemTime.setTime because ` + JSON.stringify(error)); }); ``` +## systemTime.getCurrentTime8+ + +getCurrentTime(isNano?: boolean, callback: AsyncCallback<number>): void + +获取自 Unix 纪元以来经过的时间，使用callback形式返回结果。 + +**系统能力**: SystemCapability.Miscservices.Time + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | isNano | boolean | 否 | 如果是true，返回纳秒数；否则返回毫秒数。 | + | callback | AsyncCallback<number> | 是 | 回调函数，返回自 Unix 纪元以来经过的时间。 | + +- 示例： + + ``` + systemTime.getCurrentTime(true, (error, data) => { + if (error) { + console.error(`failed to systemTime.getCurrentTime because ` + JSON.stringify(error)); + return; + } + console.log(`systemTime.getCurrentTime success data : ` + JSON.stringify(data)); + }); + ``` + + +## systemTime.getCurrentTime8+ + +getCurrentTime(isNano?: boolean): Promise<number> + +获取自 Unix 纪元以来经过的时间，使用Promise形式返回结果。 + +**系统能力**: SystemCapability.Miscservices.Time + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | isNano | boolean | 否 | 如果是true，返回纳秒数；否则返回毫秒数。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<number> | 以Promise形式返回结果，返回自 Unix 纪元以来经过的时间。 | + +- 示例： + + ``` + systemTime.getCurrentTime().then((data) => { + console.log(`systemTime.getCurrentTime success data : ` + JSON.stringify(data)); + }).catch((error) => { + console.error(`failed to systemTime.getCurrentTime because ` + JSON.stringify(error)); + }); + ``` + + +## systemTime.getRealActiveTime8+ + +getRealActiveTime(isNano?: boolean, callback: AsyncCallback<number>): void + +获取自系统启动以来经过的时间，不包括深度睡眠时间，使用callback形式返回结果。 + +**系统能力**: SystemCapability.Miscservices.Time + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | isNano | boolean | 否 | 如果是true，返回纳秒数；否则返回毫秒数。 | + | callback | AsyncCallback<number> | 是 | 回调函数，返回自系统启动以来但不包括度睡眠时间经过的时间。 | + +- 示例： + + ``` + systemTime.getRealActiveTime(true, (error, data) => { + if (error) { + console.error(`failed to systemTime.getRealActiveTimebecause ` + JSON.stringify(error)); + return; + } + console.log(`systemTime.getRealActiveTime success data : ` + JSON.stringify(data)); + }); + ``` + + +## systemTime.getRealActiveTime8+ + +getRealActiveTime(isNano?: boolean): Promise<number> + +获取自系统启动以来经过的时间，不包括深度睡眠时间，使用Promise形式返回结果。 + +**系统能力**: SystemCapability.Miscservices.Time + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | isNano | boolean | 否 | 如果是true，返回纳秒数；否则返回毫秒数。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<number> | 以Promise形式返回结果，返回自系统启动以来但不包括度睡眠时间经过的时间。 | + +- 示例： + + ``` + systemTime.getCurrentTime().then((data) => { + console.log(`systemTime.getRealActiveTime success data : ` + JSON.stringify(data)); + }).catch((error) => { + console.error(`failed to systemTime.getRealActiveTime because ` + JSON.stringify(error)); + }); + ``` + + +## systemTime.getRealTime8+ + +getRealTime(callback: AsyncCallback<number>): void + +获取自系统启动以来经过的时间，包括深度睡眠时间，使用callback形式返回结果。 + +**系统能力**: SystemCapability.Miscservices.Time + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | isNano | boolean | 否 | 如果是true，返回纳秒数；否则返回毫秒数。 | + | callback | AsyncCallback<number> | 是 | 回调函数，返回自系统启动以来包括深度睡眠时间经过的毫秒数。 | + +- 示例： + + ``` + systemTime.getRealTime(true, (error, data) => { + if (error) { + console.error(`failed to systemTime.getRealTime because ` + JSON.stringify(error)); + return; + } + console.log(`systemTime.getRealTime success data: ` + JSON.stringify(data)); + }); + ``` + + +## systemTime.getRealTime8+ + +getRealTime(): Promise<number> + +获取自系统启动以来经过的时间，包括深度睡眠时间，使用Promise形式返回结果。 + +**系统能力**: SystemCapability.Miscservices.Time + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | isNano | boolean | 否 | 如果是true，返回纳秒数；否则返回毫秒数。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<number> | 以Promise形式返回结果，返回自系统启动以来包括深度睡眠时间经过的时间。 | + +- 示例： + + ``` + systemTime.getRealTime().then((data) => { + console.log(`systemTime.getRealTime success data: ` + JSON.stringify(data)); + }).catch((error) => { + console.error(`failed to systemTime.getRealTime because ` + JSON.stringify(error)); + }); + ``` + + ## systemTime.setDate setDate(date: Date, callback: AsyncCallback<void>): void -设置系统日期，需要ohos.permission.SET_TIME权限。 +设置系统日期，使用callback形式返回结果。 + +**需要权限：**ohos.permission.SET_TIME + +**系统能力**: SystemCapability.Miscservices.Time - 参数： - | 参数名 | 类型 | 必填 | 说明 | + | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | date | Date | 是 | 目标日期。 | - | callback | AsyncCallback<void> | 是 | 回调函数，可以在回调函数中处理接口返回值。 | + | date | Date | 是 | 目标日期。 | + | callback | AsyncCallback<void> | 是 | 回调函数，可以在回调函数中处理接口返回值。 | - 示例： + ``` var data = new Date("October 13, 2020 11:13:00"); systemTime.setDate(data,(error, data) => { if (error) { - console.error('SystemTimePlugin setDate failed because ' + JSON.stringify(error)); + console.error('failed to systemTime.setDate because ' + JSON.stringify(error)); return; } - console.info('SystemTimePlugin setDate success data : ' + JSON.stringify(data)); + console.info('systemTime.setDate success data : ' + JSON.stringify(data)); }); ``` @@ -94,25 +278,80 @@ setDate(date: Date, callback: AsyncCallback<void>): void setDate(date: Date): Promise<void> -设置系统日期，需要ohos.permission.SET_TIME权限。 +设置系统日期，使用Promise形式返回结果。 + +**需要权限：**ohos.permission.SET_TIME + +**系统能力**: SystemCapability.Miscservices.Time - 参数： - | 参数名 | 类型 | 必填 | 说明 | + | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | date | Date | 是 | 目标日期。 | + | date | Date | 是 | 目标日期。 | - 返回值： - | 类型 | 说明 | + | 类型 | 说明 | | -------- | -------- | - | Promise<void> | 返回的异步回调函数。 | + | Promise<void> | 返回的异步回调函数。 | - 示例： + ``` var data = new Date("October 13, 2020 11:13:00"); systemTime.setDate(data).then((value) => { - console.log(`SystemTimePlugin success to systemTime.setDate: ` + JSON.stringify(value)); + console.log(`systemTime.setDate success data : ` + JSON.stringify(value)); }).catch((error) => { - console.error(`SystemTimePlugin failed to systemTime.setDate because: ` + JSON.stringify(error)); + console.error(`failed to systemTime.setDate because: ` + JSON.stringify(error)); + }); + ``` + + +## systemTime.getDate8+ + +getDate(callback: AsyncCallback<Date>): void + +获取当前系统日期，使用callback形式返回结果。 + +**系统能力**: SystemCapability.Miscservices.Time + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<Date> | 是 | 回调函数，返回当前系统日期。 | + +- 示例： + + ``` + systemTime.getDate((error, data) => { + if (error) { + console.error(`failed to systemTime.getDate because ` + JSON.stringify(error)); + return; + } + console.log(`systemTime.getDate success data : ` + JSON.stringify(data)); + }); + ``` + + +## systemTime.getDate8+ + +getDate(): Promise<Date> + +获取当前系统日期，使用Promise形式返回结果。 + +**系统能力**: SystemCapability.Miscservices.Time + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<Date> | 以Promise形式返回结果，返回当前系统日期。 | + +- 示例： + + ``` + systemTime.getDate().then((data) => { + console.log(`systemTime.getDate success data : ` + JSON.stringify(data)); + }).catch((error) => { + console.error(`failed to systemTime.getDate because ` + JSON.stringify(error)); }); ``` @@ -121,22 +360,27 @@ setDate(date: Date): Promise<void> setTimezone(timezone: string, callback: AsyncCallback<void>): void -设置系统时区，需要ohos.permission.SET_TIME_ZONE权限。 +设置系统时区。 + +**需要权限：**ohos.permission.SET_TIME_ZONE + +**系统能力**: SystemCapability.Miscservices.Time - 参数： - | 参数名 | 类型 | 必填 | 说明 | + | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | timezone | string | 是 | 系统时区。 | - | callback | AsyncCallback<void> | 是 | 回调函数，可以在回调函数中处理接口返回值。 | + | timezone | string | 是 | 系统时区。 | + | callback | AsyncCallback<void> | 是 | 回调函数，可以在回调函数中处理接口返回值。 | - 示例： + ``` systemTime.setTimezone('Asia/Shanghai', (error, data) => { if (error) { - console.error('SystemTimePlugin setTimezone failed because ' + JSON.stringify(error)); + console.error('failed to systemTime.setTimezone because ' + JSON.stringify(error)); return; } - console.info('SystemTimePlugin setTimezone success data : ' + JSON.stringify(data)); + console.info('SystemTimePlugin systemTime.setTimezone success data : ' + JSON.stringify(data)); }); ``` @@ -145,23 +389,78 @@ setTimezone(timezone: string, callback: AsyncCallback<void>): void setTimezone(timezone: string): Promise<void> -设置系统时区，需要ohos.permission.SET_TIME_ZONE权限。 +设置系统时区。 + +**需要权限：**ohos.permission.SET_TIME_ZONE + +**系统能力**: SystemCapability.Miscservices.Time - 参数： - | 参数名 | 类型 | 必填 | 说明 | + | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | timezone | string | 是 | 系统时区。 | + | timezone | string | 是 | 系统时区。 | - 返回值： - | 类型 | 说明 | + | 类型 | 说明 | | -------- | -------- | - | Promise<void> | 返回的异步回调函数。 | + | Promise<void> | 返回的异步回调函数。 | - 示例： + ``` systemTime.setTimezone('Asia/Shanghai').then((data) => { - console.log(`SystemTimePlugin success to systemTime.setTimezone: ` + JSON.stringify(data)); + console.log(`systemTime.setTimezone success data : ` + JSON.stringify(data)); }).catch((error) => { - console.error(`SystemTimePlugin failed to systemTime.setTimezone because: ` + JSON.stringify(error)); + console.error(`failed to systemTime.setTimezone because: ` + JSON.stringify(error)); + }); + ``` + + +## systemTime.getTimeZone8+ + +getTimeZone(callback: AsyncCallback<string>): void + +获取系统时区，使用callback形式返回结果。 + +**系统能力**: SystemCapability.Miscservices.Time + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<string> | 是 | 回调函数，返回系统时区。 | + +- 示例： + + ``` + systemTime.getTimeZone((error, data) => { + if (error) { + console.error(`failed to systemTime.getTimeZone because ` + JSON.stringify(error)); + return; + } + console.log(`systemTime.getTimeZone success data : ` + JSON.stringify(data)); + }); + ``` + + +## systemTime.getTimeZone8+ + +getTimeZone(): Promise<string> + +获取系统时区，使用Promise形式返回结果。 + +**系统能力**: SystemCapability.Miscservices.Time + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<string> | 以Promise形式返回结果，返回系统时区。 | + +- 示例： + + ``` + systemTime.getDate().then((data) => { + console.log(`systemTime.getTimeZone success data : ` + JSON.stringify(data)); + }).catch((error) => { + console.error(`failed to systemTime.getTimeZone because ` + JSON.stringify(error)); }); ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-wallpaper.md b/zh-cn/application-dev/reference/apis/js-apis-wallpaper.md new file mode 100644 index 0000000000..754db5beae --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-wallpaper.md @@ -0,0 +1,569 @@ +# 壁纸 + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + +## 导入模块 + + +``` +import wallpaper from '@ohos.wallpaper'; +``` + + +## WallpaperType + +定义壁纸类型。 + +**系统能力**: 以下各项对应的系统能力均为SystemCapability.Miscservices.Wallpaper。 + + | 名称 | 说明 | +| -------- | -------- | +| WALLPAPER_LOCKSCREEN | 锁屏壁纸标识。 | +| WALLPAPER_SYSTEM | 主屏幕壁纸标识。 | + + +## wallpaper.getColors + +getColors(wallpaperType: WallpaperType, callback: AsyncCallback<Array<RgbaColor>>): void + +获取指定类型壁纸的主要颜色信息。 + +**系统能力**: SystemCapability.Miscservices.Wallpaper + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | wallpaperType | [WallpaperType](#wallpapertype) | 是 | 壁纸类型。 | + | callback | AsyncCallback<Array<[RgbaColor](#rgbacolor)>> | 是 | 回调函数，返回壁纸的主要颜色信息。 | + +- 示例： + + ``` + wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => { + if (error) { + console.error(`failed to getColors because: ` + JSON.stringify(error)); + return; + } + console.log(`success to getColors.`); + }); + ``` + + +## wallpaper.getColors + +getColors(wallpaperType: WallpaperType): Promise<Array<RgbaColor>> + +获取指定类型壁纸的主要颜色信息。 + +**系统能力**: SystemCapability.Miscservices.Wallpaper + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | wallpaperType | [WallpaperType](#wallpapertype) | 是 | 壁纸类型。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<Array<[RgbaColor](#rgbacolor)>> | 返回壁纸的主要颜色信息。 | + +- 示例： + + ``` + wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => { + console.log(`success to getColors.`); + }).catch((error) => { + console.error(`failed to getColors because: ` + JSON.stringify(error)); + }); + ``` + + +## wallpaper.getId + +getId(wallpaperType: WallpaperType, callback: AsyncCallback<number>): void + +获取指定类型壁纸的ID。 + +**系统能力**: SystemCapability.Miscservices.Wallpaper + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | wallpaperType | [WallpaperType](#wallpapertype) | 是 | 壁纸类型。 | + | callback | AsyncCallback<number> | 是 | 回调函数，返回壁纸的ID。如果配置了指定类型的壁纸就返回一个大于等于0的数，否则返回-1。取值范围是-1~2^31-1。 | + +- 示例： + + ``` + wallpaper.getId(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => { + if (error) { + console.error(`failed to getId because: ` + JSON.stringify(error)); + return; + } + console.log(`success to getId: ` + JSON.stringify(data)); + }); + ``` + + +## wallpaper.getId + +getId(wallpaperType: WallpaperType): Promise<number> + +获取指定类型壁纸的ID。 + +**系统能力**: SystemCapability.Miscservices.Wallpaper + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | wallpaperType | [WallpaperType](#wallpapertype) | 是 | 壁纸类型。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<number> | 壁纸的ID。如果配置了这种壁纸类型的壁纸就返回一个大于等于0的数，否则返回-1。取值范围是-1~2^31-1。 | + +- 示例： + + ``` + wallpaper.getId(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => { + console.log(`success to getId: ` + JSON.stringify(data)); + }).catch((error) => { + console.error(`failed to getId because: ` + JSON.stringify(error)); + }); + ``` + + +## wallpaper.getMinHeight + +getMinHeight(callback: AsyncCallback<number>): void + +获取壁纸的最小高度值。 + +**系统能力**: SystemCapability.Miscservices.Wallpaper + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<number> | 是 | 回调函数，返回壁纸的最小高度值，单位是像素。如果返回值等于0，说明没有设置壁纸，调用者应该使用默认显示的高度值代替。 | + +- 示例： + + ``` + wallpaper.getMinHeight((error, data) => { + if (error) { + console.error(`failed to getMinHeight because: ` + JSON.stringify(error)); + return; + } + console.log(`success to getMinHeight: ` + JSON.stringify(data)); + }); + ``` + + +## wallpaper.getMinHeight + +getMinHeight(): Promise<number> + +获取壁纸的最小高度值。 + +**系统能力**: SystemCapability.Miscservices.Wallpaper + + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<number> | 返回壁纸的最小高度值，单位是像素。如果返回值等于0，说明没有设置壁纸，调用者应该使用默认显示的高度值代替。 | + +- 示例： + + ``` + wallpaper.getMinHeight().then((data) => { + console.log(`success to getMinHeight: ` + JSON.stringify(data)); + }).catch((error) => { + console.error(`failed to getMinHeight because: ` + JSON.stringify(error)); + }); + ``` + + +## wallpaper.getMinWidth + +getMinWidth(callback: AsyncCallback<number>): void + +获取壁纸的最小宽度值。 + +**系统能力**: SystemCapability.Miscservices.Wallpaper + + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<number> | 是 | 回调函数，壁纸的最小宽度值，单位是像素。如果返回值等于0，说明没有设置壁纸，调用者应该使用默认显示的宽度值代替。 | + +- 示例： + + ``` + wallpaper.getMinWidth((error, data) => { + if (error) { + console.error(`failed to getMinWidth because: ` + JSON.stringify(error)); + return; + } + console.log(`success to getMinWidth: ` + JSON.stringify(data)); + }); + ``` + + +## wallpaper.getMinWidth + +getMinWidth(): Promise<number> + +获取壁纸的最小宽度值。 + +**系统能力**: SystemCapability.Miscservices.Wallpaper + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<number> | 壁纸的最小宽度值，单位是像素。如果返回值等于0，说明没有设置壁纸，调用者应该使用默认显示的宽度值代替。 | + +- 示例： + + ``` + wallpaper.getMinWidth().then((data) => { + console.log(`success to getMinWidth: ` + JSON.stringify(data)); + }).catch((error) => { + console.error(`failed to getMinWidth because: ` + JSON.stringify(error)); + }); + ``` + + +## wallpaper.isChangePermitted + +isChangePermitted(callback: AsyncCallback<boolean>): void + +是否允许应用改变当前用户的壁纸。 + +**系统能力**: SystemCapability.Miscservices.Wallpaper + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<boolean> | 是 | 回调函数，返回是否允许应用改变当前用户的壁纸。如果允许返回true，否则返回false。 | + +- 示例： + + ``` + wallpaper.isChangePermitted((error, data) => { + if (error) { + console.error(`failed to isChangePermitted because: ` + JSON.stringify(error)); + return; + } + console.log(`success to isChangePermitted: ` + JSON.stringify(data)); + }); + ``` + + +## wallpaper.isChangePermitted + +isChangePermitted(): Promise<boolean> + +是否允许应用改变当前用户的壁纸。 + +**系统能力**: SystemCapability.Miscservices.Wallpaper + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<boolean> | 返回是否允许应用改变当前用户的壁纸。如果允许返回true，否则返回false。 | + +- 示例： + + ``` + wallpaper.isChangePermitted().then((data) => { + console.log(`success to isChangePermitted: ` + JSON.stringify(data)); + }).catch((error) => { + console.error(`failed to isChangePermitted because: ` + JSON.stringify(error)); + }); + ``` + + +## wallpaper.isOperationAllowed + +isOperationAllowed(callback: AsyncCallback<boolean>): void + +是否允许用户设置壁纸。 + +**系统能力**: SystemCapability.Miscservices.Wallpaper + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<boolean> | 是 | 回调函数，返回是否允许用户设置壁纸。如果允许返回true，否则返回false。 | + +- 示例： + + ``` + wallpaper.isOperationAllowed((error, data) => { + if (error) { + console.error(`failed to isOperationAllowed because: ` + JSON.stringify(error)); + return; + } + console.log(`success to isOperationAllowed: ` + JSON.stringify(data)); + }); + ``` + + +## wallpaper.isOperationAllowed + +isOperationAllowed(): Promise<boolean> + +是否允许用户设置壁纸。 + +**系统能力**: SystemCapability.Miscservices.Wallpaper + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<boolean> | 异步回调函数，返回是否允许用户设置壁纸。如果允许返回true，否则返回false。 | + +- 示例： + + ``` + wallpaper.isOperationAllowed().then((data) => { + console.log(`success to isOperationAllowed: ` + JSON.stringify(data)); + }).catch((error) => { + console.error(`failed to isOperationAllowed because: ` + JSON.stringify(error)); + }); + ``` + + +## wallpaper.reset + +reset(wallpaperType: WallpaperType, callback: AsyncCallback<void>): void + +移除指定类型的壁纸，恢复为默认显示的壁纸。 + +**需要权限**：ohos.permission.SET_WALLPAPER + +**系统能力**: SystemCapability.Miscservices.Wallpaper + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | wallpaperType | [WallpaperType](#wallpapertype) | 是 | 壁纸类型。 | + | callback | AsyncCallback<void> | 是 | 回调函数，调用成功则返回是否移除成功的结果，调用失败则返回error信息。 | + +- 示例： + + ``` + wallpaper.reset((error, data) => { + if (error) { + console.error(`failed to reset because: ` + JSON.stringify(error)); + return; + } + console.log(`success to reset.`); + }); + ``` + + +## wallpaper.reset + +reset(wallpaperType: WallpaperType): Promise<void> + +移除指定类型的壁纸，恢复为默认显示的壁纸。 + +**需要权限：**ohos.permission.SET_WALLPAPER + +**系统能力**: SystemCapability.Miscservices.Wallpaper + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | wallpaperType | [WallpaperType](#wallpapertype) | 是 | 壁纸类型。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<void> | 调用成功则返回是否移除成功的结果，调用失败则返回error信息。 | + +- 示例： + + ``` + wallpaper.reset(wallpaper.WALLPAPER_SYSTEM).then((data) => { + console.log(`success to reset.`); + }).catch((error) => { + console.error(`failed to reset because: ` + JSON.stringify(error)); + }); + ``` + + +## wallpaper.setWallpaper + +setWallpaper(uriOrPixelMap: string | image.PixelMap, wallpaperType: WallpaperType, callback: AsyncCallback<void>): void + +将指定资源设置为指定类型的壁纸。 + +**需要权限:** ohos.permission.SET_WALLPAPER + +**系统能力**: SystemCapability.Miscservices.Wallpaper + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | uriOrPixelMap | string \| [ERROR:Invalid link:zh-cn_topic_0000001154665636.xml#xref134981523104113,link:zh-cn_topic_0000001122977382.xml#section160331714124](zh-cn_topic_0000001122977382.xml#section160331714124) | 是 | JPEG或PNG文件的Uri路径，或者PNG格式文件的位图。 | + | wallpaperType | [WallpaperType](#wallpapertype) | 是 | 壁纸类型。 | + | callback | AsyncCallback<void> | 是 | 回调函数，调用成功则返回是返回设置的结果，调用失败则返回error信息。 | + +- 示例： + + ``` + // uriOrPixelMap类型为string + let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg"; + wallpaper.setWallpaper(wallpaperPath, wallpaper.WALLPAPER_SYSTEM, (error, data) => { + if (error) { + console.error(`failed to setWallpaper because: ` + JSON.stringify(error)); + return; + } + console.log(`success to setWallpaper.`); + }); + + // uriOrPixelMap类型为image.PixelMap + import image from '@ohos.multimedia.image'; + let imageSource = image.createImageSource("file://" + wallpaperPath); + let opts = { + "desiredSize": { + "height": 3648, + "width": 2736 + } + }; + imageSource.createPixelMap(opts).then((pixelMap) => { + wallpaper.setWallpaper(pixelMap, wallpaper.WALLPAPER_SYSTEM, (error, data) => { + if (error) { + console.error(`failed to setWallpaper because: ` + JSON.stringify(error)); + return; + } + console.log(`success to setWallpaper.`); + }); + }).catch((error) => { + console.error(`failed to createPixelMap because: ` + JSON.stringify(error)); + }); + ``` + + +## wallpaper.setWallpaper + +setWallpaper(uriOrPixelMap: string | image.PixelMap, wallpaperType: WallpaperType): Promise<void> + +将指定资源设置为指定类型的壁纸。 + +**需要权限**：ohos.permission.SET_WALLPAPER + +**系统能力**: SystemCapability.Miscservices.Wallpaper + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | uriOrPixelMap | string \| [ERROR:Invalid link:zh-cn_topic_0000001154665636.xml#xref2071734616,link:zh-cn_topic_0000001122977382.xml#section160331714124](zh-cn_topic_0000001122977382.xml#section160331714124) | 是 | JPEG或PNG文件的Uri路径，或者PNG格式文件的位图。 | + | wallpaperType | [WallpaperType](#wallpapertype) | 是 | 壁纸类型。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<void> | 调用成功则返回是返回设置的结果，调用失败则返回error信息。 | + +- 示例： + + ``` + // uriOrPixelMap类型为string + let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg"; + wallpaper.setWallpaper(wallpaperPath, wallpaper.WALLPAPER_SYSTEM).then((data) => { + console.log(`success to setWallpaper.`); + }).catch((error) => { + console.error(`failed to setWallpaper because: ` + JSON.stringify(error)); + }); + + // uriOrPixelMap类型为image.PixelMap + import image from '@ohos.multimedia.image'; + let imageSource = image.createImageSource("file://" + wallpaperPath); + let opts = { + "desiredSize": { + "height": 3648, + "width": 2736 + } + }; + imageSource.createPixelMap(opts).then((pixelMap) => { + wallpaper.setWallpaper(pixelMap, wallpaper.WALLPAPER_SYSTEM).then((data) => { + console.log(`success to setWallpaper.`); + }).catch((error) => { + console.error(`failed to setWallpaper because: ` + JSON.stringify(error)); + }); + }).catch((error) => { + console.error(`failed to createPixelMap because: ` + JSON.stringify(error)); + }); + ``` + + +## wallpaper.on('colorChange') + +on(type: 'colorChange', callback: (colors: Array<RgbaColor>, wallpaperType: WallpaperType) => void): void + +订阅壁纸颜色变化结果上报事件。 + +**系统能力**: SystemCapability.Miscservices.Wallpaper + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 取值为'colorChange'，表示壁纸颜色变化结果上报事件。 | + | callback | function | 是 | 壁纸颜色变化触发该回调方法，返回壁纸类型和壁纸的主要颜色信息。
- colors
  壁纸的主要颜色信息，其类型见[RgbaColor](#rgbacolor)。
- wallpaperType
  壁纸类型。 | + +- 示例: + + ``` + let listener = (colors, wallpaperType) => { + console.log(`wallpaper color changed.`); + }; + wallpaper.on('colorChange', listener); + ``` + + +## wallpaper.off('colorChange') + +off(type: 'colorChange', callback?: (colors: Array<RgbaColor>, wallpaperType: WallpaperType) => void): void + +取消订阅壁纸颜色变化结果上报事件。 + +**系统能力**: SystemCapability.Miscservices.Wallpaper + +- 参数： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 取值为'colorChange'，表示取消订阅壁纸颜色变化结果上报事件。 | + | callback | function | 否 |   表示取消壁纸颜色变化结果上报，不填写该参数则取消订阅该type对应的所有回调。
- colors
  壁纸的主要颜色信息，其类型见[RgbaColor](#rgbacolor)。
- wallpaperType
  壁纸类型。 | + +- 示例: + + ``` + let listener = (colors, wallpaperType) => { + console.log(`wallpaper color changed.`); + }; + wallpaper.on('colorChange', listener); + // 取消订阅listener + wallpaper.off('colorChange', listener); + // 取消所有'colorChange'类型的订阅 + wallpaper.off('colorChange'); + ``` + + +## RgbaColor + +**系统能力**: 以下各项对应的系统能力均为SystemCapability.Miscservices.Wallpaper。 + + | 名称 | 参数类型 | 可读 | 可写 | 说明 | +| -------- | -------- | -------- | -------- | -------- | +| red | number | 是 | 是 | 表示红色值，范围为 0 到 255。 | +| green | number | 是 | 是 | 表示绿色值，范围为 0 到 255。 | +| blue | number | 是 | 是 | 表示蓝色值，范围为 0 到 255。 | +| alpha | number | 是 | 是 | 表示 alpha 值，范围为 0 到 255。 | -- GitLab