xtf-home-sheet

组件说明

xtf-home-sheet 是首页底部面板组件，类似地图应用的底部可拖拽面板。支持多档位停靠、拖拽切换和滚动锁定，适用于首页信息展示、地图底部面板和可折叠内容区等场景。

---

基础用法

1. 基础用法

通过 modelValue 控制当前档位（从 0 开始），通过 stops 设置停靠比例：

<template>
  <xtf-home-sheet v-model="sheetIndex" :stops="[0.22, 0.48, 0.88]">
    <view class="content">
      <xtf-text level="title" bold text="推荐服务" />
      <xtf-grid :items="serviceItems" :columns="4" icon-size="lg" />
    </view>
  </xtf-home-sheet>
</template>

<script>
export default {
  data() {
    return {
      sheetIndex: 1,
      serviceItems: [
        { icon: 'receipt_long', title: '账单' },
        { icon: 'account_balance_wallet', title: '钱包' },
        { icon: 'local_atm', title: '提现' },
        { icon: 'analytics', title: '统计' }
      ]
    }
  }
}
</script>

2. 不可拖拽

通过 draggable 禁用手动拖拽：

<template>
  <xtf-home-sheet v-model="sheetIndex" :draggable="false">
    <view class="content">
      <xtf-text text="固定面板内容" />
    </view>
  </xtf-home-sheet>
</template>

<script>
export default {
  data() {
    return {
      sheetIndex: 0
    }
  }
}
</script>

3. 自定义头部、手柄与档位控制

<template>
  <view>
    <xtf-button label="展开面板" @click="$refs.sheet.expand()" />
    <xtf-home-sheet
      ref="sheet"
      v-model="index"
      lock-scroll-until-expanded
      @update:modelValue="onUpdate"
      @change="onChange"
    >
      <template #handle><xtf-icon name="expand_more" theme="secondary" /></template>
      <template #header><xtf-text text="附近服务" level="title" bold /></template>
      <xtf-text text="面板主体内容" />
    </xtf-home-sheet>
  </view>
</template>

<script>
export default {
  data() {
    return { index: 0 }
  },
  methods: {
    onUpdate(value) {
      console.log('update', value)
    },
    onChange(value) {
      uni.showToast({ title: '档位 ' + value, icon: 'none' })
    }
  }
}
</script>

---

全部属性

属性	类型	默认值	作用描述	适用范围
modelValue	String | Number	1	当前档位索引	双向绑定
stops	Array	[0.22, 0.48, 0.88]	停靠比例数组	档位
topInset	String | Number	24	顶部安全距离	安全区
duration	String | Number	240	动画时长(ms)	动画
draggable	Boolean	true	是否可拖拽	交互
maskClosable	Boolean	false	当前遮罩层设置了 pointer-events: none，该属性暂不能通过点击遮罩关闭面板	当前实现限制
lockScrollUntilExpanded	Boolean	false	展开前锁定滚动	滚动
customClass	String	''	自定义类名	样式覆盖
customStyle	String | Object	''	自定义样式	动态样式覆盖

---

事件

事件名称	触发时机	回调参数	参数说明
update:modelValue	档位变化时触发	(index)	新档位索引
change	档位变化时触发	(index)	新档位索引

---

插槽

插槽名称	说明
default	面板内容
handle	自定义拖拽手柄
header	面板头部

第三个示例展示了所有具名插槽的可运行用法。

---

方法

| 方法名 | 参数 | 返回值 | 说明 | | --- | --- | --- | | collapse | - | - | 收起到第 0 档 | | expand | - | - | 展开到最高档 | | open | (index: Number) | - | 切换至指定档位 |

---

主题说明

• 面板顶部圆角 36rpx
• 遮罩透明度随面板位置动态变化
• 拖拽手柄为灰色圆角条

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖相关 CSS 变量。