README

Laravel的用户界面框架。由TailwindCSS提供支持。

先决条件

由于此包依赖于一些第三方包，您需要在项目中安装和配置以下内容

安装

使用composer要求：composer require arkecosystem/ui
使用php artisan vendor:publish --provider="ARKEcosystem\UserInterface\UserInterfaceServiceProvider" --tag="css" --tag="fonts" --force发布所有资产/视图。如果您需要自定义分页，请运行php artisan vendor:publish --provider="ARKEcosystem\UserInterface\UserInterfaceServiceProvider" --tag="pagination"
在您的app.css文件中导入供应商CSS资产
在您的自定义tailwind配置中导入供应商tailwind.config.js文件，并根据需要在此之上进行更改
使用<x-ark-component>在项目中使用组件
将以下片段添加到您的webpack.mix.js文件中，以便能够使用@ui别名

mix.webpackConfig({
        resolve: {
            alias: {
                '@ui': path.resolve(__dirname, 'vendor/arkecosystem/ui/resources/assets/')
            }
        }
    })
    ...

小贴士：您可以将以下内容添加到composer.json中的post-autoload-dump属性，而不是手动运行步骤3

"post-autoload-dump": [
    "Illuminate\\Foundation\\ComposerScripts::postAutoloadDump",
    "@php artisan package:discover --ansi",
    "@php artisan vendor:publish --provider=\"ARKEcosystem\\UserInterface\\UserInterfaceServiceProvider\" --tag=\"css\" --tag=\"fonts\""
],

小贴士：您可以通过使用它们的标签来发布单个资产，例如--tag="css"，--tag="images"等

小贴士2：为了懒加载图标，您需要使用它们的标签来发布它们，例如--tag="icons"

导航栏/头像组件

导航栏使用我们自己的PHP实现picasso来生成默认头像（与桌面钱包保持一致）。您需要在项目中按照以下方式设置此功能

将$identifier值传递给导航栏组件，用作图像生成的种子

剪贴板

将剪贴板添加到Laravel Mix配置中

.copy('vendor/arkecosystem/ui/resources/assets/js/clipboard.js', 'public/js/clipboard.js')

将剪贴板添加到任何需要它的页面

@push('scripts')
    <script src="{{ mix('js/clipboard.js')}}"></script>
@endpush

安装tippy.js

yarn add tippy.js

将以下片段添加到您的resources/app.js

window.initClipboard = () => {
    tippy('.clipboard', {
        trigger: 'click',
        content: (reference) => reference.getAttribute('tooltip-content'),
        onShow(instance) {
            setTimeout(() => {
                instance.hide();
            }, 3000);
        },
    });
}

模态框

安装body-scroll-lock

yarn add body-scroll-lock

在您的resources/js/app.js文件中导入模态脚本

import Modal from "@ui/js/modal";

window.Modal = Modal;

所见即所得Markdown编辑器

安装npm依赖项

yarn add @toast-ui/editor@^2.5.2 codemirror@^5.62.0

请确保在模板的<head>标签内部导入markdown脚本。

@push('scripts')
    <x-ark-pages-includes-markdown-scripts />
@endpush

现在，将到window对象的赋值是在markdown脚本中完成的，因此不需要手动导入和分配此脚本！

使用markdown插件配置webpack.mix

// Import the following script in the `webpack.mix.js` file
require('./vendor/arkecosystem/ui/laravel-mix/markdownPlugin.js');

// If the Tailwind Config file in your project is `tailwind.config.js`
// you dont need to pass any argument
mix.markdown('tailwind.app.config.js')

将markdown组件添加到您的表单中

<x-ark-markdown name="about" />

您可以更改高度和工具栏预设

<x-ark-markdown name="about"
    height="300px"
    toolbar="full"
/>

您可以选择限制要插入的字符

<x-ark-markdown name="about"
    chars-limit="1000"
/>

所有插件接受 full，仅文本相关按钮接受 basic。

如果您使用图像上传插件，您的页面需要将 csrf_token 放入元数据中。

<meta name="csrf-token" content="{{ csrf_token() }}">

标签输入

添加 taggle 依赖 yarn add taggle 并确保将脚本复制到公共目录

// webpack.mix.js file
    mix.copy('node_modules/taggle/dist/taggle.min.js', 'public/js/taggle.js')

将 Tags 脚本添加到主 js 文件

import Tags from "@ui/js/tags";

window.Tags = Tags;

确保导入 taggle 脚本

@push('scripts')
    <script src="{{ mix('js/taggle.js')}}"></script>
@endpush

像其他组件一样使用该组件。它接受 tags 和 allowed-tags 属性。

<x-ark-tags :tags="['tag1', 'tag2']" name="tags" :allowed-tags="['taga', 'tagb']" />

用户标签输入

添加 tributejs 依赖 yarn add tributejs 并确保将脚本复制到公共目录

// webpack.mix.js file
    mix.copy('node_modules/tributejs/dist/tribute.min.js', 'public/js/tribute.js')

将用户标签脚本导入主 js 文件并将样式导入您的 css 文件

import "@ui/js/user-tagger.js";

@import "../../vendor/arkecosystem/ui/resources/assets/css/_user_tagger.css";

确保在组件将使用的地方导入 tributejs 脚本

@push('scripts')
    <script src="{{ mix('js/tribute.js')}}"></script>
@endpush

像使用 textarea 输入一样使用该组件

<x-ark-user-tagger
    name="body"
    :placeholder="trans('forms.review.create_message_length')"
    rows="5"
    wire:model="body"
    maxlength="1000"
    required
    hide-label
>{{ $body }}</x-ark-user-tagger>

此组件会向 /api/users/autocomplete 端点发送 GET 请求，查询为 q，该查询应用于搜索用户，并以下列格式返回

注意：您可以使用 endpoint 属性更改 URL。

[
    {
        "name":"Foo Bar",
        "username":"foo.bar",
        "avatar":"SVG AVATAR OR URL"
    },
    {
        "name":"Other user",
        "username":"user_name",
        "avatar":"SVG AVATAR OR URL"
    },
    ...
]

组件接受一个 usersInContext 属性，该属性期望一个用户名数组。这些用户名将在搜索查询请求中以 context 发送，并可用于在响应中首先显示这些用户。用于首先显示对话中的用户非常有用。

诱饵

安装依赖

composer require lukeraymonddowning/honey

设置诱饵

php artisan honey:install

数据库迁移

php artisan migrate

Livewire 模态框

要使用 Livewire 模态框，请在组件类中使用 ARKEcosystem\UserInterface\Http\Livewire\Concerns\HasModal 特性。该特性添加了 closeModal 和 openModal 方法，这些方法切换 modalShown 属性，您应使用此属性来显示或隐藏模态框。

重要：如果您需要使用不同的变量来关闭模态框，或者由于某种原因无法使用特性，请确保发出 modalClosed 事件，因为这是在前端正确处理模态框所必需的！如果您未发出此事件，则模态框消失后浏览器窗口将不可滚动。

Alpine 模态框

重要：为了正确工作，模态框期望在 header 元素内部使用一个 nav 元素用于头部组件。如果您使用 UI 库中的导航栏（参见 navbar.blade.php），这些元素已经使用，但对于自定义导航栏，您可能需要进行调整。

您可以通过几种方式结合 Alpine 使用新的模态框

对于仅 JS 的模态框，您需要使用 <x-ark-js-modal /> 组件。您需要使用名称（使用 name 属性）初始化模态框，可以通过调用 Livewire.emit('openModal', 'name-of-my-modal') 来打开它。

<x-ark-js-modal name="name-of-my-modal'">
    @slot('description')
        My Description
    @endslot
</x-ark-js-modal>

<button onclick="Livewire.emit('openModal', 'name-of-my-modal')">Open modal</button>

或者，如果您将模态框包裹在另一个 Alpine 组件中，您可以使用 Modal.alpine() 方法来初始化模态框（不要忘记在 x-init 上调用 init 方法）。

Modal.alpine() 方法接受一个对象作为第一个参数。该对象将与原始模态框数据合并。

在该组件内部，您可以使用 show() 方法显示模态框。

<div
    x-data="Modal.alpine({}, 'optionalNameOfTheModal')"
    x-init="init"
>
    <button type="button" @click="show">Show modal</button>

    <x-ark-js-modal
        class="w-full max-w-2xl text-left"
        title-class="header-2"
        :init="false"
    >
        @slot('description')
            My Description
        @endslot
    </x-ark-modal>
</div>

请注意，您也可以挂钩到模态框的生命周期方法。如果需要，您可以覆盖 onBeforeHide、onBeforeShow、onHidden 和 onShown 属性，使用自定义方法。

<div
    x-data="Modal.alpine({
        onHidden: () => {
            alert('The modal was hidden')
        },
        onBeforeShow: () => {
            alert('The modal is about to be shown')
        }
    }"
    x-init="init"
>
    <button type="button" @click="show">Show modal</button>

    <x-ark-js-modal
        class="w-full max-w-2xl text-left"
        title-class="header-2"
        :init="false"
    >
        @slot('description')
            My Description
        @endslot
    </x-ark-js-modal>
</div>

import Modal from "@ui/js/modal";

window.Modal = Modal;

工具提示

安装tippy.js

yarn add tippy.js

添加到 webpack mix

.js('vendor/arkecosystem/ui/resources/assets/js/tippy.js', 'public/js')

将 tippy 添加到需要它的任何页面

@push('scripts')
    <script src="{{ mix('js/tippy.js')}}" defer></script>
@endpush

滑块

安装 swiper

yarn add -D swiper

将 swiper 添加到 Laravel Mix 配置

.copy('node_modules/swiper/swiper-bundle.min.js', 'public/js/swiper.js')

将 swiper 添加到需要它的任何页面

@push('scripts')
    <script src="{{ mix('js/swiper.js')}}"></script>
@endpush

包含 swiper CSS

@import "../../node_modules/swiper/swiper-bundle.min.css";

将以下内容添加到 app.js 文件

import Slider from "@ui/js/slider";

window.Slider = Slider

日期选择器

安装 pikaday

yarn add -D pikaday

包含 pikaday CSS

@import "../../node_modules/pikaday/css/pikaday.css";
@import '../../vendor/arkecosystem/ui/resources/assets/css/_pikaday.css';

通知指示器

将此添加到您的用户迁移表中

$table->timestamp('seen_notifications_at')->nullable();

在 LivewireServiceProvider 文件中注册组件

use Domain\Components\NotificationsIndicator;
...
Livewire::component('notifications-indicator', NotificationsIndicator::class);

Prism 代码块

将 prism js 添加到 Laravel webpack mix

.js('vendor/arkecosystem/ui/resources/assets/js/prism.js', 'public/js')

将 prism 添加到需要它的任何页面

@push('scripts')
    <script src="{{ mix('js/prism.js')}}"></script>
@endpush

包含 prism CSS

@import "../vendor/ark/_prism-theme.css";

安装 prism.js

yarn add -D prism-themes prismjs

将以下片段添加到 resources/prism.js

import "../vendor/ark/prism";

document.addEventListener("DOMContentLoaded", () => {
    document
        .querySelectorAll("pre")
        .forEach((pre) => useHighlight(pre, { omitLineNumbers: false }));
});

图像集合可排序

安装 Livewire Sortable

yarn add -D livewire-sortable

将以下片段添加到您的resources/app.js

import 'livewire-sortable'
// Or.
require('livewire-sortable')

将 imagesReordered 方法添加到处理图像排序时的索引重新排序。

public function imagesReordered(array $ids): void
{
    Media::setNewOrder($ids);
}

然后，您可以使用具有可排序功能的 upload-image-collection 组件。

<x-ark-upload-image-collection id="media" :images="$this->imageCollection" sortable />

<x-ark-tabbed>
    <x-slot name="tabs">
        <x-ark-tab name="tab-1" />
        <x-ark-tab name="tab-2" />
        <x-ark-tab name="tab-3" />
    </x-slot>
    
    <x-ark-tab-panel name="tab-1">...</x-ark-tab-panel>
    <x-ark-tab-panel name="tab-2">...</x-ark-tab-panel>
    <x-ark-tab-panel name="tab-3">...</x-ark-tab-panel>
</x-ark-tabbed>

有关可用参数，请参阅 EXAMPLE.md

错误页面

您还可以使用默认错误页面为您的 Laravel 项目

运行 php artisan vendor:publish --provider="ARKEcosystem\UserInterface\UserInterfaceServiceProvider" --tag="error-pages"
将以下片段添加到 menus.php 语言文件

'error' => [
    '401' => '401 Unauthorized',
    '404' => '403 Forbidden',
    '404' => '404 Not Found',
    '419' => '419 Unauthorized',
    '429' => '429 Too Many Requests',
    '500' => '500 Internal Server Error',
    '503' => '503 Unavailable',
]

请手动访问应引发错误的 URL 以测试页面是否正常工作

可用组件

<x-ark-accordion>
<x-ark-accordion-group>
<x-ark-alert>
<x-ark-breadcrumbs>
<x-ark-checkbox>
<x-ark-clipboard>
<x-ark-dropdown>
<x-ark-expandable>
<x-ark-input>
<x-ark-navbar>
<x-ark-radio>
<x-ark-secondary-menu>
<x-ark-select>
<x-ark-sidebar-link>
<x-ark-tags>
<x-ark-textarea>
<x-ark-toggle>
<x-ark-upload-image-single>
<x-ark-upload-image-collection>
<x-ark-font-loader>
<x-ark-tabs>

有关更深入的用法示例，请参阅示例文件

Livewire 分页滚动

将以下内容添加到 app.js 文件

import "@ui/js/page-scroll";

在 Livewire 组件上使用 HasPagination 特性

use ARKEcosystem\UserInterface\Http\Livewire\Concerns\HasPagination;

class Articles {
    use HasPagination;
}

在组件模板底部添加事件触发器

<div>
    ...

    <x-ark-pagination :results="$articles" class="mt-8" />

    <script>
        window.addEventListener('livewire:load', () => window.livewire.on('pageChanged', () => scrollToQuery('#article-list')));
    </script>
</div>

分页

发布分页资源

php artisan vendor:publish --provider="ARKEcosystem\UserInterface\UserInterfaceServiceProvider" --tag="pagination"

将以下内容添加到 app.js 文件

import Pagination from "@ui/js/pagination";

window.Pagination = Pagination

全部设置完成，现在您可以使用分页组件了

<x-ark-pagination :results="$results"  />

页脚

将以下代码片段添加到您的 urls.php 语言文件中

'discord'  => 'https://discord.ark.io/',
'facebook' => 'https://facebook.ark.io/',
'github'   => 'https://github.com/ArkEcosystem',
'linkedin' => 'https://www.linkedin.com/company/ark-ecosystem',
'reddit'   => 'https://reddit.ark.io/',
'twitter'  => 'https://twitter.ark.io/',
'youtube'  => 'https://youtube.ark.io/',

可用样式

建议使用通用组件的样式，以便在整个项目中保持它们的一致性

按钮
表格
标签

进行中

更多样式，并正确配置以定义样式发布的位置

Blade 支持

头像

在 config/app.php 下的 aliases 中添加以下条目

'Avatar' => ARKEcosystem\UserInterface\Support\Avatar::class,

日期格式

在 config/app.php 下的 aliases 中添加以下条目

'DateFormat' => ARKEcosystem\UserInterface\Support\DateFormat::class,

Blade 的格式读取时间方法（通常用于博客日期/时间输出）

在 config/app.php 下的 providers 中添加以下条目

ARKEcosystem\UserInterface\Providers\FormatReadTimeServiceProvider::class,

SVG 懒加载图标

在 config/app.php 下的 providers 中添加以下条目

ARKEcosystem\UserInterface\Providers\SvgLazyServiceProvider::class,

这将启动 svgLazy 指令，并允许您从 arkecosystem/ui 包中加载图标。例如

@svgLazy('checkmark', 'w-5 h-5')

这将插入以下 HTML

<svg lazy="/icons/checkmark.svg" class="w-5 h-5" />

提示：您需要 lazy.js 才能使用此功能

开发

如果组件需要更改或您想创建额外的组件，您可以按照以下方式操作

供应商文件夹

建议使用此方法进行较小的更改测试。您可以通过运行 php artisan vendor:publish --tag=views 来发布视图，它们将显示在 views/vendor/ark 文件夹中。从那里您可以根据需要编辑它们，并且您的项目将使用这些修改后的文件。确保在修改后将其提交到此存储库，以保持项目中文件的一致性。

组件文件夹

当您创建一个 views/components 文件夹时，您可以在其中创建新的 blade 文件，它们将自动通过 <x-your-component> 在您的项目中可用。这样，您可以创建新组件、测试它们，然后在完成时将它们复制到 arkecosystem/ui 仓库。

之后，您可以将新组件添加到本地包中，并在您的项目中对其进行测试。

图标

如果您需要添加、替换或删除一个图标

将新图标移动到 /resources/assets/icons 中或从中删除
运行 yarn run generate-icon-preview
打开 icons.html 并检查图标是否存在

Tailwind 配置

组件依赖于几个 Tailwind 配置的添加（例如颜色和附加阴影），因此期望使用此存储库中的 Tailwind 配置作为基础（您可以根据需要导入和扩展它）。

arkecosystem / ui

维护者

详细信息