add dropdown document

lib/ui/dropdown.html

@@ -4,88 +4,235 @@
   <p>
     创建一个统一样式的下拉输入、选择框元素，或者解析转换页面上的 select 标签为该元素。
   </p>
-  <!-- <h2>createCheckbox</h2>
-  <code>function createCheckbox(opts?: CheckboxOptions): HTMLElement</code>
-  <h3>opts?: CheckboxOptions</h3>
+  <h2>constructor</h2>
+  <code>new(options?: DropdownOptions): Dropdown</code>
+  <h3>options?: DropdownOptions</h3>
   <p>
-    复选框初始参数，结构为
-  <pre>interface CheckboxOptions {
-    type?: string;
-    label?: string;
-    checked?: boolean;
-    isImage?: boolean;
-    imageHeight?: Number;
-    checkedNode?: HTMLElement;
-    uncheckedNode?: HTMLElement;
-    customerAttributes?: { [key: string]: string };
-    onchange?: (this: HTMLInputElement, ev: Event) => any;
+    下拉输入、选择框的初始参数，结构为
+  <pre>interface DropdownOptions {
+    textkey?: string;
+    valuekey?: string;
+    htmlkey?: string;
+    maxlength?: Number;
+    multiselect?: boolean;
+    selected?: string;
+    selectedlist?: Array&lt;DropdownItem | any&gt;;
+    disabled?: boolean;
+    input?: boolean;
+    search?: boolean;
+    searchkeys?: Array&lt;string&gt;;
+    searchplaceholder?: string;
+    tabindex?: Number;
+    placeholder?: string;
+    slidefixed?: boolean;
+    parent?: HTMLElement;
 }</pre>
   </p>
-  <h3>type?: string</h3>
+  <h3>textkey?: string</h3>
   <p>
-    复选框图标的样式，可选值目前有 <code>fa-regular</code>、<code>fa-light</code>、<code>fa-solid</code>
+    数据源中用以显示的属性，默认为 <code>text</code>
   </p>
-  <h3>label?: string | HTMLElement</h3>
+  <h3>valuekey?: string</h3>
   <p>
-    复选框的标签文本，或者想要呈现的元素
+    数据源中作为值的属性，默认为 <code>value</code>
   </p>
-  <h3>checked?: boolean</h3>
+  <h3>htmlkey?: string</h3>
   <p>
-    初始是否选中
+    数据源中用来以 html 方式呈现的属性，默认为 <code>html</code>
   </p>
-  <h3>isImage?: boolean</h3>
+  <h3>maxlength?: Number</h3>
   <p>
-    是否为图片复选框
+    作为输入类型时的最大允许字符数，默认为 500
   </p>
-  <h3>imageHeight?: Number</h3>
+  <h3>multiselect?: boolean</h3>
   <p>
-    为图片复选框时的图片限制高度
+    是否允许多选，仅在选择类型下有效
   </p>
-  <h3>checkedNode?: HTMLElement</h3>
+  <h3>selected?: string</h3>
   <p>
-    为图片复选框时的选中时显示的元素
+    默认选中的项目的值
   </p>
-  <h3>uncheckedNode?: HTMLElement</h3>
+  <h3>selectedlist?: Array&lt;DropdownItem | any&gt;</h3>
   <p>
-    为图片复选框时的未选中时显示的元素
+    多选时默认选中的项目的值的列表
   </p>
-  <h3>customerAttributes?: { [key: string]: string }</h3>
+  <h3>disabled?: boolean</h3>
   <p>
-    自定义属性，例如
-    <pre>{
-    'data-id': 'xxxxxx',
-    'disabled': ''
-}</pre>
+    初始化时下拉框是否禁用
   </p>
-  <h3>onchange?: (this: HTMLInputElement, ev: Event) => any</h3>
+  <h3>input?: boolean</h3>
   <p>
-    复选框改变时触发的事件
+    是否为输入类型
   </p>
-  <h2>resolveCheckbox</h2>
-  <code>function resolveCheckbox(container?: HTMLElement, legacy?: boolean): HTMLElement</code>
-  <h3>container?: HTMLElement</h3>
+  <h3>search?: boolean</h3>
   <p>
-    将把此 HTML 元素，为 null 则把 document.body 下的所有 <code>label[data-checkbox]</code> 元素解析为复选框，<code>[data-id]</code> 为复选框元素的 id，包含
-    <code>[data-checked]</code> 时复选框默认选中。
+    是否允许搜索
   </p>
-  <p>当该元素无子元素时，<code>[data-type]</code> 同上述参数中的 <code>type?: string</code>，<code>[data-label]</code> 同上述参数中的
-    <code>label?: string</code>。
-  </p>
-  <p>当该元素有子元素时，解析为图片复选框，class 为 <code>checked</code>、<code>unchecked</code> 的子元素将分别在选中与未选中时显示。</p>
-  <h3>legacy?: boolean</h3>
+  <h3>searchkeys?: Array&lt;string&gt;</h3>
   <p>
-    是否开启兼容模式，启用兼容模式时将试图匹配 <code>input[type="checkbox"]</code> 标签，与其周围的 label，将其转换为统一样式的复选框。
+    搜索时搜索的数据源属性的列表，默认为 <code>[valuekey]</code>
   </p>
-  <hr /> -->
+  <h3>searchplaceholder?: string</h3>
+  <p>
+    搜索输入框的占位字符串
+  </p>
+  <h3>tabindex?: Number</h3>
+  <p>
+    下拉框的焦点顺序
+  </p>
+  <h3>placeholder?: string</h3>
+  <p>
+    作为输入类型时，输入框的占位字符串
+  </p>
+  <h3>slidefixed?: boolean</h3>
+  <p>
+    下拉方向是否固定为下
+  </p>
+  <h3>parent?: HTMLElement</h3>
+  <p>
+    下拉列表呈现的父容器，默认为 <code>document.body</code>
+  </p>
+  <h2>Dropdown.resolve</h2>
+  <code>static resolve(dom?: HTMLElement): HTMLElement</code>
+  <h3>dom?: HTMLElement</h3>
+  <p>
+    将把此 HTML 元素，为 null 则把 document.body 下的所有 <code>select</code> 元素解析为统一样式的下拉框
+  </p>
+  <hr />
+  <h2>sourceFilter</h2>
+  <code>sourceFilter: () => Array&lt;DropdownItem | any&gt;</code>
+  <p>
+    数据源代理，返回用以呈现在下拉列表中的数据源
+  </p>
+  <h2>onselected</h2>
+  <code>onselected: (item: DropdownItem | any) => void</code>
+  <h3>item: DropdownItem | any</h3>
+  <p>
+    选中项发生改变时触发该事件，参数为选中的项
+  </p>
+  <h2>onselectedlist</h2>
+  <code>onselectedlist: (list: Array&lt;DropdownItem | any&gt;) => void</code>
+  <h3>list: Array&lt;DropdownItem | any&gt;</h3>
+  <p>
+    多选时选中列表发生改变时触发该事件，参数为选中的列表
+  </p>
+  <h2>onexpanded</h2>
+  <code>onexpanded: () => void</code>
+  <p>
+    下拉列表展开时触发该事件，一般用来异步获取服务器数据，填充至数据源
+  </p>
+  <hr />
+  <h2>disabled</h2>
+  <code>property disabled(): boolean</code>
+  <p>
+    获取或设置下拉框是否禁用
+  </p>
+  <h2>source</h2>
+  <code>property source(): Array&lt;DropdownItem | any&gt;</code>
+  <p>
+    获取或设置下拉框数据源
+  </p>
+  <h2>multiselect</h2>
+  <code>readonly multiselect: boolean</code>
+  <p>
+    获取下拉框是否支持多选
+  </p>
+  <h2>selected</h2>
+  <code>readonly selected: DropdownItem | any</code>
+  <p>
+    获取下拉框当前选中项
+  </p>
+  <h2>selectedlist</h2>
+  <code>readonly selectedlist: Array&lt;DropdownItem | any&gt;</code>
+  <p>
+    获取下拉框当前选中的列表
+  </p>
+  <hr />
+  <h2>create</h2>
+  <code>create(): HTMLElement</code>
+  <p>
+    创建下拉列表，返回一个 HTML 元素
+  </p>
+  <h2>select</h2>
+  <code>select(selected: string, silence?: boolean): void</code>
+  <h3>selected: string</h3>
+  <p>
+    修改下拉框的选中项为参数值对应的项
+  </p>
+  <h3>silence?: boolean</h3>
+  <p>
+    是否静默修改，为 true 时不触发 <code>onselected</code> 事件
+  </p>
+  <h2>selectlist</h2>
+  <code>selectlist(selectedlist: Array&lt;string&gt;, silence?: boolean): void</code>
+  <h3>selectedlist: Array&lt;string&gt;</h3>
+  <p>
+    修改下拉框的选中列表为参数值列表对应的项的列表
+  </p>
+  <h3>silence?: boolean</h3>
+  <p>
+    是否静默修改，为 true 时不触发 <code>onselectedlist</code> 事件
+  </p>
+  <hr />
   <h2>示例</h2>
-  <pre></pre>
-  <div id="dropdown-sample">
+  <pre>&lt;div id="dropdown-sample"&gt;
+  &lt;select&gt;
+    &lt;option value="cs1"&gt;Case 1&lt;/option&gt;
+    &lt;option value="cs2" selected&gt;Case 2&lt;/option&gt;
+    &lt;option value="cs3"&gt;Case 3&lt;/option&gt;
+  &lt;/select&gt;
+&lt;/div&gt;
+
+&lt;script type="text/javascript"&gt;
+  const Dropdown = window["lib-ui"].Dropdown;
+  const sample = document.querySelector('#dropdown-sample');
+
+  // 解析 select 元素
+  Dropdown.resolve(sample);
+
+  // 创建简易输入类型下拉框
+  let drop = new Dropdown({
+    input: true,
+    // selected: 'standby',
+    placeholder: 'asset status',
+    slidefixed: true
+  });
+  drop.source = ['off', 'running', 'standby', 'broken']
+    .map(it => { return { value: it, text: it } });
+  sample.appendChild(drop.create());
+
+  // 创建自定义显示元素的下拉框
+  drop = new Dropdown({
+    selected: '#ff0',
+    search: true,
+    // multiselect: true
+  });
+  drop.source = [
+    { value: '#fff', text: 'White' },
+    { value: '#f00', text: 'Red' },
+    { value: '#0f0', text: 'Green' },
+    { value: '#00f', text: 'Blue' },
+    { value: '#ff0', text: 'Yellow' },
+    { value: '#0ff', text: 'Cyan' },
+    { value: '#f0f', text: 'Magenta' },
+  ];
+  drop.source.forEach(it => {
+    const span = document.createElement('span');
+    span.className = 'drop-item';
+    span.style.setProperty('--color', it.value);
+    span.innerText = it.text;
+    it.html = span;
+  });
+  sample.appendChild(drop.create());
+&lt;/script&gt;</pre>
+    <div id="dropdown-sample">
     <select>
       <option value="cs1">Case 1</option>
       <option value="cs2" selected>Case 2</option>
       <option value="cs3">Case 3</option>
     </select>
   </div>
+  <div style="height: 80px"></div>
   <script type="text/javascript">
     !function () {
       const Dropdown = window["lib-ui"].Dropdown;
@@ -95,7 +242,9 @@
 
       let drop = new Dropdown({
         input: true,
-        selected: 'standby'
+        // selected: 'standby',
+        placeholder: 'asset status',
+        slidefixed: true
       });
       drop.source = ['off', 'running', 'standby', 'broken']
         .map(it => { return { value: it, text: it } });
@@ -104,7 +253,7 @@
       drop = new Dropdown({
         selected: '#ff0',
         search: true,
-        multiselect: true
+        // multiselect: true
       });
       drop.source = [
         { value: '#fff', text: 'White' },