ts-container-sidebarcontainer.md 8.3 KB
Newer Older
Y
yaoyuchi 已提交
1 2
# SideBarContainer

Y
yaoyuchi 已提交
3
提供侧边栏可以显示和隐藏的侧边栏容器,通过子组件定义侧边栏和内容区,第一个子组件表示侧边栏,第二个子组件表示内容区。
Y
yaoyuchi 已提交
4

G
gmy 已提交
5 6 7
>  **说明:**
>
>  该组件从API Version 8开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
Y
yaoyuchi 已提交
8 9 10 11


## 子组件

Y
yaoyuchi 已提交
12
可以包含子组件。
Y
yaoyuchi 已提交
13

Y
yamila 已提交
14 15
>  **说明:**
>
Y
yamila 已提交
16
>  - 子组件类型:系统组件和自定义组件,不支持渲染控制类型([if/else](../../quick-start/arkts-rendering-control.md#条件渲染)、[ForEach](../../quick-start/arkts-rendering-control.md#循环渲染)和[LazyForEach](../../quick-start/arkts-rendering-control.md#数据懒加载))。
Y
yamila 已提交
17 18 19
>  - 子组件个数:必须且仅包含2个子组件。
>  - 子组件个数异常时:3个或以上子组件,显示第一个和第二个。1个子组件,显示侧边栏,内容区为空白。

Y
yaoyuchi 已提交
20 21 22 23 24

## 接口

SideBarContainer( type?: SideBarContainerType )

G
gmy 已提交
25
**参数:**
Y
yaoyuchi 已提交
26

G
gmy 已提交
27 28 29 30 31 32 33 34
| 参数名 | 参数类型 | 必填 | 参数描述 |
| -------- | -------- | -------- | -------- |
| type | SideBarContainerType | 否 | 设置侧边栏的显示类型。<br/>默认值:SideBarContainerType.Embed |

## SideBarContainerType枚举说明

| 名称 | 描述 |
| -------- | -------- |
T
third  
tianyu 已提交
35
| Embed | 侧边栏嵌入到组件内,和内容区并列显示。 |
G
gmy 已提交
36
| Overlay | 侧边栏浮在内容区上面。 |
Y
yaoyuchi 已提交
37 38 39

## 属性

Y
yamila 已提交
40 41
除支持[通用属性](ts-universal-attributes-size.md)外,还支持以下属性:

G
gmy 已提交
42 43 44
| 名称 | 参数类型 | 描述 |
| -------- | -------- | -------- |
| showSideBar | boolean | 设置是否显示侧边栏。<br/>默认值:true |
Y
yamila 已提交
45
| controlButton | [ButtonStyle](#buttonstyle对象说明)                            | 设置侧边栏控制按钮的属性。 |
G
gmy 已提交
46
| showControlButton | boolean | 设置是否显示控制按钮。<br/>默认值:true |
Y
yamila 已提交
47 48 49 50 51
| sideBarWidth | number&nbsp;\|&nbsp;[Length](ts-types.md#length)<sup>9+</sup> | 设置侧边栏的宽度。<br/>默认值:200<br/>单位:vp<br/>**说明:** <br/>设置为小于0的值时按默认值显示。<br/>受最小宽度和最大宽度限制,不在限制区域内取最近的点。<br/>sideBarWidth优先于侧边栏子组件width,sideBarWidth未设置时默认值优先级低于侧边栏子组件width。 |
| minSideBarWidth | number&nbsp;\|&nbsp;[Length](ts-types.md#length)<sup>9+</sup> | 设置侧边栏最小宽度。<br/>默认值:200,单位vp<br/>**说明:** <br/>设置为小于0的值时按默认值显示。<br/>值不能超过侧边栏容器本身宽度,超过使用侧边栏容器本身宽度。<br/>minSideBarWidth优先于侧边栏子组件minWidth,minSideBarWidth未设置时默认值优先级低于侧边栏子组件minWidth。 |
| maxSideBarWidth | number&nbsp;\|&nbsp;[Length](ts-types.md#length)<sup>9+</sup> | 设置侧边栏最大宽度。<br/>默认值:280,单位vp<br/>**说明:** <br/>设置为小于0的值时按默认值显示。<br/>值不能超过侧边栏容器本身宽度,超过使用侧边栏容器本身宽度。<br/>maxSideBarWidth优先于侧边栏子组件maxWidth,maxSideBarWidth未设置时默认值优先级低于侧边栏子组件maxWidth。 |
| autoHide<sup>9+</sup> | boolean | 设置当侧边栏拖拽到小于最小宽度后,是否自动隐藏。<br/>默认值:true<br>**说明:** <br>受minSideBarWidth属性方法影响,minSideBarWidth属性方法未设置值使用默认值。<br/>拖拽过程中判断是否要自动隐藏。小于最小宽度时需要阻尼效果触发隐藏(越界一段距离) |
| sideBarPosition<sup>9+</sup> | [SideBarPosition](#sidebarposition9枚举说明) | 设置侧边栏显示位置。<br/>默认值:SideBarPosition.Start |
C
chensi10 已提交
52
| divider<sup>10+</sup>        | [DividerStyle](#dividerstyle10对象说明) \| null | 设置分割线的样式。<br/>- 默认为DividerStyle:显示分割线。<br/>- null:不显示分割线。 |
G
gmy 已提交
53 54 55 56

## ButtonStyle对象说明

| 名称 | 参数类型 | 必填 | 描述 |
Y
yaoyuchi 已提交
57
| -------- | -------- | -------- | -------- |
Y
yamila 已提交
58 59 60 61 62
| left | number | 否 | 设置侧边栏控制按钮距离容器左界限的间距。<br/>默认值:16<br>单位:vp |
| top | number | 否 | 设置侧边栏控制按钮距离容器上界限的间距。<br/>默认值:48<br/>单位:vp |
| width | number | 否 | 设置侧边栏控制按钮的宽度。<br/>默认值:32<br/>单位:vp |
| height | number | 否 | 设置侧边栏控制按钮的高度。<br/>默认值:32<br/>单位:vp |
| icons | {<br/>shown:&nbsp;string \| PixelMap \| [Resource](ts-types.md) ,<br/>hidden:&nbsp;string \| PixelMap \| [Resource](ts-types.md) ,<br/>switching?:&nbsp;string \| PixelMap \| [Resource](ts-types.md) <br/>} | 否 | 设置侧边栏控制按钮的图标:<br/> </p> - shown: 设置侧边栏显示时控制按钮的图标。<br>**说明:** <br>资源获取错误时,使用默认图标。<br/>- hidden: 设置侧边栏隐藏时控制按钮的图标。<br>- switching:设置侧边栏显示和隐藏状态切换时控制按钮的图标。 |
Y
yaoyuchi 已提交
63

G
gmy 已提交
64
## SideBarPosition<sup>9+</sup>枚举说明
Y
yaoyuchi 已提交
65

G
gmy 已提交
66 67 68 69
| 名称 | 描述 |
| -------- | -------- |
| Start | 侧边栏位于容器左侧。 |
| End | 侧边栏位于容器右侧。 |
Y
yaoyuchi 已提交
70

C
chensi10 已提交
71 72 73 74
## DividerStyle<sup>10+</sup>对象说明

| 名称        | 参数类型      | 必填 | 描述                                     |
| ----------- | ------------- | ---- | ---------------------------------------- |
Y
yamila 已提交
75
| strokeWidth | [Length](ts-types.md#length)        | 是   | 分割线的线宽。<br/>默认值:1<br/>单位:vp |
C
chensi10 已提交
76 77 78
| color       | [ResourceColor](ts-types.md#resourcecolor) | 否   | 分割线的颜色。<br/>默认值:#000000,3%   |
| startMargin | [Length](ts-types.md#length)        | 否   | 分割线与侧边栏顶端的距离。<br/>默认值:0 |
| endMargin   | [Length](ts-types.md#length)        | 否   | 分割线与侧边栏底端的距离。<br/>默认值:0 |
Y
yamila 已提交
79 80 81 82 83 84 85 86 87 88 89
>  **说明:** 
>
>  针对侧边栏子组件设置[通用属性宽高](ts-universal-attributes-size.md)时,宽生效的前提是侧边栏容器不设置sideBarWidth,高度不生效。
>  针对侧边栏内容区设置[通用属性宽高](ts-universal-attributes-size.md)时,宽高都不生效,默认占满SideBarContainer的剩余空间。
>
>  当属性方法未设置时,依据组件大小进行自动显示:
>
>  - 小于520vp:默认不显示侧边栏。
>  - 大于等于520vp:默认显示侧边栏。
>  - 小于520vp:不显示侧边栏。
>  - 大于等于520vp:显示侧边栏。
C
chensi10 已提交
90

Y
yaoyuchi 已提交
91 92
## 事件

Y
yamila 已提交
93 94
除支持[通用事件](ts-universal-events-click.md)外,还支持以下事件:

G
gmy 已提交
95
| 名称 | 功能描述 |
Y
yaoyuchi 已提交
96
| -------- | -------- |
Y
yamila 已提交
97
| onChange(callback: (value: boolean) =&gt; void) | 当侧边栏的状态在显示和隐藏之间切换时触发回调。true表示显示,false表示隐藏。<br/>触发该事件的条件:<br>1、showSideBar属性值变换时;<br/>2、showSideBar属性自适应行为变化时;<br/>3、分割线拖拽触发autoHide时。 |
Y
yaoyuchi 已提交
98 99 100 101


## 示例

H
geshi  
HelloCrease 已提交
102 103
```ts
// xxx.ets
Y
yaoyuchi 已提交
104 105 106
@Entry
@Component
struct SideBarContainerExample {
X
xuzhidan 已提交
107 108
  normalIcon : Resource = $r("app.media.icon")
  selectedIcon: Resource = $r("app.media.icon")
Y
yaoyuchi 已提交
109 110 111 112
  @State arr: number[] = [1, 2, 3]
  @State current: number = 1

  build() {
Y
yaoyuchi 已提交
113
    SideBarContainer(SideBarContainerType.Embed)
Y
yaoyuchi 已提交
114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130
    {
      Column() {
        ForEach(this.arr, (item, index) => {
          Column({ space: 5 }) {
            Image(this.current === item ? this.selectedIcon : this.normalIcon).width(64).height(64)
            Text("Index0" + item)
              .fontSize(25)
              .fontColor(this.current === item ? '#0A59F7' : '#999')
              .fontFamily('source-sans-pro,cursive,sans-serif')
          }
          .onClick(() => {
            this.current = item
          })
        }, item => item)
      }.width('100%')
      .justifyContent(FlexAlign.SpaceEvenly)
      .backgroundColor('#19000000')
X
xuzhidan 已提交
131 132 133 134 135 136 137


      Column() {
        Text('SideBarContainer content text1').fontSize(25)
        Text('SideBarContainer content text2').fontSize(25)
      }
      .margin({ top: 50, left: 20, right: 30 })
Y
yaoyuchi 已提交
138
    }
X
xuzhidan 已提交
139 140 141
    .sideBarWidth(150)
    .minSideBarWidth(50)
    .maxSideBarWidth(300)
Y
yaoyuchi 已提交
142 143 144 145 146 147
    .onChange((value: boolean) => {
      console.info('status:' + value)
    })
  }
}
```
Y
yaoyuchi 已提交
148 149

![](figures/sidebarcontainer.png)