# # Dropdown 组件

## # 代码示例

### # 基础示例

    <html>
        <template id="layout-template">
            <webpdf>
                <div>
                    <dropdown icon-class="fv__icon-toolbar-shape" text="Dropdown">
                        <xbutton icon-class="fv__icon-toolbar-square">Square</xbutton>
                        <xbutton icon-class="fv__icon-toolbar-circle">Circle</xbutton>
                        <li class="fv__ui-dropdown-separator"></li>
                        <file-selector>Select a file</file-selector>
                        <li class="my-dropdown-list-item">
                        </li>
                    </dropdown>
                </div>
                <div class="fv__ui-body">
                    <viewer></viewer>
                </div>
            </webpdf>
        </template>
    </html>
    <style>
        .my-dropdown-list-item {
            padding: 10px 0;
            text-align: center;
        }
        .fv__ui-dropdown {
            width: auto;
        }
    </style>
    <script>
        var CustomAppearance = UIExtension.appearances.Appearance.extend({
            getLayoutTemplate: function() {
                return document.getElementById('layout-template').innerHTML;
            },
            disableAll: function(){}
        });
        var libPath = window.top.location.origin + '/lib';
        var pdfui = new UIExtension.PDFUI({
                viewerOptions: {
                    libPath: libPath,
                    jr: {
                        licenseSN: licenseSN,
                        licenseKey: licenseKey
                    }
                },
                renderTo: document.body,
                appearance: CustomAppearance,
                addons: []
        });
    </script>

    {
        "iframeOptions": {
            "style": "height: 500px"
        }
    }

### # Separation

Dropdown 的按钮可以分成左右两部分，左半部分由图标，文本组成，右半部分则为下拉箭头。当 `separate` 参数设置为 false 时，点击左右两个部分都能够使下拉列表显示，当 `separate` 参数设置为 true 时，则只有点击下拉箭头才会使下拉列表显示。

在以下的 demo 中，您将看到两个 dropdown button，如下所示：

尝试点击 'Separated Dropdown' 按钮，您将注意到 dropdown 列表只能在单击箭头时显示。这是因为 dropdown button 已被分离，只有单击箭头时才会触发 dropdown 列表。但是，您可以通过单击 `Un-separated Dropdown` 按钮的任意区域来显示 dropdown 列表。

    <html>
        <template id="layout-template">
            <webpdf>
                <div>
                    <!-- By default, the value of dropdown's 'separate' option is true -->
                    <!-- Set selected="0" means when you click on the dropdown button, it will trigger the event for  the first item in the dropdown list -->
                    <dropdown name="separate-dropdown" icon-class="fv__icon-toolbar-square" text="Separated Dropdown" selected="0">
                        <xbutton name="separate-dropdown-square-btn" icon-class="fv__icon-toolbar-square">Square</xbutton>
                        <xbutton icon-class="fv__icon-toolbar-circle">Circle</xbutton>
                        <file-selector>Select a file</file-selector>
                        <li class="my-dropdown-list-item">
                            html &lt;li&gt; tag
                        </li>
                    </dropdown>
                    <dropdown name="non-separate-dropdown" icon-class="fv__icon-toolbar-shape" text="Un-separated Dropdown" separate="false">
                        <xbutton icon-class="fv__icon-toolbar-square">Square</xbutton>
                        <xbutton icon-class="fv__icon-toolbar-circle">Circle</xbutton>
                    </dropdown>
                </div>
                <div class="fv__ui-body">
                    <viewer></viewer>
                </div>
            </webpdf>
        </template>
    </html>
    <style>
        .my-dropdown-list-item {
            padding: 10px 0;
            text-align: center;
        }
        .fv__ui-dropdown {
            width: auto;
        }
    </style>
    <script>
        var CustomAppearance = UIExtension.appearances.Appearance.extend({
            getLayoutTemplate: function() {
                return document.getElementById('layout-template').innerHTML;
            },
            getDefaultFragments: function() {
                return [{
                    target: 'separate-dropdown-square-btn',
                    config: [{
                        callback: function() {
                            alert('Click on separate Dropdown');
                        }
                    }]
                }];
            },
            disableAll: function(){}
        });
        var libPath = window.top.location.origin + '/lib';
        var pdfui = new UIExtension.PDFUI({
                viewerOptions: {
                    libPath: libPath,
                    jr: {
                        licenseSN: licenseSN,
                        licenseKey: licenseKey
                    }
                },
                renderTo: document.body,
                appearance: CustomAppearance,
                addons: []
        });
    </script>

    {
        "iframeOptions": {
            "style": "height: 500px"
        }
    }

### # 作为 select 组件使用

    <html>
        <template id="layout-template">
            <webpdf>
                <div>
                    <!-- Specify selected="0" that is the initial value -->
                    <dropdown name="separate-dropdown" icon-class="fv__icon-toolbar-square" text="Separated Dropdown" selected="0">
                        <xbutton name="separate-dropdown-square-btn" icon-class="fv__icon-toolbar-square">Square</xbutton>
                        <xbutton icon-class="fv__icon-toolbar-circle">Circle</xbutton>
                    </dropdown>
                    <dropdown name="not-separate-dropdown" icon-class="fv__icon-toolbar-shape" text="not separated Dropdown" separate="false" selected="0">
                        <xbutton icon-class="fv__icon-toolbar-square">Square</xbutton>
                        <xbutton icon-class="fv__icon-toolbar-circle">Circle</xbutton>
                    </dropdown>
                </div>
                <div class="fv__ui-body">
                    <viewer></viewer>
                </div>
            </webpdf>
        </template>
    </html>
    <style>
        .my-dropdown-list-item {
            padding: 10px 0;
            text-align: center;
        }
        .fv__ui-dropdown {
            width: auto;
        }
    </style>
    <script>
        var CustomAppearance = UIExtension.appearances.Appearance.extend({
            getLayoutTemplate: function() {
                return document.getElementById('layout-template').innerHTML;
            },
            getDefaultFragments: function() {
                return [{
                    target: 'separate-dropdown @xbutton,not-separate-dropdown @xbutton',
                    config: [{
                        callback: function() {
                            this.component.parent.select(this.component);
                        }
                    }]
                }];
            },
            disableAll: function(){}
        });
        var libPath = window.top.location.origin + '/lib';
        var pdfui = new UIExtension.PDFUI({
                viewerOptions: {
                    libPath: libPath,
                    jr: {
                        licenseSN: licenseSN,
                        licenseKey: licenseKey
                    }
                },
                renderTo: document.body,
                appearance: CustomAppearance,
                addons: []
        });
    </script>

    {
        "iframeOptions": {
            "style": "height: 500px"
        }
    }

### # 可编辑的

    <html>
        <template id="layout-template">
            <webpdf>
                <div>
                    <dropdown name="font-editable-dropdown" editable>
                        <xbutton>Helvetica</xbutton>
                        <xbutton>Courier</xbutton>
                        <xbutton>Times-Bold</xbutton>
                        <xbutton>宋体</xbutton>
                    </dropdown>
                    <dropdown name="zoom-editable-dropdown" editable @controller="custom:ZoomPageController">
                        <xbutton @controller="custom:ScaleRatioController" scale="0.5">50%</xbutton>
                        <xbutton @controller="custom:ScaleRatioController" scale="0.75">75%</xbutton>
                        <xbutton @controller="custom:ScaleRatioController" scale="1">100%</xbutton>
                    </dropdown>
                </div>
                <div class="fv__ui-body">
                    <viewer></viewer>
                </div>
            </webpdf>
        </template>
    </html>
    <style>
        .fv__ui-dropdown {
            width: 80px;
        }
    </style>
    <script>
        UIExtension.PDFUI.module('custom', [])
        .controller('ScaleRatioController', {
            handle: function() {
                const scaleRatio = parseFloat(this.component.element.getAttribute('scale'));
                debugger;
                this.component.parent.setEditValue(scaleRatio);
            }
        })
        .controller('ZoomPageController', {
            mounted: function() {
                const component = this.component;
                const firstChild = component.childAt(0);
                const scaleRatio = parseFloat(firstChild.element.getAttribute('scale'))
                component.setEditValue(scaleRatio);
                component.on('change', function(newValue, oldValue) {
                    if(isNaN(parseFloat(newValue))) {
                        alert('Illegal scale value: ' + newValue);
                        component.setEditValue(oldValue);
                        return;
                    }
                    alert('scale value changed to: ' + newValue)
                })
            }
        });
        var CustomAppearance = UIExtension.appearances.Appearance.extend({
            getLayoutTemplate: function() {
                return document.getElementById('layout-template').innerHTML;
            },
            getDefaultFragments() {
                return [{
                    target: 'zoom-editable-dropdown',
                    config: {
                        editOptions: {
                            type: 'number',
                            min: 0,
                            max: 10,
                            step: 0.01
                        }
                    }
                }];
            },
            disableAll: function(){}
        });
        var libPath = window.top.location.origin + '/lib';
        var pdfui = new UIExtension.PDFUI({
                viewerOptions: {
                    libPath: libPath,
                    jr: {
                        licenseSN: licenseSN,
                        licenseKey: licenseKey
                    }
                },
                renderTo: document.body,
                appearance: CustomAppearance,
                addons: []
        });
    </script>

    {
        "iframeOptions": {
            "style": "height: 500px"
        }
    }

### # 定位 dropdown 列表

    <html>
        <template id="layout-template">
            <webpdf>
                <div class="flex-with-gap">
                    <dropdown text="Align left,bottom(default position)" align="left" valign="bottom">
                        <li>left bottom</li>
                    </dropdown>
                    <dropdown text="Align right,bottom" align="right" valign="bottom">
                        <li>right bottom</li>
                    </dropdown>
                    <dropdown text="Align center,bottom" align="center" valign="bottom">
                        <li>center bottom</li>
                    </dropdown>
                </div>
                <div class="flex-with-gap">
                    <dropdown text="Align out-right,bottom" align="out-right" valign="bottom">
                        <li>out-right bottom</li>
                    </dropdown>
                    <dropdown text="Align client-center,bottom" align="client-center" valign="bottom">
                        <li>client-center bottom</li>
                    </dropdown>
                    <dropdown text="Align out-left,bottom" align="out-left" valign="bottom">
                        <li>out-left bottom</li>
                    </dropdown>
                </div>
                <div class="flex-with-gap">
                    <dropdown text="Align left,client-center" align="left" valign="client-center">
                        <li>left client-center</li>
                    </dropdown>
                    <dropdown text="Align client-center,client-center" align="client-center" valign="client-center">
                        <li>client-center</li>
                    </dropdown>
                    <dropdown text="Align left,top" align="left" valign="top">
                        <li>left top</li>
                    </dropdown>
                </div>
                <div class="fv__ui-body">
                    <viewer></viewer>
                </div>
            </webpdf>
        </template>
    </html>
    <style>
        .fv__ui-dropdown {
            width: auto;
        }
        .flex-with-gap {
            display: flex;
            flex-direction: row;
            justify-content: center;
        }
        .flex-with-gap>.fv__ui-dropdown {
            margin: 0 20px;
            flex: 1 1 auto;
        }
    </style>
    <script>
        var CustomAppearance = UIExtension.appearances.Appearance.extend({
            getLayoutTemplate: function() {
                return document.getElementById('layout-template').innerHTML;
            },
            disableAll: function(){}
        });
        var libPath = window.top.location.origin + '/lib';
        var pdfui = new UIExtension.PDFUI({
                viewerOptions: {
                    libPath: libPath,
                    jr: {
                        licenseSN: licenseSN,
                        licenseKey: licenseKey
                    }
                },
                renderTo: document.body,
                appearance: CustomAppearance,
                addons: []
        });
    </script>

    {
        "iframeOptions": {
            "style": "height: 500px"
        }
    }

### # 动态 dropdown 列表

    <html>
        <template id="layout-template">
            <webpdf>
                <div>
                    <dropdown separate="false" @controller="custom:DropdownItemListController as ctrl" text="Dynamic dropdown list">
                        <li style="padding-left: 1em;">Click button to create more</li>
                        <li @foreach="item in ctrl.items track by id">
                            <text @sync.text="item.text"></text>
                        </li>
                        <xbutton icon-class="fv__icon-toolbar-add-sign" @controller="custom:AddItemController">Add dropdown item</xbutton>
                    </dropdown>
                </div>
                <div class="fv__ui-body">
                    <viewer></viewer>
                </div>
            </webpdf>
        </template>
    </html>
    <style>
        .fv__ui-dropdown {
            width: auto;
        }
    </style>
    <script>
        UIExtension.PDFUI.module('custom', [])
            .controller('DropdownItemListController', {
                init: function() {
                    this.items = [{
                        id: Date.now().toString(16),
                        text: new Date().toLocaleString()
                    }];
                },
                addItem: function(data) {
                    this.items = this.items.concat(data);
                    this.digest();
                }
            })
            .controller('AddItemController', {
                handle: function() {
                    const itemListCtrl = this.data.ctrl;
                    itemListCtrl.addItem({
                        id: Date.now().toString(16),
                        text: new Date().toLocaleString()
                    });
                }
            })
        var CustomAppearance = UIExtension.appearances.Appearance.extend({
            getLayoutTemplate() {
                return document.getElementById('layout-template').innerHTML;
            },
            disableAll(){}
        });
        var libPath = window.top.location.origin + '/lib';
        var pdfui = new UIExtension.PDFUI({
                viewerOptions: {
                    libPath: libPath,
                    jr: {
                        licenseSN: licenseSN,
                        licenseKey: licenseKey
                    }
                },
                renderTo: document.body,
                appearance: CustomAppearance,
                addons: []
        });
    </script>

    {
        "iframeOptions": {
            "style": "height: 500px"
        }
    }

## # API

### # Dropdown 组件模板

模板示例:

    <dropdown text="" icon-class="" editable align="left" valign="bottom" separate="true" selected="0"></dropdown>

模板属性:

属性 | 描述 | 类型 | 默认值 | 版本
--- | --- | --- | --- | ---
text | 设置 dropdown button 文本 | `string` | `''` | 7.0
icon-class | 设置图标的 css class | `string` | `''` | 7.0
editable | 是否可编辑 | `boolean` | `false` | 7.0
align | 水平对齐 | `'left'|'right'|'out-right'| 'out-left'|'center'|'client-center'` | `'left'` | 7.0
valign | 垂直对齐 | `'top'|'bottom'|'center'|'client-center'` | `'bottom'` | 7.0
separate | dropdown button 是否分离 | `boolean` | `true` | 7.0

#### # 使用 fragment 配置 dropdown 属性

除了 `editOptions`，其他属性与模板属性一样。

    {
        target: 'dropdown-name',
        config: {
            editOptions: {
                type: 'text',
                min: 0,
                max: 0,
                step: 0,
                vallue: ''
            }
        }
    }

属性 | 描述 | 类型 | 默认值 | 版本
--- | --- | --- | --- | ---
editOptions.type | 指定 dropdown 编辑模式，支持 `'text'` 和 `'number'`。 | `string` | `'text'` | 7.0
editOptions.min | 编辑框的最小值。只有当编辑模式为 `'number'` 时才有效。 | `number` |  | 7.0
editOptions.max | 编辑框的最大值。只有当编辑模式为 `'number'` 时才有效。 | `number` |  | 7.0
editOptions.step | 编辑框的操作步骤。只有当编辑模式为 `'number'` 时才有效。 | `number` |  | 7.0
editOptions.value | 编辑框的初始值 | `string|number` |  | 7.0

### # Dropdown 对象属性

属性 | 描述 | 类型
--- | --- | ---
disabled | Dropdown 禁用状态 | `boolean`
isVisible | Dropdown 可见状态 | `boolean`
isActive | 检查 dropdown 列表是否处于活动状态 | `boolean`

### # 方法

方法 | 描述 | 版本
--- | --- | ---
`setEditValue(text: String|number): void` | 设置输入值。其不会触发 `change` 事件。 | 7.0
`disable(): void` | 禁用 dropdown | 7.0
`enable(): void` | 启用被禁用的 dropdown | 7.0
`show(): void` | 显示隐藏的 dropdown | 7.0
`hide(): void` | 隐藏 dropdown | 7.0
`active(): void` | 打开 dropdown | 7.0
`deactive(): void` | 关闭 dropdown | 7.0
`destroy(): void` | 销毁组件 | 7.0

## # 事件

名称 | 描述 | 示例 | 版本
--- | --- | --- | ---
active | 展开/显示下拉列表时触发 | `dropdown.on('active', () => {})` | 7.0
deactive | 隐藏 dropdown 时触发 | `dropdown.on('deactive', () => {})` | 7.0
change | 在鼠标进入和焦点丢失时触发 | `dropdown.on('change', (newValue,oldValue) => {})` | 7.0