# `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 组件没有定义事件。

← viewer 组件 inline-color-picker 组件 →