Openharmony & VCordova三方库适配1.4.0 - 下拉菜单组件

📊 UI 展示

单选下拉菜单

多选下拉菜单

搜索功能

分组选项

为什么需要下拉菜单

在前面的版本中，我们完成了数据展示、图表、弹窗和日期选择。现在需要处理选择问题。

用户需要从一个列表中选择一个或多个选项。比如选择城市、选择分类、选择语言等。下拉菜单是最常见的选择方式。

v1.4.0 的下拉菜单支持单选、多选、搜索、分组等功能。提供丰富的自定义选项和流畅的交互体验。

---

快速上手

第一步：引入文件

<link rel="stylesheet" href="components/dropdown/dropdown.css">
<script src="components/dropdown/dropdown.js"></script>

CSS 文件包含下拉菜单的样式，JS 文件包含 Dropdown 类的实现。

第二步：创建容器

<div id="dropdownContainer"></div>

下拉菜单需要一个容器来放置。这个容器可以是任何 HTML 元素，只要有一个 ID 就行。

第三步：初始化下拉菜单

const dropdown = new Dropdown({
    container: '#dropdownContainer',
    options: [
        { label: '选项1', value: 'opt1' },
        { label: '选项2', value: 'opt2' },
        { label: '选项3', value: 'opt3' }
    ],
    onChange: (value) => {
        console.log('选择的值:', value);
    }
});

初始化很简单。传入一个配置对象，包含以下属性：

• container: 容器选择器
• options: 选项列表
• onChange: 值改变时的回调函数

---

单选下拉菜单

单选下拉菜单用于从列表中选择一个选项。

创建单选下拉菜单

const dropdown = new Dropdown({
    container: '#dropdownContainer',
    options: [
        { label: '北京', value: 'beijing' },
        { label: '上海', value: 'shanghai' },
        { label: '广州', value: 'guangzhou' }
    ],
    onChange: (value) => {
        console.log('选择的城市:', value);
    }
});

用户点击下拉菜单打开选项列表，选择一个选项后菜单自动关闭。

获取选择的值

const value = dropdown.getValue();
console.log(value);  // "beijing"

getValue() 方法返回用户选择的值。

设置初始值

const dropdown = new Dropdown({
    container: '#dropdownContainer',
    options: [...],
    value: 'beijing'  // 设置初始值
});

可以通过 value 属性设置初始值。

---

多选下拉菜单

多选下拉菜单用于从列表中选择多个选项。

创建多选下拉菜单

const dropdown = new Dropdown({
    container: '#dropdownContainer',
    multiple: true,
    options: [
        { label: 'JavaScript', value: 'js' },
        { label: 'Python', value: 'py' },
        { label: 'Java', value: 'java' }
    ],
    onChange: (values) => {
        console.log('选择的语言:', values);
    }
});

多选模式下，用户可以选择多个选项。每个选项前面会显示一个复选框。

获取选择的值

const values = dropdown.getValue();
console.log(values);  // ["js", "py"]

getValue() 方法返回一个数组，包含所有选择的值。

设置初始值

const dropdown = new Dropdown({
    container: '#dropdownContainer',
    multiple: true,
    options: [...],
    value: ['js', 'py']  // 设置初始值
});

可以通过 value 属性设置初始值。

---

搜索功能

搜索功能可以帮助用户快速找到想要的选项。

启用搜索

const dropdown = new Dropdown({
    container: '#dropdownContainer',
    searchable: true,
    options: [
        { label: 'Apple', value: 'apple' },
        { label: 'Banana', value: 'banana' },
        { label: 'Cherry', value: 'cherry' }
    ]
});

设置 searchable: true 就能启用搜索功能。菜单打开时会显示一个搜索框。

搜索回调

const dropdown = new Dropdown({
    container: '#dropdownContainer',
    searchable: true,
    options: [...],
    onSearch: (text) => {
        console.log('搜索文本:', text);
    }
});

onSearch 回调会在用户输入搜索文本时调用。可以用来实现动态搜索或远程搜索。

搜索实现

filterOptions() {
    if (!this.searchText) {
        this.filteredOptions = this.options;
        return;
    }
    
    const text = this.searchText.toLowerCase();
    this.filteredOptions = this.options.filter(option => {
        return option.label.toLowerCase().includes(text) || 
               (option.description && option.description.toLowerCase().includes(text));
    });
}

搜索会同时检查选项的标签和描述。

---

选项分组

选项分组可以将相关的选项组织在一起。

创建分组选项

const dropdown = new Dropdown({
    container: '#dropdownContainer',
    options: [
        { group: '水果' },
        { label: '苹果', value: 'apple' },
        { label: '香蕉', value: 'banana' },
        { group: '蔬菜' },
        { label: '番茄', value: 'tomato' },
        { label: '黄瓜', value: 'cucumber' }
    ]
});

使用 group 属性创建分组标题。分组标题不能被选择。

分组显示

// 分组标题会显示为灰色的分组标签
// 同一分组下的选项会显示在一起

分组标题会显示为灰色的分组标签，帮助用户快速定位选项。

---

禁用选项

可以禁用某些选项，使用户无法选择它们。

禁用单个选项

const dropdown = new Dropdown({
    container: '#dropdownContainer',
    options: [
        { label: '启用', value: 'enabled' },
        { label: '禁用', value: 'disabled', disabled: true },
        { label: '启用', value: 'enabled2' }
    ]
});

设置 disabled: true 就能禁用一个选项。禁用的选项会显示为灰色且不可点击。

禁用整个下拉菜单

const dropdown = new Dropdown({
    container: '#dropdownContainer',
    disabled: true,
    options: [...]
});

设置 disabled: true 就能禁用整个下拉菜单。

---

选项描述

可以为选项添加描述，帮助用户更好地理解选项。

添加选项描述

const dropdown = new Dropdown({
    container: '#dropdownContainer',
    options: [
        { label: '标准版', value: 'standard', description: '¥99/月' },
        { label: '专业版', value: 'pro', description: '¥199/月' },
        { label: '企业版', value: 'enterprise', description: '¥499/月' }
    ]
});

description 属性用来添加选项的描述。描述会显示在选项标签的右侧。

---

清空功能

清空功能可以让用户快速清除所有选择。

启用清空按钮

const dropdown = new Dropdown({
    container: '#dropdownContainer',
    clearable: true,
    options: [...]
});

设置 clearable: true 就能启用清空按钮。当有选择时，会在下拉菜单右侧显示一个清空按钮。

手动清空

dropdown.clear();

clear() 方法可以手动清空所有选择。

---

动态更新

下拉菜单初始化后，可以动态更新选项和值。

更新选项

dropdown.setOptions([
    { label: '新选项1', value: 'new1' },
    { label: '新选项2', value: 'new2' }
]);

setOptions() 方法可以更新选项列表。这对于从服务器加载选项的场景很有用。

更新值

// 单选
dropdown.setValue('opt1');

// 多选
dropdown.setValue(['opt1', 'opt2']);

setValue() 方法可以更新选择的值。

获取标签

const labels = dropdown.getSelectedLabels();
// 单选: "选项1"
// 多选: ["选项1", "选项2"]

getSelectedLabels() 方法返回选择的标签而不是值。

---

---

总结

v1.4.0 下拉菜单组件完成了选择功能。结合前面的组件，现在我们有了完整的数据展示、交互、输入和选择解决方案。

下拉菜单的设计也很简洁。支持单选和多选两种模式，提供搜索、分组、禁用等功能。这就是"开箱即用"的理念。

后续版本会继续添加更多组件。下一个是文件上传，再后面还有标签、进度条等等。每个组件都会遵循同样的设计理念：简洁、高效、易用。

https://gitcode.com/nutpi/openHarmony_Cordova_NutpiDesign