Surface

Surface 是一个服务端渲染组件库，能让开发者编写少量自定义 JavaScript 即可构建丰富的交互式用户界面。

Surface 构建于 Phoenix LiveView 及其组件 API 之上，充分利用出色的 Phoenix 框架，为构建现代 Web 应用提供了快速且高效的解决方案。

完整文档和在线示例可访问 surface-ui.org。

示例

# Defining the component

defmodule Hello do
  use Surface.Component

  @doc "Someone to say hello to"
  prop name, :string, required: true

  def render(assigns) do
    ~F"""
    Hello, {@name}!
    """
  end
end

# Using the component

defmodule Example do
  use Surface.Component

  def render(assigns) do
    ~F"""
    <Hello name="John Doe"/>
    """
  end
end

特性

• 以 HTML 为中心的模板语言，专为提升开发体验而设计。

• 组件即模块——它们可以是无状态的、有状态的、无渲染的或编译时的。

• 声明式属性——显式声明每个组件的输入（属性和事件）。

• 插槽（Slots）——由组件声明的占位符，您可以用自定义内容填充。

• 上下文（Contexts）——允许父组件与其子组件共享数据，而无需将数据作为属性传递。

• 编译时检查模板结构、组件属性、插槽、事件等。

• 与编辑器/工具集成，支持警告/错误提示、语法高亮、跳转到定义、自动补全（即将推出！）等功能。

安装

Phoenix v1.7 内置支持 LiveView 应用。您可以使用以下命令创建一个新的 phoenix 应用：

mix phx.new my_app

注意： 如果你想将 Surface 添加到一个尚未正确安装 LiveView 的现有 Phoenix 应用中，请参阅 Phoenix LiveView 的安装说明，网址为 hexdocs.pm/phoenix_live_view/installation.html。

在 mix.exs 的依赖项列表中添加 surface：

def deps do
  [
    {:surface, "~> 0.12.0"}
  ]
end

使用 mix surface.init 配置项目

使用 mix deps.get 获取依赖后，你可以运行 surface.init 任务来更新项目中必要的文件。

如果你希望该任务同时为你生成一个示例组件，可以使用 --demo 选项。使用该组件的 liveview 将可在 /demo 路由访问。

此外，该任务还可以使用 --catalogue 选项为你的项目设置 Surface Catalogue。该目录将可在 /catalogue 访问。

注意： 当同时使用 --demo 和 --catalogue 选项时，该任务还会为示例组件生成两个目录示例和一个 playground。

mix surface.init --demo --catalogue

使用以下命令启动 Phoenix 服务器：

mix phx.server

就是这样！现在你可以通过 http://localhost:4000 访问你的应用程序了。

你可以通过运行以下命令查看 surface.init 提供的所有选项：

mix help surface.init

如需了解更多安装相关信息，包括如何手动安装 Surface，请访问 快速开始 指南。

从旧版本迁移

有关详细信息，请参阅 迁移指南。

工具

• Surface Formatter - Surface 的代码格式化工具。
• VS Code 的 Surface 扩展包 - 为 Surface/Elixir 提供语法高亮支持。

许可证

版权所有 (c) 2020，Marlus Saraiva。

Surface 源代码采用 MIT 许可证 授权。