检查员控制

Inspector是一个可视化的配置工具，在Winter后台的几个地方都会用到。 Inspector 最广为人知的用法是 CMS 组件配置功能，但 Inspector 并不局限于 CMS。事实上，它是一个通用工具，可以与后端页面上的任何元素一起使用。

Inspector 从可检查元素加载配置模式，构建用户界面，并将用户输入的值写回可检查元素。 Inspector 的第一个版本只支持几种标量值类型——字符串和布尔值，没有编辑任何复杂数据的选项。

当前版本的 Inspector 允许编辑任何可以想象的数据结构，包括用户在 Inspector 界面中创建可枚举数据元素的情况。

本节介绍客户端 Inspector API，但不详细介绍 Inspector 生成的数据的后端使用情况。 Inspector 接受 JSON 格式的配置模式并生成 JSON 格式的值。提供配置和解释生成的值取决于开发人员。例如，CMS 模块使用从组件的 defineProperties() 方法返回的信息来生成配置 JSON 字符串，并将 Inspector 生成的 JSON 值转换为 CMS 模板中的组件配置。在本文档中，我们只关注 JSON 格式。

配置可检查元素

单击可检查元素会显示该元素的检查器。任何 HTML 元素都可以通过向其添加数据属性来使其可检查。必需的属性是：

Inspectable 元素还应包含 Inspector 用于读取和写入值的隐藏输入元素。输入元素应标有data-inspector-values 数据属性。

示例可检查元素标记：

<div
    data-inspectable
    data-inspector-title="Some inspectable element"
    data-inspector-description="Some description">
        <input
            data-inspector-values
            type="hidden"
            value="JSON"/>
</div>

可选数据属性

有几个可选的数据属性和特性可以在可检查元素或其周围的元素中定义：

动态配置和动态项

如果data-inspector-config 可检查元素中缺少属性 Inspector 尝试从服务器加载其配置。重要说明 - 应该有一个 FORM 元素包装可检查元素，以便使用 Inspector 的任何动态功能。

用于从服务器加载配置的 AJAX 请求名为onGetInspectorConfiguration.处理程序应在后端控制器中定义，并应返回一个数组，其中包含检查器配置（在本节后面描述的 JSON 配置结构的 PHP 等效项中）、检查器标题和描述。服务器端 AJAX 动态配置请求处理程序示例：

public function onGetInspectorConfiguration()
{
    // Load and use some values from the posted form
    //
    $someValue = Request::input('someValue');

    ... do some processing ...

    return [
        'configuration' => [
            'properties'  => [list of properties],
            'title'       => 'Inspector title',
            'description' => 'Inspector description'
        ]
    ];
}

一些 Inspector 编辑器——（下拉、设置、自动完成）支持静态和动态选项。动态选项是从服务器请求的，而不是在配置 JSON 字符串中定义的。要使用此功能，可检查元素必须具有data-inspector-class 属性定义。属性值应包含与可检查元素对应的 PHP 类的名称。

服务器端控制器应该使用Backend\Traits\InspectableContainer trait 以提供动态选项加载。可检查的 PHP 类（指定为data-inspector-class) 必须有一个方法get[Property]Options()，其中 [Property] 部分对应于动态属性的名称，或者getPropertyOptions($propertyName) 更通用并接受属性名称作为参数的方法。这些方法应该返回options 包含带键的关联数组的数组option 和value.例子：

public function getContextOptions()
{
    $optionsArray = [];

    $optionsArray[] = ['value' => 'create', 'title' => 'Create'];
    $optionsArray[] = ['value' => 'update', 'title' => 'Update'];
    $optionsArray[] = ['value' => 'delete', 'title' => 'Delete'];

    return [
        'options' => $optionsArray
    ];
}

容器和弹出窗口

默认情况下，Inspector 显示在弹出窗口中，但可以选择将其显示在页面上的容器元素中。要启用此选项，所有可检查元素都应包装到另一个元素中data-inspector-container 属性。属性值应该是指向包装内元素的 CSS 选择器。例子：

<div data-inspector-container=".inspector-container">
   <div class="inspector-container"></div>
   <div data-inspectable ... ...>
   <div data-inspectable ... ...>
</div>

单击可检查元素时，内部元素将充当检查器的宿主元素。该元素应该有inspector-container 类，可以选择标记为data-inspector-scrollable 使 Inspector 可滚动的属性。对于滚动功能，容器元素应该明确定义高度。

使用容器时，Inspector 默认仍显示在弹出窗口中，但用户可以单击 Inspector 标题中的图标将其移动到容器中。

数据架构配置

检查器配置，定义为data-inspector-config 属性或从服务器加载，应该是一个包含属性定义列表的数组。本节中的所有示例均使用 JSON 格式。下面是两个属性的配置示例：

[
    {
        "property": "firstName",
        "title": "First name",
        "type": "string"
    },
    {
        "property": "lastName",
        "title": "Last name",
        "type": "string"
    }
]

此配置创建两个标题为“名字”和“姓氏”的文本字段。当数据被保存回可检查元素（到data-inspector-values 隐藏的输入元素），它将具有以下格式：

{"firstName":"John", "lastName":"Smith"}

每个属性都应该有属性property,title 和type.这type 属性定义了应该为属性创建的编辑器类型。进一步描述支持的编辑器。

所有（或大多数）属性类型支持的其他属性是：

所有其他配置属性都特定于不同的属性类型。

字符串编辑器

字符串编辑器允许输入单行文本并用简单的输入文本字段表示。编辑器没有任何特定参数。可选的default 编辑器的参数应该包含一个字符串。

{
    "property": "firstName",
    "title": "First name",
    "type": "string",
    "default": "John"
}

编辑器生成字符串值：

{"firstName":"Sam"}

文本编辑器

文本编辑器允许在弹出窗口中输入多行长文本值。编辑器没有任何特定参数。可选的default 编辑器的参数应该包含一个字符串。

{
    "property": "description",
    "title": "Description",
    "type": "text",
    "default": "This is a default description"
}

编辑器生成字符串值：

{"description":"This is a description"}

字符串列表编辑器

允许用户输入字符串列表。编辑器在弹出窗口中打开并显示一个文本区域。每行文本代表结果数组中的一个元素。可选的default 参数应包含一个字符串数组。例子：

{
    "property": "items",
    "title": "Items"
    "type": "stringList",
    "default": ["String 1", "String 2"]
}

编辑器生成的值是一个字符串数组，例如：

{"items":["String 1","String 2","String 3"]}

自动完成编辑器

该编辑器的工作方式类似于string 编辑器，但包括自动完成功能。可以静态指定自动完成选项，使用items 参数或动态加载。带有静态选项的示例：

{
    "property": "condition",
    "title": "Condition"
    "type": "autocomplete",
    "items": {"start": "Start", "end": "End"}
}

这些项目被指定为键值对象。这items 参数是可选的，如果没有提供，项目将从服务器加载 - 请参阅动态配置和动态项 上面的部分。

编辑器生成的值是字符串。例子：

{"condition":"start"}

这种类型的字段不支持外部属性编辑器。

复选框编辑器

这种类型的属性在 Inspector UI 中用复选框表示。此属性没有任何特殊参数。这default 参数，如果指定，应包含布尔值或字符串值“true”、“false”、“1”、“0”。例子：

{
    "property": "enabled",
    "title": "Enabled",
    "type": "checkbox",
    "default": true
}

编辑器生成的值为 0（未选中）或 1（选中）。例子：

{"enabled":1}

下拉编辑器

显示下拉列表。可以使用静态指定下拉列表的选项options 属性或从服务器动态加载。例子：

{
    "property": "action",
    "title": "Action",
    "type": "dropdown",
    "options": {
        "show": "Show",
        "hide": "Hide",
        "enable": "Enable",
        "disable": "Disable",
        "empty": "Empty"
    }
}

这options 属性应该是一个键值对象。如果未指定该属性，Inspector 将尝试从服务器加载选项 - 请参阅动态配置和动态项 上面的部分。

编辑器生成对应于所选选项的字符串值，例如：

{"action":"hide"}

词典编辑器

字典编辑器允许使用一个简单的用户界面创建键值对，该界面由一个包含两列的表格组成。这default 参数，如果指定，应该包含一个键值对象。例子：

{
    "property": "options",
    "title": "Options",
    "type": "dictionary",
    "default": {"option1": "Option 1"}
}

编辑器生成一个对象值，例如：

{"options":{"option1":"Option 1","option2":"Option 2"}}

词典编辑器支持对整个集合的验证（required 和length 验证器）和键和值分开。见验证说明 进一步在本文档中。这validationKey 和validationValue 定义键和值的验证，例如：

{
    "property": "options",
    "title": "Options",
    "type": "dictionary",
    "validation": {
        "required": {
            "message": "Please create options"
        },
        "length": {
            "min": {
                "value": 2,
                "message": "Create at least two options."
            }
        }
    },
    "validationKey": {
        "regex": {
            "pattern": "^[a-z]+$",
            "message": "Keys can contain only lowercase Latin letters"
        }
    },
    "validationValue": {
        "regex": {
            "pattern": "^[a-zA-Z0-9]+$",
            "message": "Values can contain only Latin letters and digits"
        }
    }
}

对象编辑器

允许定义具有用户可编辑的特定属性的对象。对象属性用properties 属性。该属性的值是一个数组，其结构与 Inspector 属性数组完全相同。

{
    "property": "address",
    "title": "Address",
    "type": "object",
    "properties": [
        {
            "property": "streetAddress",
            "title": "Street address",
            "type": "string"
        },
        {
            "property": "city",
            "title": "City",
            "type": "string"
        },
        {
            "property": "country",
            "title": "Country",
            "type": "dropdown",
            "options": {"us": "US", "ca": "Canada"}
        }
    ]
}

上面的示例创建了一个具有三个属性的对象。其中两个显示为文本字段，第三个显示为下拉列表。

对象编辑器值是对象。例子：

{
    "address": {
        "streetAddress":"321-210 Second ave",
        "city":"Springfield",
        "country":"us"
    }
}

对象属性可以是 Inspector 支持的任何类型，包括其他对象。

如果其中一个对象字段为空，则有一种方法可以从 Inspector 值中完全排除对象。该字段标识为ignoreIfPropertyEmpty 范围。例如：

{
    "property": "address",
    "title": "Address",
    "type": "object",
    "ignoreIfPropertyEmpty": "title",
    "properties": [
        {
            "property": "streetAddress",
            "title": "Street address",
            "type": "string"
        },
        {
            "property": "city",
            "title": "City",
            "type": "string"
        }
    ]
}

在上面的示例中，如果未指定街道地址，则对象（“地址”）将从 Inspector 输出中完全删除。如果在其他对象属性上定义了任何验证规则并且 required 属性为空，则这些规则将被忽略。

Adefault 编辑器的值（如果指定）应该是一个具有与定义在properties 配置参数。

对象编辑器不支持外部属性编辑器功能。

对象列表编辑器

对象列表编辑器允许用户创建具有预定义结构的多个对象。例如，它可用于创建人员列表，其中每个人都有姓名和地址。

可以使用编辑器创建的对象的属性定义为itemProperties 范围。该参数应包含一个属性数组，类似于 Inspector 配置数组。另一个必需的参数是titleProperty，它标识应在 Inspector UI 中用作标题的属性。示例配置：

{
    "property": "people",
    "title": "People",
    "type": "objectList",
    "titleProperty": "fullName",
    "itemProperties": [
        {
            "property": "fullName",
            "title": "Full name",
            "type": "string"
        },
        {
            "property": "address",
            "title": "Address",
            "type": "string"
        }
    ]
}

定义的属性数组itemProperties 支持所有属性类型。

对象列表编辑器类型不支持默认值。

默认情况下，这种类型的编辑器创建的值是一个非关联数组：

{
    "people":[
        {"fullName":"John Smith","address":"Palo Alto"},
        {"fullName":"Bart Simpson","address":"Springfield"}
     ]
}

如果结果值应该是一个关联数组（对象），使用keyProperty 配置选项。选项值应引用应用作键的属性。 key 属性只能使用字符串或下拉编辑器，它的值应该是唯一的，不能为空。例子：

{
    "property": "people",
    "title": "People",
    "type": "objectList",
    "titleProperty": "fullName",
    "keyProperty": "login",
    "itemProperties": [
        {
            "property": "fullName",
            "title": "Full name",
            "type": "string"
        },
        {
            "property": "login",
            "title": "Login",
            "type": "string"
        },
        {
            "property": "address",
            "title": "Address",
            "type": "string"
        }
    ]
}

这login 上例中的属性将用作结果值中的键：

{
    "people":{
        "john":{"fullName":"John Smith","address":"Palo Alto"},
        "bart":{"fullName":"Bart Simpson","address":"Springfield"}
    }
}

集编辑器

集合编辑器允许用户使用复选框选择多个预定义选项。可以使用配置静态指定设置项，使用items 参数，或动态加载。静态项目定义示例：

{
    "property": "context",
    "title": "Context",
    "type": "set",
    "items": {
        "create": "Create",
        "update": "Update",
        "preview": "Preview"
    },
    "default": ["create", "update"]
}

这items 属性应该是一个键值对象。如果未指定该属性，Inspector 将尝试从服务器加载选项 - 请参阅动态配置和动态项 上面的部分。

这default 参数，如果指定，应该是一个数组，列出默认选择的项目键。

集编辑器不支持外部属性编辑器功能。

定义验证规则

Inspector 支持多种可应用于属性的验证规则。验证规则可以应用于顶级属性以及对象和对象列表编辑器的内部属性定义。有两种定义验证规则的方法——旧语法和新语法。

支持旧语法以实现与现有 CMS 组件定义的向后兼容性。此语法将始终受到支持，但它是有限的，并且不能与新语法混合使用。遗留语法示例：

{
    "property": "name",
    "title": "Name",
    "type": "string",
    "required": true,
    "validationPattern": "^[a-zA-Z]+$"
    "validationMessage": "The Name field is required and can contain only Latin letters.",
}

遗留语法仅支持两个验证规则 - 必需和正则表达式。新语法更加灵活和可扩展：

{
    "property": "name",
    "title": "Name",
    "type": "string",
    "validation": {
        "required": {
            "message": "The Name field is required"
        },
        "regex": {
            "message": "The Name field can contain only Latin letters.",
            "pattern": "^[a-zA-Z]+$"
        }
    }
}

中的关键值validation 对象指的是验证器（见下文）。验证器配置有对象，其属性取决于验证器。一处房产——message 对所有验证器都是通用的。

必需的验证器

检查值是否不为空。验证器可以与任何编辑器一起使用，包括复杂的编辑器（集合、字典、对象列表等）。例子：

{
    "property": "name",
    "title": "Name",
    "type": "string",
    "validation": {
        "required": {
            "message": "The Name field is required"
        }
    }
}

正则表达式验证器

使用正则表达式验证字符串值。验证器只能与字符串类型的编辑器一起使用。例子：

{
    "property": "name",
    "title": "Name",
    "type": "string",
    "validation": {
        "regex": {
            "message": "The Name field can contain only Latin letters",
            "pattern": "^[a-z]+$",
            "modifiers": "i"
        }
    }
}

正则表达式指定了所需的pattern 范围。这modifiers 参数是可选的，可用于设置正则表达式修饰符。

整数验证器

检查该值是否为整数，并且可以选择验证该值是否在特定间隔内。验证器只能与字符串类型的编辑器一起使用。例子：

{
    "property": "numOfColumns",
    "title": "Number of Columns",
    "type": "string",
    "validation": {
        "integer": {
            "message": "The Number of Columns field should contain an integer value",
            "allowNegative": true,
            "min": {
                "value": -10,
                "message": "The number of columns should not be less than -10."
            },
            "max": {
                "value": 10,
                "message": "The number of columns should not be greater than 10."
            }
        }
    }
}

支持的参数：

浮动验证器

检查该值是否为浮点数。该验证器的参数与integer 上面描述的验证器。例子：

{
    "property": "amount",
    "title": "Amount",
    "type": "string",
    "validation": {
        "float": {
            "message": "The Amount field should contain a positive floating point value."
        }
    }
}

有效的浮点数格式：

长度验证器

检查字符串、数组或对象是否不短于或长于指定值。此验证器可以与字符串、文本、集合、字符串列表、字典和对象列表编辑器一起使用。在多值编辑器（集合、字符串列表、字典和对象列表）中，它验证在编辑器中创建的项目数。

Note： 这length 验证器不验证空值。例如，如果它应用于集合编辑器，并且集合为空，则无论min 和max 参数值。使用required 验证器连同length 验证器以确保在应用长度验证之前该值不为空。

{
    "property": "name",
    "title": "Name",
    "type": "string",
    "validation": {
        "length": {
            "min": {
                "value": 2,
                "message": "The name should not be shorter than two letters."
            },
            "max": {
                "value": 10,
                "message": "name should not be longer than 10 letters."
            }
        }
    }
}

支持的参数：

检查员事件

Inspector 在可检查元素上触发多个事件。

change

这change 在 Inspector 将更新的值应用于可检查元素后触发事件。仅当用户在 Inspector UI 中更改值时才会触发该事件。

showing.oc.inspector

这showing.oc.inspector 在显示 Inspector 之前触发事件。事件处理程序可以选择通过调用停止进程ev.isDefaultPrevented().示例 - 防止 Inspector 显示：

$(document).on('showing.oc.inspector', 'div[data-inspectable]', function(ev, data){
    ev.preventDefault()
})

处理程序可以执行任何所需的处理，甚至是异步处理，然后调用传递给处理程序的回调函数，以继续显示检查器。在这种情况下，处理程序应该调用ev.stopPropagation() 方法来停止默认的 Inspector 初始化。示例 - 经过一些处理后继续显示：

$(document).on('showing.oc.inspector', 'div[data-inspectable]', function(ev, data){
    ev.stopPropagation()
    // The callback function can be called asynchronously
    data.callback()
})

hiding.oc.inspector

这hiding.oc.inspector 在 Inspector 隐藏过程开始之前被调用。处理程序可以通过调用停止隐藏ev.preventDefault().例子：

$(document).on('hiding.oc.inspector', 'div[data-inspectable]', function(ev, data){
    if (!confirm('Allow hiding?')) {
        ev.preventDefault()
    }
})

Inspector 中输入的值可通过values 第二个处理程序参数的元素：

$(document).on('hiding.oc.inspector', 'div[data-inspectable]', function(ev, data){
   console.log(data.values)
})

hidden.oc.inspector

这hidden.oc.inspector 在 Inspector 隐藏后触发。

豫ICP备18041297号-2
Please enter a query in order to search.