README

为Yii 2提供的JSON编辑器小部件。
此小部件使用了JSON编辑器josdejong/jsoneditor。

需求

• PHP 5.4或更高版本或HHVM 3；
• Yii框架2。

安装

通过Composer安装此扩展是首选方法。

安装，运行以下命令之一：

php composer.phar require kdn/yii2-json-editor "*"

或

"kdn/yii2-json-editor": "*"

将其添加到您的composer.json文件的require部分。

用法

最小示例

<?php

use kdn\yii2\JsonEditor;

echo JsonEditor::widget(['name' => 'editor', 'value' => '{"foo": "bar"}']);

或者您也可以传递已解码的JSON

<?php

use kdn\yii2\JsonEditor;

echo JsonEditor::widget(['name' => 'editor', 'decodedValue' => ['foo' => 'bar']]);

带有一些选项

echo JsonEditor::widget(
    [
        // JSON editor options
        'clientOptions' => [
            'modes' => ['code', 'form', 'preview', 'text', 'tree', 'view'], // all available modes
            'mode' => 'tree', // default mode
            'onModeChange' => 'function (newMode, oldMode) {
                console.log(this, newMode, oldMode);
            }',
        ],
        'collapseAll' => ['view'], // collapse all fields in "view" mode
        'containerOptions' => ['class' => 'container'], // HTML options for JSON editor container tag
        'expandAll' => ['tree', 'form'], // expand all fields in "tree" and "form" modes
        'name' => 'editor', // hidden input name
        'options' => ['id' => 'data'], // HTML options for hidden input
        'value' => '{"foo": "bar"}', // JSON which should be shown in editor
    ]
);

与ActiveForm和ActiveRecord一起使用

echo $form->field($model, 'data')->widget(
    JsonEditor::class,
    [
        'clientOptions' => ['modes' => ['code', 'tree']],
        'decodedValue' => $model->data, /* if attribute contains already decoded JSON,
        then you should pass it as shown, otherwise omit this line */
    ]
);

要获取客户端上JSON编辑器的实例，您可以使用以下JavaScript

var jsonEditor = window[$('#YOUR-HIDDEN-INPUT-ID').data('json-editor-name')];
jsonEditor.set({"foo": "bar"});

如何为隐藏输入设置id

echo JsonEditor::widget(
    [
        'name' => 'editor',
        'options' => ['id' => 'YOUR-HIDDEN-INPUT-ID'],
        'value' => '{}'
    ]
);

传递数据的所有可能方式及其优先级

$model->data = '{"precedence": 5}';
echo $form->field(
    $model,
    'data',
    ['inputOptions' => ['value' => '{"precedence": 4}']]
)->widget(
    JsonEditor::class,
    [
        'decodedValue' => ['precedence' => 1],
        'value' => '{"precedence": 2}',
        'options' => ['value' => '{"precedence": 3}'],
        'defaultValue' => '{"precedence": 6}',
    ]
);

对于上面的代码，小部件将显示{"precedence": 1}。
如果未设置decodedValue，则小部件将显示{"precedence": 2}等。

请查看类JsonEditor中的公共属性以获取有关所有可用选项的信息，它们得到了全面的文档。

测试

确保您已安装所有Composer依赖项（在存储库的基本目录中运行composer update）。在存储库的基本目录中运行PHPUnit。

./vendor/bin/phpunit

使用Docker进行测试

需求

• Docker >= 19.03.0 (安装)；
• Docker Compose >= 1.25.5 (安装)；
• Docker插件
  • buildx (安装)。

启动并运行

1. 为Composer提供凭据

   cp auth.json.example \
       auth.json

   我建议在auth.json中设置GitHub OAuth令牌（也称为个人访问令牌），但是如果您对安全性有疑虑，或者您懒得生成令牌，则可以替换auth.json的内容为{}，在大多数情况下这将有效。

2. 为服务构建镜像

   docker buildx bake --load --pull

   或

   docker buildx bake --load --pull --no-cache --progress plain

   查看docker buildx bake --help以获取详细信息。

3. 以后台模式启动服务

   docker-compose up --detach 8.1

   此命令将使用PHP 8.1启动服务。还允许使用7.4、5.6、8.1-alpine、7.4-alpine和5.6-alpine，请参阅在docker-compose.yml中定义的服务。

4. 在运行的容器中执行测试

   docker-compose exec 8.1 ./vendor/bin/phpunit

   或者您也可以在运行的容器中启动一个shell并从中执行测试

   docker-compose exec 8.1 sh
   $ ./vendor/bin/phpunit

5. 停止并删除由up创建的容器

   docker-compose down

   您可能希望与容器一起删除卷

   docker-compose down --volumes

向后兼容性保证

yii2-json-editor使用Semver。这意味着版本带有MAJOR.MINOR.PATCH标签。只有新的主要版本才会允许破坏向后兼容性（BC）。

PHP 8引入了命名参数，这增加了包维护者的成本并降低了灵活性。yii2-json-editor中方法参数的名称不包括在我们的向后兼容性保证中。