v1.x版本升级指南
<h1>v1.x版本升级指南</h1>
<h3>前言</h3>
<p>本章节内容只包含 <code>1.x</code> 版本中 <code>API</code> 改动的部分，不包含新增特性或对用户使用无影响的改动说明， <code>2.0</code> 的具体版本变化说明请参考 <a href="https://learnku.com/articles/50781?#reply164307">2.0有哪些变化？</a></p>
<p><strong>预计升级时间：60 分钟</strong></p>
<h3>1.创建新分支，备份配置文件</h3>
<p>创建一个新的分支，然后备份配置文件 <code>config/admin.php</code> 命名为 <code>config/admin.bak.php</code>，方便后续对比配置变动。</p>
<h3>2.更新composer依赖</h3>
<p>先卸载 <code>1.x</code> 版本</p>
<pre><code class="language-bash">composer remove dcat/laravel-admin</code></pre>
<p>再安装</p>
<pre><code>composer require dcat/laravel-admin:&quot;2.*&quot;</code></pre>
<p>安装成功后</p>
<ol>
<li>删除 <code>public/vendors</code> 目录</li>
<li>重新发布资源 <code>php artisan admin:publish --force</code></li>
<li>根据上面备份后的配置文件，把修改过的参数写到新的配置文件 <code>config/admin.php</code> 中，这里需要注意的是<code>1.x</code>的默认主题色是<code>indigo</code>（已被废弃），在新版本中已经替换成<code>default</code>了</li>
<li>调整语言包，新版本中语言包目录由 <code>zh-CN</code> 变成了 <code>zh_CN</code>，需要把自定义的翻译文件移动到新目录，并且 <code>菜单标题</code> 的翻译也独立出来到 <code>menus.php</code> 中了</li>
<li>运行数据库迁移命令命令 <code>php artisan migrate</code> ，新版本中新增了两个表<code>admin_settings</code> 以及 <code>admin_extensions</code></li>
</ol>
<h3>3.全局更改命名空间</h3>
<ol>
<li>全局搜索命名空间 <code>Dcat\Admin\Controllers</code> 并替换为 <code>Dcat\Admin\Http\Controllers</code></li>
<li>全局搜索命名空间 <code>Dcat\Admin\Auth</code> 并替换为 <code>Dcat\Admin\Http\Auth</code></li>
</ol>
<h3>4.表格部分变动</h3>
<p>1.字段隐藏功能调整，旧版本 <code>responsive</code> 方法已废弃，在新版本中开启字段隐藏功能方法如下</p>
<pre><code class="language-php">// 开启字段选择器功能
$grid-&gt;showColumnSelector();
// 设置默认隐藏字段
$grid-&gt;hideColumns(['field1', ...]);</code></pre>
<p>2.表格 <code>collection</code>、<code>fetching</code> 等方法已被移除，在新版本中可以通过下面的事件代替</p>
<pre><code class="language-php">use Dcat\Admin\Grid;
use Illuminate\Support\Collection;
// 使用 Grid\Events\Fetched 事件代替 collection
$grid-&gt;listen(Grid\Events\Fetched::class, function ($grid, Collection $rows) {
$rows-&gt;transform(function ($row) {
// 更改行数据
$row['name'] = $row['first_name'].' '.$row['last_name'];
return $row;
});
});
// 使用 Grid\Events\Fetching 事件代替 fetching
$grid-&gt;listen(Grid\Events\Fetching::class, function ($grid) {
});</code></pre>
<p>3.表格行相关闭包中允许使用模型</p>
<pre><code class="language-php">$grid-&gt;column('avatar')-&gt;display(function ({
// 可直接访问模型相关方法
return $this-&gt;getAvatar();
});</code></pre>
<p>4.设置路由前缀方法由 <code>resource</code> 调整为 <code>setResource</code> </p>
<pre><code class="language-php">$grid-&gt;setResource('auth/users');</code></pre>
<p>5.树形表格 <code>tree</code> 方法即将被废弃，将会移动到扩展中心</p>
<h3>5.表单部分变动</h3>
<p>1.调整表单处理响应方法，旧版本中的<code>success</code>、<code>error</code>、<code>redirect</code> 以及 <code>location</code> 方法已被移除，
在 <code>2.0</code> 中我们让表单的响应方法和 <code>action</code> 的响应方法统一了起来，详细用法请参考文档 <a href="response.md">动作和表单响应</a>，示例</p>
<pre><code class="language-php">$form-&gt;saving(function (Form $form) {
return $form
-&gt;response()
-&gt;success('保存成功')
-&gt;script('console.log(&quot;执行JS代码&quot;)')
-&gt;redirect('auth/users');
});</code></pre>
<p>如果是在<a href="widgets-form.md">工具表单</a>中，用法如下</p>
<pre><code class="language-php">public function handle(array $input)
{
...
return $this
-&gt;response()
-&gt;alert()
-&gt;success('成功')
-&gt;detail('详细内容');
}</code></pre>
<p>2.调整表单 <code>block</code> 布局功能，并废弃 <code>setDefaultBlockWidth</code> 方法，详细用法请参考文档 <a href="model-form-layout.md">表单block布局</a>，示例</p>
<pre><code class="language-php">$form-&gt;block(8, function (Form\BlockForm $form) {
$form-&gt;title('基本设置');
$form-&gt;showFooter();
$form-&gt;width(9, 2);
$form-&gt;column(6, function (Form\BlockForm $form) {
$form-&gt;display('id');
$form-&gt;text('name');
$form-&gt;email('email');
$form-&gt;image('avatar');
$form-&gt;password('password');
});
$form-&gt;column(6, function (Form\BlockForm $form) {
$form-&gt;text('username');
$form-&gt;email('mobile');
$form-&gt;textarea('description');
});
});
$form-&gt;block(4, function (Form\BlockForm $form) {
$form-&gt;title('分块2');
$form-&gt;text('nickname');
$form-&gt;number('age');
$form-&gt;radio('status')-&gt;options(['1' =&gt; '默认', 2 =&gt; '冻结'])-&gt;default(1);
$form-&gt;next(function (Form\BlockForm $form) {
$form-&gt;title('分块3');
$form-&gt;date('birthday');
$form-&gt;date('created_at');
});
});</code></pre>
<p>3.废弃表单直接提交，只保留 <code>ajax</code> 提交的方式，并重命名 <code>disableAjaxSubmit</code> 方法为 <code>ajax</code></p>
<pre><code class="language-php">$form-&gt;ajax(false);</code></pre>
<p>4.废弃分步表单，新版本请使用<a href="https://github.com/dcat-admin/form-step">分步表单扩展</a>代替</p>
<p>6.<code>map</code>以及<code>listbox</code>、<code>slider</code>也即将废弃，并移动扩展中心</p>
<p>7.表单字段扩展功能变动，具体请参考文档<a href="model-form-field-management.md">表单字段扩展</a>章节</p>
<h3>6.数据仓库部分变动</h3>
<p>1.数据仓库的接口命名做了简化处理，新的 interface 如下</p>
<pre><code class="language-php">interface Repository
{
/**
* 获取主键名称.
*
* @return string
*/
public function getKeyName();
/**
* 获取创建时间字段.
*
* @return string
*/
public function getCreatedAtColumn();
/**
* 获取更新时间字段.
*
* @return string
*/
public function getUpdatedAtColumn();
/**
* 是否使用软删除.
*
* @return bool
*/
public function isSoftDeletes();
/**
* 获取Grid表格数据.
*
* @param Grid\Model $model
*
* @return \Illuminate\Contracts\Pagination\LengthAwarePaginator|Collection|array
*/
public function get(Grid\Model $model);
/**
* 获取编辑页面数据.
*
* @param Form $form
*
* @return array|\Illuminate\Contracts\Support\Arrayable
*/
public function edit(Form $form);
/**
* 获取详情页面数据.
*
* @param Show $show
*
* @return array|\Illuminate\Contracts\Support\Arrayable
*/
public function detail(Show $show);
/**
* 新增记录.
*
* @param Form $form
*
* @return mixed
*/
public function store(Form $form);
/**
* 查询更新前的行数据.
*
* @param Form $form
*
* @return array|\Illuminate\Contracts\Support\Arrayable
*/
public function updating(Form $form);
/**
* 更新数据.
*
* @param Form $form
*
* @return bool
*/
public function update(Form $form);
/**
* 删除数据.
*
* @param Form $form
* @param array $deletingData
*
* @return mixed
*/
public function delete(Form $form, array $deletingData);
/**
* 查询删除前的行数据.
*
* @param Form $form
*
* @return array|\Illuminate\Contracts\Support\Arrayable
*/
public function deleting(Form $form);
}</code></pre>
<p>2.<code>EloquentRepository::eloquent()</code> 重命名为 <code>EloquentRepository::model()</code></p>
<h3>7.Section变动</h3>
<p>在新版本中 <code>AdminSection</code> 已被移除，请使用 <code>Dcat\Admin\Admin::SECTION</code> 常量代替</p>
<pre><code class="language-php">use Dcat\Admin\Admin;
admin_inject_default_section(Admin::SECTION['HEAD'], function () {
return ...;
});</code></pre>
<h3>8.扩展</h3>
<p>扩展相关变动请参考文档<a href="extension-f.md">扩展</a></p>
<h3>9.登录逻辑</h3>
<p>1.登录模板，如果你在旧项目中自定义过登录模板，则需要调整登录模板中的<code>JS</code>代码</p>
<pre><code class="language-js">Dcat.ready(function () {
// ajax表单提交
$('#login-form').form({
validate: true,
});
});</code></pre>
<p>2.登录逻辑，如果重写过登录逻辑，则最后登录成功的响应方法需要使用 <code>sendLoginResponse</code></p>
<h3>10.其他变动</h3>
<p>1.资源注册</p>
<pre><code class="language-php">use Dcat\Admin\Admin;
// 注册资源路径别名
Admin::asset()-&gt;alias('test', 'assets/test');
Admin::asset()-&gt;alias('名称', [
'js' =&gt; [
// @test 会判定为别名
'@test/test.js',
],
'css' =&gt; [
'@test/test.css',
],
]);
// 加载资源
Admin::asset()-&gt;require('@名称');
// 仅加载 js
Admin::js('@名称');
// 仅加载 css
Admin::css('@名称');</code></pre>