stellar-ui-plus 1.25.0 → 1.25.2

package/components/ste-drag-sort/README.md

@@ -0,0 +1,116 @@
+# Drag Sort 拖拽排序
+
+用于列表、宫格等场景的拖拽排序组件。
+
+---$
+
+## 代码演示
+
+## 基础用法
+
+- 通过 `v-model` 传入待排序列表
+- 通过具名插槽 `item` 自定义每一项的展示内容
+
+```html
+<script setup lang="ts">
+    import { ref } from 'vue';
+
+    const basicList = ref([{ text: '商品 A' }, { text: '商品 B' }, { text: '商品 C' }]);
+</script>
+
+<template>
+    <ste-drag-sort v-model="basicList">
+        <template #item="{ item, index }">
+            <view class="demo-card-item">{{ index + 1 }}. {{ item.text }}</view>
+        </template>
+    </ste-drag-sort>
+</template>
+
+<style scoped>
+    .demo-card-item {
+        padding: 24rpx;
+        margin-bottom: 16rpx;
+        border-radius: 16rpx;
+        background: #f5f7fa;
+    }
+</style>
+```
+
+## 网格排序
+
+- `columns` 大于 `1` 时会按网格布局排序
+- 网格类纯拖拽场景可按需要设置 `:longPress="false"`
+
+```html
+<script setup lang="ts">
+    import { ref } from 'vue';
+
+    const gridList = ref([{ text: '1' }, { text: '2' }, { text: '3' }, { text: '4' }, { text: '5' }, { text: '6' }]);
+</script>
+
+<template>
+    <ste-drag-sort v-model="gridList" :columns="3" :longPress="false">
+        <template #item="{ item }">
+            <view class="grid-item">{{ item.text }}</view>
+        </template>
+    </ste-drag-sort>
+</template>
+
+<style scoped>
+    .grid-item {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        height: 120rpx;
+        margin: 12rpx;
+        border-radius: 16rpx;
+        background: #eef3ff;
+    }
+</style>
+```
+
+## 禁用单项拖拽
+
+- 列表项数据中可直接写 `disabled: true`
+- 被禁用项会保留展示，但不能被拖拽
+
+```html
+<script setup lang="ts">
+    import { ref } from 'vue';
+
+    const disabledList = ref([{ text: '固定在这里', disabled: true }, { text: '可拖拽 1' }, { text: '可拖拽 2' }]);
+</script>
+
+<template>
+    <ste-drag-sort v-model="disabledList">
+        <template #item="{ item }">
+            <view class="demo-card-item" :style="{ opacity: item.disabled ? 0.5 : 1 }">{{ item.text }}</view>
+        </template>
+    </ste-drag-sort>
+</template>
+```
+
+## longPress 说明
+
+- `longPress=true`：长按后再开始拖拽，适合纵向列表、可滚动页面、移动端场景，可减少误触和页面滚动冲突
+- `longPress=false`：按下后立即开始拖拽，适合网格、纯排序面板、桌面端操作更直接的场景
+- 默认值为 `true`，因为列表排序通常更需要兼顾滚动和点击体验
+
+```html
+<ste-drag-sort v-model="list" :longPress="true" />
+<ste-drag-sort v-model="list" :longPress="false" />
+```
+
+---$
+
+<!-- props -->
+
+## 使用建议
+
+- 列表项高度尽量保持一致，否则排序位移动画可能出现偏差
+- `columns > 1` 时建议每个子项都设置稳定的视觉尺寸，避免网格测量不准
+- 列表排序、可滚动页面、移动端场景优先使用 `longPress`
+- 网格纯拖拽、桌面端快速操作场景可显式设置 `:longPress="false"`
+
+---$
+{{fuyuwei}}

package/components/ste-drag-sort/config.json

@@ -0,0 +1,5 @@
+{
+    "group": "基础组件",
+    "title": "Drag Sort 拖拽排序",
+    "icon": "https://image.whzb.com/chain/StellarUI/组件图标/drag.png?1722389562846"
+}

package/components/ste-drag-sort/props.ts

@@ -0,0 +1,16 @@
+import type { ExtractPropTypes, PropType } from 'vue'
+
+export type SteDragSortItem = Record<string, any> & {
+  disabled?: boolean
+}
+
+const dragSortProps = {
+  modelValue: { type: Array as PropType<SteDragSortItem[]>, default: () => [] },
+  disabled: { type: Boolean, default: false },
+  columns: { type: Number, default: 1 },
+  longPress: { type: Boolean, default: true },
+}
+
+export default dragSortProps
+
+export type SteDragSortProps = ExtractPropTypes<typeof dragSortProps>

package/components/ste-drag-sort/ste-drag-sort.easycom.json

@@ -0,0 +1,88 @@
+{
+    "name": "ste-drag-sort",
+    "description": "拖拽排序组件，支持单列列表和多列网格排序",
+    "example": "<ste-drag-sort v-model='basicList'><template #item=\"{ item, index }\"><view>{{ index + 1 }}. {{ item.text }}</view></template></ste-drag-sort>",
+    "tutorial": "https://stellar-ui.intecloud.com.cn/?projectName=stellar-ui-plus&menu=%E7%BB%84%E4%BB%B6&active=ste-drag-sort",
+    "attributes": [
+        {
+            "name": "modelValue",
+            "description": "拖拽数据列表，支持 v-model 双向绑定",
+            "type": "SteDragSortItem[]",
+            "default": "[]"
+        },
+        {
+            "name": "disabled",
+            "description": "是否禁用拖拽功能",
+            "type": "boolean",
+            "default": false
+        },
+        {
+            "name": "columns",
+            "description": "列数，1 为纵向列表，大于 1 为网格排序",
+            "type": "number",
+            "default": 1
+        },
+        {
+            "name": "longPress",
+            "description": "拖拽启动方式。true 为长按后开始拖拽，适合列表和可滚动页面；false 为按下立即拖拽，适合网格和纯排序面板",
+            "type": "boolean",
+            "default": true
+        },
+        {
+            "name": "[event]start",
+            "description": "开始拖拽时触发",
+            "params": [
+                {
+                    "name": "index",
+                    "description": "当前拖拽项索引"
+                }
+            ]
+        },
+        {
+            "name": "[event]change",
+            "description": "排序结果发生变化时触发",
+            "params": [
+                {
+                    "name": "list",
+                    "description": "最新排序结果"
+                }
+            ]
+        },
+        {
+            "name": "[event]end",
+            "description": "拖拽结束时触发",
+            "params": [
+                {
+                    "name": "index",
+                    "description": "最终落点索引"
+                }
+            ]
+        },
+        {
+            "name": "[slot]item",
+            "description": "单个拖拽项内容",
+            "params": [
+                {
+                    "name": "item",
+                    "description": "当前项数据"
+                },
+                {
+                    "name": "index",
+                    "description": "当前项索引"
+                },
+                {
+                    "name": "dragging",
+                    "description": "当前是否处于拖拽中"
+                },
+                {
+                    "name": "dragIndex",
+                    "description": "当前拖拽项索引"
+                },
+                {
+                    "name": "insertIndex",
+                    "description": "当前插入位置索引"
+                }
+            ]
+        }
+    ]
+}