From 32ef782fd3d13e54bf9c8a07ca018e97d4df3365 Mon Sep 17 00:00:00 2001 From: luoying_ace_admin Date: Wed, 16 Nov 2022 16:12:18 +0800 Subject: [PATCH] revise doc Signed-off-by: luoying_ace_admin --- .../reference/arkui-ts/Readme-CN.md | 8 +- .../ts-basic-components-navdestination.md | 27 ++ .../ts-basic-components-navigation.md | 59 +++- .../arkui-ts/ts-basic-components-navrouter.md | 22 ++ .../arkui-ts/ts-components-summary.md | 290 ++++++++++++++++++ 5 files changed, 394 insertions(+), 12 deletions(-) create mode 100644 zh-cn/application-dev/reference/arkui-ts/ts-basic-components-navdestination.md create mode 100644 zh-cn/application-dev/reference/arkui-ts/ts-basic-components-navrouter.md create mode 100644 zh-cn/application-dev/reference/arkui-ts/ts-components-summary.md diff --git a/zh-cn/application-dev/reference/arkui-ts/Readme-CN.md b/zh-cn/application-dev/reference/arkui-ts/Readme-CN.md index a18461d405..3fa8f6e43b 100644 --- a/zh-cn/application-dev/reference/arkui-ts/Readme-CN.md +++ b/zh-cn/application-dev/reference/arkui-ts/Readme-CN.md @@ -1,5 +1,6 @@ # 基于ArkTS的声明式开发范式 +- [组件导读](ts-components-summary.md) - 组件通用信息 - 通用事件 - [点击事件](ts-universal-events-click.md) @@ -65,6 +66,8 @@ - [LoadingProgress](ts-basic-components-loadingprogress.md) - [Marquee](ts-basic-components-marquee.md) - [Navigation](ts-basic-components-navigation.md) + - [NavRouter](ts-basic-components-navrouter.md) + - [NavDestination](ts-basic-components-navdestination.md) - [PatternLock](ts-basic-components-patternlock.md) - [PluginComponent](ts-basic-components-plugincomponent.md) - [Progress](ts-basic-components-progress.md) @@ -140,8 +143,6 @@ - [OffscreenCanvasRenderingContext2D对象](ts-offscreencanvasrenderingcontext2d.md) - [Path2D对象](ts-components-canvas-path2d.md) - [Lottie](ts-components-canvas-lottie.md) - - - 动画 - [属性动画](ts-animatorproperty.md) - [显式动画](ts-explicit-animation.md) @@ -164,5 +165,4 @@ - [枚举说明](ts-appendix-enums.md) - [类型说明](ts-types.md) - 已停止维护的组件 - - - [GridContainer(栅格)](ts-container-gridcontainer.md) + - [GridContainer(栅格)](ts-container-gridcontainer.md) \ No newline at end of file diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-navdestination.md b/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-navdestination.md new file mode 100644 index 0000000000..49669a8f1b --- /dev/null +++ b/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-navdestination.md @@ -0,0 +1,27 @@ +# NavDestination + +作为NavRouter组件的子组件，用于显示导航内容区。 + +> **说明：** +> +> 该组件从API Version 9开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 + + +## 子组件 + +可以包含子组件。 + + +## 接口 + +NavDestination() + + +## 属性 + +仅支持[backgroundColor](ts-universal-attributes-background.md)通用属性。 + +| 名称 | 参数类型 | 描述 | +| -------------- | ---------------------------------------- | ---------------------------------------- | +| title | string \| [CustomBuilder](ts-types.md#custombuilder8) \| [NavigationCommonTitle](ts-basic-components-navigation.md#navigationcommontitle类型说明) \| [NavigationCustomTitle](ts-basic-components-navigation.md##navigationcustomtitle类型说明) | 页面标题。 | +| hideTitleBar | boolean | 是否显示标题栏。
默认值：false
true: 隐藏标题栏。
false: 显示标题栏。 | \ No newline at end of file diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-navigation.md b/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-navigation.md index 9c21ba142b..69a4680cbb 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-navigation.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-navigation.md @@ -1,6 +1,6 @@ # Navigation -Navigation组件一般作为Page页面的根容器，通过属性设置来展示页面的标题、工具栏、菜单。 +Navigation组件一般作为Page页面的根容器，通过属性设置来展示页面的标题栏、工具栏、导航栏等。 > **说明：** > @@ -9,14 +9,13 @@ Navigation组件一般作为Page页面的根容器，通过属性设置来展示 ## 子组件 -可以包含子组件。 +可以包含子组件。从API Version 9开始，推荐与[NavRouter](ts-basic-components-navrouter.md)组件搭配使用。 ## 接口 Navigation() -创建可以根据属性设置，自动展示导航栏、标题、工具栏的组件。 ## 属性 @@ -24,14 +23,20 @@ Navigation() | 名称 | 参数类型 | 描述 | | -------------- | ---------------------------------------- | ---------------------------------------- | -| title | string \| [CustomBuilder](ts-types.md#custombuilder8)8+ | 页面标题。 | -| subTitle | string | 页面副标题。 | +| title | string \| [CustomBuilder](ts-types.md#custombuilder8)8+ \| [NavigationCommonTitle](#navigationcommontitle类型说明)9+ \| [NavigationCustomTitle](#navigationcustomtitle类型说明)9+ | 页面标题。 | +| subTitledeprecated | string | 页面副标题。从API Version 9开始废弃，建议使用title代替。 | | menus | Array<[NavigationMenuItem](#navigationmenuitem类型说明)> \| [CustomBuilder](ts-types.md#custombuilder8)8+ | 页面右上角菜单。 | | titleMode | [NavigationTitleMode](#navigationtitlemode枚举说明) | 页面标题栏显示模式。
默认值：NavigationTitleMode.Free | | toolBar | [object](#object类型说明) \| [CustomBuilder](ts-types.md#custombuilder8)8+ | 设置工具栏内容。
items: 工具栏所有项。 | -| hideToolBar | boolean | 隐藏工具栏：
默认值：false
true: 隐藏工具栏。
false: 显示工具栏。 | +| hideToolBar | boolean | 隐藏工具栏。
默认值：false
true: 隐藏工具栏。
false: 显示工具栏。 | | hideTitleBar | boolean | 隐藏标题栏。
默认值：false
true: 隐藏标题栏。
false: 显示标题栏。 | | hideBackButton | boolean | 隐藏返回键。
默认值：false
true: 隐藏返回键。
false: 显示返回键。 | +| navBarWidth9+ | [Length](ts-types.md#length) | 导航栏宽度。
默认值：200vp | +| navBarPosition9+ | [NavBarPosition](#navbarposition枚举说明) | 导航栏位置。
默认值：NavBarPosition.Start | +| mode9+ | [NavigationMode](#navigationmode枚举说明) | 导航栏的显示模式。
默认值：NavigationMode.Auto | +| backButtonIcon9+ | string \| [PixelMap](../apis/js-apis-image.md#pixelmap7) \| [Resource](ts-types.md#resource) | 设置导航栏返回图标。 | +| hideNavBar9+ | boolean | 是否显示导航栏（仅在mode为NavigationMode.Split时生效）。 | + ## NavigationMenuItem类型说明 @@ -54,8 +59,45 @@ Navigation() | 名称 | 描述 | | ---- | ---------------------------------------- | | Free | 当内容为可滚动组件时，标题随着内容向上滚动而缩小（子标题的大小不变、淡出）。向下滚动内容到顶时则恢复原样。 | -| Mini | 固定为小标题模式（图标+主副标题）。 | -| Full | 固定为大标题模式（主副标题）。 | +| Mini | 固定为小标题模式。 | +| Full | 固定为大标题模式。 | + +## NavigationCommonTitle类型说明 + +| 名称 | 类型 | 必填 | 描述 | +| ------ | --------- | ---- | -------- | +| main | string | 是 | 设置主标题。 | +| sub | string | 是 | 设置副标题。 | + +## NavigationCustomTitle类型说明 + +| 名称 | 类型 | 必填 | 描述 | +| ------ | ----------------------- | ---- | ------------------------------ | +| builder | [CustomBuilder](ts-types.md#custombuilder8) | 是 | 设置标题栏内容。 | +| height | [TitleHeight](#titleheight枚举说明) \| [Length](ts-types.md#length) | 是 | 设置标题栏高度。 | + +## NavBarPosition枚举说明 + +| 名称 | 描述 | +| ---- | ---------------------------------------- | +| Start | 双栏显示时，主列在主轴方向首部。 | +| End | 双栏显示时，主列在主轴方向尾部。 | + +## NavigationMode枚举说明 + +| 名称 | 描述 | +| ---- | ---------------------------------------- | +| Stack | 导航栏与内容区独立显示，相当于两个页面。 | +| Split | 导航栏与内容区分两栏显示。 | +| Auto | 窗口宽度>=520vp时，采用Split模式显示；窗口宽度<520vp时，采用Stack模式显示。 | + +## TitleHeight枚举说明 + +| 名称 | 描述 | +| ---- | ---------------------------------------- | +| MainOnly | 只有主标题时标题栏的推荐高度（56vp）。 | +| MainWithSub | 同时有主标题和副标题时标题栏的推荐高度（82vp）。 | + > **说明：** > 目前可滚动组件只支持List。 @@ -66,6 +108,7 @@ Navigation() | 名称 | 功能描述 | | ---------------------------------------- | ---------------------------------------- | | onTitleModeChange(callback: (titleMode: NavigationTitleMode) => void) | 当titleMode为NavigationTitleMode.Free时，随着可滚动组件的滑动标题栏模式发生变化时触发此回调。 | +| onNavBarStateChange(callback: (isVisible: boolean) => void) | 导航栏显示状态切换时触发该回调。返回值isVisible为true时表示显示，为false时表示隐藏。 | ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-navrouter.md b/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-navrouter.md new file mode 100644 index 0000000000..124c299714 --- /dev/null +++ b/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-navrouter.md @@ -0,0 +1,22 @@ +# NavRouter + +导航组件，默认提供点击响应处理，不需要开发者自定义点击事件逻辑。 + +> **说明：** +> +> 该组件从API Version 9开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 + +## 子组件 + +必须包含两个子组件，其中第二个子组件必须为[NavDestination](ts-basic-components-navdestination.md)。 + +## 接口 + +NavRouter() + + +## 事件 + +| 名称 | 功能描述 | +| ---------------------------------------- | ---------------------------------------- | +| onStateChange(callback: (isActivated: boolean) => void) | 组件激活状态切换时触发该回调。返回值isActivated为true时表示激活，为false时表示未激活。
**说明：**用户点击NavRouter，激活NavRouter，加载对应的NavDestination子组件时，回调onStateChange(true)；NavRouter对应的NavDestination子组件不再显示时，回调onStateChange(false)。 | diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-components-summary.md b/zh-cn/application-dev/reference/arkui-ts/ts-components-summary.md new file mode 100644 index 0000000000..4ddc18329b --- /dev/null +++ b/zh-cn/application-dev/reference/arkui-ts/ts-components-summary.md @@ -0,0 +1,290 @@ +# 组件导读 + + +## 行列与分栏 + +- [Column](ts-container-column.md) + + 沿垂直方向布局的容器组件。 +- [ColumnSplit](ts-container-columnsplit.md) + + 垂直方向分隔布局容器组件，将子组件纵向布局，并在每个子组件之间插入一根横向的分割线。 +- [Row](ts-container-row.md) + + 沿水平方向布局的容器组件。 +- [RowSplit](ts-container-rowsplit.md) + + 水平方向分隔布局容器组件，将子组件横向布局，并在每个子组件之间插入一根纵向的分割线。 +- [SideBarContainer](ts-container-sidebarcontainer.md) + + 提供侧边栏可以显示和隐藏的侧边栏容器组件，通过子组件定义侧边栏和内容区，第一个子组件表示侧边栏，第二个子组件表示内容区。 + + +## 堆叠Flex与栅格 + +- [Stack](ts-container-stack.md) + + 堆叠容器组件，子组件按照顺序依次入栈，后一个子组件覆盖前一个子组件。 +- [Flex](ts-container-flex.md) + + 以弹性方式布局子组件的容器组件。 +- [GridContainer](ts-container-gridcontainer.md) + + 纵向排布栅格布局容器组件，仅在栅格布局场景中使用。 +- [GridRow](ts-container-gridrow.md) + + 栅格容器组件，仅可以和栅格子组件(GridCol)在栅格布局场景中使用。 +- [GridCol](ts-container-gridcol.md) + + 栅格子组件，必须作为栅格容器组件(GridRow)的子组件使用。 +- [RelativeContainer](ts-container-relativecontainer.md) + + 相对布局组件，用于复杂场景中元素对齐的布局。 + + +## 列表与宫格 + +- [List](ts-container-list.md) + + 列表包含一系列相同宽度的列表项，适合连续、多行呈现同类数据，例如图片和文本。 +- [ListItem](ts-container-listitem.md) + + 用来展示具体列表项，必须配合List来使用。 +- [ListItemGroup](ts-container-listitemgroup.md) + + 用来展示分组列表项的组件，必须配合List组件来使用。 +- [Grid](ts-container-grid.md) + + 网格容器组件，由“行”和“列”分割的单元格所组成，通过指定“项目”所在的单元格做出各种各样的布局。 +- [GridItem](ts-container-griditem.md) + + 网格容器中单项内容容器。 + + +## 滚动与滑动 + +- [Scroll](ts-container-scroll.md) + + 可滚动的容器组件，当子组件的布局尺寸超过父组件的尺寸时，内容可以滚动。 +- [Swiper](ts-container-swiper.md) + + 滑块视图容器组件，提供子组件滑动轮播显示的能力。 +- [WaterFlow](ts-container-waterflow.md) + + 瀑布流容器组件，由“行”和“列”分割的单元格所组成，通过容器自身的排列规则，将不同大小的“项目”自上而下，如瀑布般紧密布局。 +- [FlowItem](ts-container-flowitem.md) + + 瀑布流组件WaterFlow的子组件，用来展示瀑布流具体item。 + + +## 导航 + +- [Navigator](ts-container-navigator.md) + + 路由容器组件，提供路由跳转能力。 +- [Navigation](ts-basic-components-navigation.md) + + 一般作为Page页面的根容器，通过属性设置来展示页面的标题栏、工具栏、导航栏等。 +- [NavRouter](ts-basic-components-navrouter.md) + + 导航组件，默认提供点击响应处理，不需要开发者自定义点击事件逻辑。 +- [NavDestination](ts-basic-components-navdestination.md) + + 作为NavRouter组件的子组件，用于显示导航内容区。 +- [Stepper](ts-basic-components-stepper.md) + + 步骤导航器组件，适用于引导用户按照步骤完成任务的导航场景。 +- [StepperItem](ts-basic-components-stepperitem.md) + + Stepper组件的子组件。 +- [Tabs](ts-container-tabs.md) + + 通过页签进行内容视图切换的容器组件，每个页签对应一个内容视图。 +- [TabContent](ts-container-tabcontent.md) + + 仅在Tabs组件中使用，对应一个切换页签的内容视图。 + + +## 按钮与选择 + +- [Button](ts-basic-components-button.md) + + 按钮组件，可快速创建不同样式的按钮。 +- [Toggle](ts-basic-components-toggle.md) + + 组件提供勾选框样式、状态按钮样式及开关样式。 +- [Checkbox](ts-basic-components-checkbox.md) + + 提供多选框组件，通常用于某选项的打开或关闭。 +- [CheckboxGroup](ts-basic-components-checkboxgroup.md) + + 多选框群组，用于控制多选框全选或者不全选状态。 +- [DatePicker](ts-basic-components-datepicker.md) + + 选择日期的滑动选择器组件。 +- [TextPicker](ts-basic-components-textpicker.md) + + 滑动选择文本内容的组件。 +- [TimePicker](ts-basic-components-timepicker.md) + + 滑动选择时间的组件。 +- [Radio](ts-basic-components-radio.md) + + 单选框，提供相应的用户交互选择项。 +- [Rating](ts-basic-components-rating.md) + + 提供在给定范围内选择评分的组件。 +- [Select](ts-basic-components-select.md) + + 提供下拉选择菜单，可以让用户在多个选项之间选择。 +- [Slider](ts-basic-components-slider.md) + + 滑动条组件，通常用于快速调节设置值，如音量调节、亮度调节等应用场景。 +- [Counter](ts-container-counter.md) + + 计数器组件，提供相应的增加或者减少的计数操作。 + + +## 文本与输入 + +- [Text](ts-basic-components-text.md) + + 显示一段文本的组件。 +- [Span](ts-basic-components-span.md) + + 作为Text组件的子组件，用于显示行内文本片段的组件。 +- [Search](ts-basic-components-search.md) + + 搜索框组件，适用于浏览器的搜索内容输入框等应用场景。 +- [TextArea](ts-basic-components-textarea.md) + + 多行文本输入框组件，当输入的文本内容超过组件宽度时会自动换行显示。 +- [TextInput](ts-basic-components-textinput.md) + + 单行文本输入框组件。 +- [PatternLock](ts-basic-components-patternlock.md) + + 图案密码锁组件，以九宫格图案的方式输入密码，用于密码验证场景。手指在PatternLock组件区域按下时开始进入输入状态，手指离开屏幕时结束输入状态完成密码输入。 +- [RichText](ts-basic-components-richtext.md) + + 富文本组件，解析并显示HTML格式文本。 + + +## 图片视频与媒体 + +- [Image](ts-basic-components-image.md) + + 图片组件，支持本地图片和网络图片的渲染展示。 +- [ImageAnimator](ts-basic-components-imageanimator.md) + + 提供逐帧播放图片能力的帧动画组件，可以配置需要播放的图片列表，每张图片可以配置时长。 +- [Video](ts-media-components-video.md) + + 用于播放视频文件并控制其播放状态的组件。 +- [PluginComponent](ts-basic-components-plugincomponent.md) + + 提供外部应用组件嵌入式显示功能，即外部应用提供的UI可在本应用内显示。 +- [XComponent](ts-basic-components-xcomponent.md) + + 用于EGL/OpenGLES和媒体数据写入。 + + +## 信息展示 + +- [DataPanel](ts-basic-components-datapanel.md) + + 数据面板组件，用于将多个数据占比情况使用占比图进行展示。 +- [Gauge](ts-basic-components-gauge.md) + + 数据量规图表组件，用于将数据展示为环形图表。 +- [LoadingProgress](ts-basic-components-loadingprogress.md) + + 用于显示加载动效的组件。 +- [Marquee](ts-basic-components-marquee.md) + + 跑马灯组件，用于滚动展示一段单行文本，仅当文本内容宽度超过跑马灯组件宽度时滚动。 +- [Progress](ts-basic-components-progress.md) + + 进度条组件，用于显示内容加载或操作处理等进度。 +- [QRCode](ts-basic-components-qrcode.md) + + 用于显示单个二维码的组件。 +- [TextClock](ts-basic-components-textclock.md) + + 通过文本将当前系统时间显示在设备上。支持不同时区的时间显示，最高精度到秒级。 +- [TextTimer](ts-basic-components-texttimer.md) + + 通过文本显示计时信息并控制其计时器状态的组件。 + + +## 空白与分隔 + +- [Blank](ts-basic-components-blank.md) + + 空白填充组件，在容器主轴方向上，空白填充组件具有自动填充容器空余部分的能力。仅当父组件为Row/Column时生效。 +- [Divider](ts-basic-components-divider.md) + + 分隔器组件，分隔不同内容块/内容元素。 + + +## 画布与图形绘制 + +- [Canvas](ts-components-canvas-canvas.md) + + 提供画布组件，用于自定义绘制图形。 +- [Circle](ts-drawing-components-circle.md) + + 用于绘制圆形的组件。 +- [Ellipse](ts-drawing-components-ellipse.md) + + 椭圆绘制组件。 +- [Line](ts-drawing-components-line.md) + + 直线绘制组件。 +- [Polyline](ts-drawing-components-polyline.md) + + 折线绘制组件。 +- [Polygon](ts-drawing-components-polygon.md) + + 多边形绘制组件。 +- [Path](ts-drawing-components-path.md) + + 路径绘制组件，根据绘制路径生成封闭的自定义形状。 +- [Rect](ts-drawing-components-rect.md) + + 矩形绘制组件。 +- [Shape](ts-drawing-components-shape.md) + + 作为绘制组件的父组件，实现类似SVG的效果，父组件中会描述所有绘制组件均支持的通用属性。 + + +## 网络 + +- [Web](ts-basic-components-web.md) + + 提供具有网页显示能力的Web组件。 + + +## 其他 + +- [ScrollBar](ts-basic-components-scrollbar.md) + + 滚动条组件，用于配合可滚动组件使用，如List、Grid、Scroll等。 +- [Badge](ts-container-badge.md) + + 可以附加在单个组件上用于信息标记的容器组件。 +- [AlphabetIndexer](ts-container-alphabet-indexer.md) + + 可以与容器组件联动用于按逻辑结构快速定位容器显示区域的索引条组件。 +- [Panel](ts-container-panel.md) + + 可滑动面板，提供一种轻量的内容展示窗口，方便在不同尺寸中切换。 +- [Refresh](ts-container-refresh.md) + + 可以进行页面下拉操作并显示刷新动效的容器组件。 +- [AbilityComponent](ts-container-ability-component.md) + + 独立显示Ability的容器组件。 +- [RemoteWindow](ts-basic-components-remotewindow.md) + + 远程控制窗口组件，可以通过此组件控制应用窗口，提供启动退出过程中控件动画和应用窗口联动动画的能力。 \ No newline at end of file -- GitLab