扩展基本使用
<h1>扩展基本使用</h1>
<h2>基本使用</h2>
<h3>设置扩展相关目录读写权限</h3>
<p>在使用扩展功能之前，需要先保证所在用户拥有扩展相关目录的读写权限，否则可能造成扩展安装失败，请保证拥有以下几个目录的读写权限</p>
<ol>
<li><code>项目目录/dcat-admin-extensions</code> 扩展的安装目录，可以根据配置参数 <code>admin.extensions.dir</code> 进行更改</li>
<li><code>public/vendor</code> 扩展静态资源发布目录</li>
<li><code>resources/lang</code> 语言包目录</li>
</ol>
<h3>扩展安装</h3>
<p><code>Dcat Admin</code>中扩展支持以下三种安装方式，安装成功后均能在扩展管理页面<code>admin/auth/extensions</code>看到相关扩展信息</p>
<h4>1.通过应用市场安装</h4>
<p>敬请期待...</p>
<h4>2.本地安装</h4>
<p>下载扩展的<code>zip</code>压缩包，注意必须是<code>zip</code>格式，然后打开扩展管理页面<code>admin/auth/extensions</code>，然后点击表格工具栏的<code>本地安装</code>按钮上传提交即可。</p>
<h4>3.composer安装</h4>
<p>根据扩展开发者文档提供的说明，直接使用composer安装即可</p>
<pre><code class="language-bash">composer require {扩展名称}</code></pre>
<h4>启用扩展</h4>
<p>安装之后，需要在扩展管理页面点击 <code>更新至xxx版本</code> 以及更新 <code>启用</code> 按钮之后方可正常使用</p>
<h2>开发扩展</h2>
<p>详细的开发教程，请参考文档 <a href="extension-dev.md">开发扩展</a> 章节。</p>
<p><a name="service"></a></p>
<h3>服务注册与初始化</h3>
<p>> {tip} 如果你对服务提供者的概念并不熟悉，请先前往<a href="https://learnku.com/docs/laravel/8.x/providers/9362">Laravel文档 - 服务提供者</a>学习。</p>
<p>扩展的 <code>ServiceProvider</code> 类实际上是一个<a href="https://learnku.com/docs/laravel/8.x/providers/9362">服务提供者</a>，唯一的区别是扩展的 <code>ServiceProvider</code> 不能重写 <code>boot</code> 方法，需要通过 <code>init</code> 代替 <code>boot</code>方法。</p>
<p><a name="version"></a></p>
<h3>版本管理</h3>
<p>每个扩展都有一个<code>version.php</code>文件，通过这个文件可以实现版本管理功能，每次发布新版本我们只需要往这个文件添加新的版本号以及相关描述即可</p>
<pre><code class="language-php">&lt;?php
return [
// key 是版本号，注意这里不要带 v 前缀！
'1.0.0' =&gt; [
'版本描述信息，可以有多条',
'描述2...',
'create_operation_log.php', // 版本迁移文件，可以有多条
],
'1.0.1' =&gt; [
'版本描述信息，可以有多条',
'update_operation_log.php', // 版本迁移文件
],
...
];</code></pre>
<h4>升级版本</h4>
<p>安装了新的版本代码之后，可以在扩展管理页面<code>admin/auth/extensions</code>中点击更新按钮进行升级。</p>
<p>点击升级后如果有迁移文件则会运行迁移文件，如果有菜单则会重新创建菜单，如果有静态资源则会自动重新发布资源文件。</p>
<h4>回滚版本</h4>
<p>通过命令 <code>php artisan admin:ext-rollback {扩展名称} {版本号}</code> 可以回滚到指定版本，但需要注意的是，回滚扩展会删除数据，可能会导致数据丢失，请谨慎操作！！！</p>
<h4>卸载</h4>
<p>如果你的扩展已安装，通过扩展页面 <code>admin/auth/extensions</code> 可以扩展进行卸载，但需要注意的是，卸载扩展会删除数据，可能会导致数据丢失，请谨慎操作！！！</p>
<p>如果你想完全移除扩展的代码，则直接删除 <code>dcat-admin-extensions</code> 目录下对应的扩展文件夹即可。</p>
<p><a name="view"></a></p>
<h3>视图 (view)</h3>
<p>视图的默认目录为<code>扩展目录/resources/view</code></p>
<pre><code class="language-bash">├── resources
│ ├── ...
│ └── views # 视图目录
│ └── index.blade.php # 视图示例文件</code></pre>
<p>只要把视图文件放在上述目录，系统就会自动给视图目录注册别名，别名与扩展名称相同。假设你的扩展包名称为 <code>dcat-admin/form-step</code>，则可以通过以下方式加载视图</p>
<pre><code class="language-php">return view('dcat-admin.form-step::index');</code></pre>
<p><a name="assets"></a></p>
<h3>静态资源</h3>
<p>假设你的扩展包名称为 <code>dcat-admin/form-step</code>，如果你的扩展中包含静态资源如下，那么你可以通过 <code>FormStepServiceProvider</code> 上的 <code>$js</code> 和 <code>$css</code> 属性为你的静态资源注册别名</p>
<pre><code class="language-php">└── resources
└─── assets
├── css
│ └── index.css
└── js
└── index.js</code></pre>
<pre><code class="language-php">class FormStepServiceProvider extends ServiceProvider
{
protected $js = [
'js/index.js',
];
protected $css = [
'css/index.css',
];
}</code></pre>
<p>然后就可以通过下面的方法加载静态资源</p>
<pre><code class="language-php">use Dcat\Admin\Admin;
// 直接用你的 包名 即可引入扩展包的静态资源
Admin::requireAssets('@dcat-admin.form-step');</code></pre>
<p>当然你也可以不通过 <code>$js</code> 和 <code>$css</code> 属性注册别名，那么也可以用下面的方法直接加载静态资源，效果是一样的</p>
<pre><code class="language-php">// 上面的写法相当于
Admin::js(['@dcat-admin.form-step/js/index.js']);
Admin::css(['@dcat-admin.form-step/css/index.css']);</code></pre>