# # `form-group` 组件

`<form-group>` 组件用于向表单中添加某些具有特定结构的控件。它可以很方便地用来组织输入组件与标签的布局，以及显示帮助文本。

## # 代码示例

### # 标签文本

表单组件的标签描述文本，用于指示一个输入组件。

#### # 标签文本布局

`form-group` 组件的标签文本支持三种布局方式： `ltr`, `rtl` 和 `ttb`:

- 其中 `ltr` 和 `rtl` 是水平布局, 表示标签文本和输入组件显示在同一行。
- `ltr` 表示标签文本显示在输入组件的左侧。
- `rtl` 表示标签文本显示在输入组件的右侧。
- `ttb` 则是垂直布局，表示标签文本显示在输入组件的上方。

下面的示例演示了这三种布局的效果:

    <html>
        <template id="layout-template">
            <webpdf>
                <toolbar>
                    <group-list>
                        <group name="home-tab-group-hand">
                            <hand-ribbon-button></hand-ribbon-button>
                            <open-file-ribbon-dropdown></open-file-ribbon-dropdown>
                            <download-file-ribbon-button></download-file-ribbon-button>
                        </group>
                    </group-list>
                </toolbar>
                <div class="fv__ui-body">
                    <viewer></viewer>
                </div>
                <template name="template-container">
                    <layer class="center" visible="true" backdrop style="width: 640px">
                        <layer-header title="form-group component example"  @draggable="{type: 'parent'}"></layer-header>
                        <layer-view>
                            <fieldset>
                                <legend>direction="ltr"</legend>
                                <form-group label="Name">
                                    <input>
                                </form-group>
                                <form-group label="Email">
                                    <input type="email">
                                </form-group>
                                <form-group label="Address">
                                    <input type="address">
                                </form-group>
                            </fieldset>
                            <fieldset>
                                <legend>direction="rtl"</legend>
                                <form-group label="Name" direction="rtl">
                                    <input>
                                </form-group>
                                <form-group label="Email" direction="rtl">
                                    <input type="email">
                                </form-group>
                                <form-group label="Address" direction="rtl">
                                    <input type="address">
                                </form-group>
                            </fieldset>
                            <fieldset>
                                <legend>direction="ttb"</legend>
                                <form-group label="Name" direction="ttb">
                                    <input>
                                </form-group>
                                <form-group label="Email" direction="ttb">
                                    <input type="email">
                                </form-group>
                                <form-group label="Address" direction="ttb">
                                    <input type="address">
                                </form-group>
                            </fieldset>
                        </layer-view>
                    </layer>
                </template>
            </webpdf>
        </template>
    </html>
    <style>
        .fv__ui-form-group-label {
            width: 5em;
        }
        .fv__ui-form-group {
            margin-bottom: 10px;
            color: #666;
        }
        input {
            border: 1px solid #ddd;
            margin-right: 1em;
        }
    </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"
        }
    }

#### # 标签分隔符

从上面的示例可以注意到， 当 `direction` 设置为 `ltr` 和 `ttb` 时，会自动显示 `:` 号分隔符，如果你不需要它，可以将其置空以隐藏：

    <html>
        <template id="layout-template">
            <webpdf>
                <toolbar>
                    <group-list>
                        <group name="home-tab-group-hand">
                            <hand-ribbon-button></hand-ribbon-button>
                            <open-file-ribbon-dropdown></open-file-ribbon-dropdown>
                            <download-file-ribbon-button></download-file-ribbon-button>
                        </group>
                    </group-list>
                </toolbar>
                <div class="fv__ui-body">
                    <viewer></viewer>
                </div>
                <template name="template-container">
                    <layer class="center" visible="true" backdrop style="width: 640px">
                        <layer-header title="form-group component example"  @draggable="{type: 'parent'}"></layer-header>
                        <layer-view>
                            <fieldset>
                                <legend>direction="ltr" delimiter=""</legend>
                                <form-group label="Name" delimiter="">
                                    <input>
                                </form-group>
                                <form-group label="Email" delimiter="">
                                    <input type="email">
                                </form-group>
                                <form-group label="Address" delimiter="">
                                    <input type="address">
                                </form-group>
                            </fieldset>
                            <fieldset>
                                <legend>direction="ttb" delimiter=""</legend>
                                <form-group label="Name" direction="ttb" delimiter="">
                                    <input>
                                </form-group>
                                <form-group label="Email" direction="ttb" delimiter="">
                                    <input type="email">
                                </form-group>
                                <form-group label="Address" direction="ttb" delimiter="">
                                    <input type="address">
                                </form-group>
                            </fieldset>
                        </layer-view>
                    </layer>
                </template>
            </webpdf>
        </template>
    </html>
    <style>
        .fv__ui-form-group-label {
            width: 5em;
        }
        .fv__ui-form-group {
            margin-bottom: 10px;
            color: #666;
        }
        input {
            border: 1px solid #ddd;
            margin-right: 1em;
        }
    </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: 400px"
        }
    }

### # 帮助文本

帮助文本是可选的，主要用于显示一些组件描述信息，可以通过 `description` 属性来设置内容，内容支持 i18n 词条。

下面的示例展示了不同布局下的帮助文本样式：

    <html>
        <template id="layout-template">
            <webpdf>
                <toolbar>
                    <group-list>
                        <group name="home-tab-group-hand">
                            <hand-ribbon-button></hand-ribbon-button>
                            <open-file-ribbon-dropdown></open-file-ribbon-dropdown>
                            <download-file-ribbon-button></download-file-ribbon-button>
                        </group>
                    </group-list>
                </toolbar>
                <div class="fv__ui-body">
                    <viewer></viewer>
                </div>
                <template name="template-container">
                    <layer class="center" visible="true" backdrop style="width: 640px">
                        <layer-header title="form-group component example"  @draggable="{type: 'parent'}"></layer-header>
                        <layer-view>
                            <fieldset>
                                <legend>direction="ltr"</legend>
                                <form-group label="Name" description="让我们知道你的名字">
                                    <input>
                                </form-group>
                            </fieldset>
                            <fieldset>
                                <legend>direction="rtl"</legend>
                                <form-group label="Email" direction="rtl" description="用于验证和接收提醒">
                                    <input type="email">
                                </form-group>
                            </fieldset>
                            <fieldset>
                                <legend>direction="ttb"</legend>
                                <form-group label="Address" direction="ttb" description="用于邮寄">
                                    <input type="address">
                                </form-group>
                            </fieldset>
                        </layer-view>
                    </layer>
                </template>
            </webpdf>
        </template>
    </html>
    <style>
        .fv__ui-form-group-label {
            width: 5em;
        }
        .fv__ui-form-group {
            margin-bottom: 10px;
            color: #666;
        }
        input {
            border: 1px solid #ddd;
            margin-right: 1em;
        }
    </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: 400px"
        }
    }

### # 动态修改参数

`form-group` 组件的各项参数均可以在模板或者 js 中动态修改， 参考下面的示例：

    <html>
        <template id="example-dialog-template">
            <layer class="center" backdrop style="width: 640px" @var.comp="$component">
                <layer-header title="form-group component example"  @draggable="{type: 'parent'}"></layer-header>
                <layer-view>
                    <fieldset>
                        <legend>参数调整（模板语法）</legend>
                        <form-group label="设置签名">
                            <input @model="comp.label">
                        </form-group>
                        <form-group label="设置帮助文本">
                            <input @model="comp.description">
                        </form-group>
                        <form-group label="设置分隔符">
                            <input @model="comp.delimiter">
                        </form-group>
                        <form-group label="设置布局" tag="div">
                            <radio name="form-group-direction" @model="comp.direction" value="ltr" text="水平-靠左"></radio>
                            <radio name="form-group-direction" @model="comp.direction" value="rtl" text="水平-靠右"></radio>
                            <radio name="form-group-direction" @model="comp.direction" value="ttb" text="垂直"></radio>
                        </form-group>
                    </fieldset>
                    <fieldset>
                        <legend>参数调整（js API）</legend>
                        <button @on.click="comp.resetLabel()">重置标签文本</button>
                        <button @on.click="comp.resetDescription()">重置帮助文本</button>
                        <button @on.click="comp.resetDirection()">随机布局</button>
                    </fieldset>
                    <fieldset>
                        <legend>效果预览</legend>
                        <form-group
                            @setter.label="comp.label"
                            @setter.description="comp.description"
                            @setter.delimiter="comp.delimiter"
                            @setter.direction="comp.direction"
                            @init="comp.formGroupComponent = $component"
                        >
                            <input>
                        </form-group>
                    </fieldset>
                </layer-view>
            </layer>
        </template>
        <template id="layout-template">
            <webpdf>
                <toolbar>
                    <group-list>
                        <group name="home-tab-group-hand">
                            <hand-ribbon-button></hand-ribbon-button>
                            <open-file-ribbon-dropdown></open-file-ribbon-dropdown>
                            <download-file-ribbon-button></download-file-ribbon-button>
                        </group>
                    </group-list>
                </toolbar>
                <div class="fv__ui-body">
                    <viewer></viewer>
                </div>
                <template name="template-container">
                    <exp:example-dialog visible="true"></exp:example-dialog>
                </template>
            </webpdf>
        </template>
    </html>
    <style>
        .fv__ui-form-group {
            margin-bottom: 10px;
            color: #666;
        }
        input {
            border: 1px solid #ddd;
            margin-right: 1em;
        }
    </style>
    <script>
        class ExampleDialog extends UIExtension.SeniorComponentFactory.createSuperClass({
            template: document.getElementById('example-dialog-template').innerHTML
        })  {
            static getName() {
                return 'example-dialog'
            }
            init() {
                super.init();
                this.delimiter = ':';
                this.description = '帮助文本';
                this.label = '标签文本';
                this.direction = 'ltr';
            }
            resetLabel() {
                this.formGroupComponent.setLabel(
                    this.label = new Date().toUTCString()
                );
                this.digest();
            }
            resetDescription() {
                this.formGroupComponent.setDescription(
                    this.description = '帮助文本：' + new Date().toUTCString()
                );
                this.digest();
            }
            resetDirection() {
                this.formGroupComponent.setDirection(
                    this.direction = ['ltr', 'rtl', 'ttb'][Math.floor(Math.random() * 3)]
                );
                this.digest();
            }
        }
        UIExtension.modular.module('exp', []).registerComponent(ExampleDialog);
        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"
        }
    }

## # API

### # form-group 组件模板

    <form-group delimiter=":" direction="ltr" label="" description="">
        <input>
    </form-group>

`form-group` 各个属性描述：

属性 | 描述 | 类型 | 默认值 | 版本
--- | --- | --- | --- | ---
delimiter | 标签文本后面的分隔符号，`direction` 为 `rtl` 时无效 | `string` | `':'` | 8.5.0
direction | 标签文本和输入组件的布局方式 | `'ltr'` | `'rtl'` | `'ttb'` | `'ltr'` | 8.5.0
label | 标签文本 | `string` | `''` | 8.5.0
description | 在输入组件下方显示的帮助文本 | `string` | `''` | 8.5.0

### # 方法

`form-group` 组件上面的方法：

方法 | 描述 | 版本
--- | --- | ---
`setDelimiter(delimiter: string)` | 修改分隔符 | 8.5.0
`setDirection(direction: 'ltr'|'rtl'|'ttb')` | 修改布局方式 | 8.5.0
`setLabel(label: string)` | 修改标签文本 | 8.5.0
`setDescription(description: string)` | 修改帮助文本 | 8.5.0

### # 事件

`form-group` 组件没有定义事件。