Y—Tags
适用于 iOS 的可访问且可自定义的标签用户界面元素。

此框架包含标签组件(有时称为药丸),它们是完全可自定义的,并支持动态类型和辅助功能粗体文本特性(标签边框也会随着文本一起变为粗体)。默认外观支持深色模式,并符合 WCAG 2.00 AAA 标准(当指定自定义颜色时,由调用者提供对深色和增加对比度模式的支持)。

Y—Tags demo animation

许可

Y—Tags 遵循 Apache 2.0 许可

文档

文档从源代码注释自动生成,并呈现为一个静态网站,托管在 GitHub Pages 上:https://yml-org.github.io/ytags-ios/

用法

Tag view Components

初始化器

标签视图可以使用标题和一个外观(可选)进行初始化。外观参数允许您完全自定义标签(包括是否包含前导图标和/或尾随关闭按钮)。您也可以随时更新标签的外观。

public init(
    title: String,
    appearance: TagView.Appearance = .default
)

简单用例 1:仅包含文本的标签,使用默认外观。

let tagView = TagView(title: "Hello World!!")

简单用例 2:仅包含文本的标签,使用自定义外观。

let tagView = TagView(
    title: "Hello world!",
    appearance: TagView.Appearance(
        backgroundColor: .blue,
        borderColor: .black,
        shape: .rectangle
    )
)

简单用例 3:带有图标的标签。

let tagView = TagView(
    title: "Hello world!",
    appearance: TagView.Appearance(
        icon: TagView.Appearance.LeadingIcon(image: cube)
    )
)

简单用例 4:带有关闭按钮的标签。

let tagView = TagView(
    title: "Hello world!",
    appearance: TagView.Appearance(
        closeButton: TagView.Appearance.CloseButton()
    )
)

自定义

TagView 具有一个 appearance 属性,类型为 Appearance

Appearance 允许您自定义标签视图的外观。 我们可以自定义边框颜色、前导图标、关闭图标、背景颜色等外观。

public struct Appearance {
    /// A tuple consisting of `textColor` and `typography` for the title label.
    /// Default is `(.label, .systemLabel)`.
    public var title: (textColor: UIColor, typography: Typography)
    /// Tag view background color. Default is `.clear`.
    public var backgroundColor: UIColor
    /// Border color. Default is `.label`.
    public var borderColor: UIColor
    /// border width. Default is `1`.
    public var borderWidth: CGFloat
    /// Leading icon appearance. Default is 'nil` (no leading icon).
    public var icon: LeadingIcon?
    /// Close button appearance. Default is 'nil` (no close button).
    public var closeButton: CloseButton?
    /// Tag view layout properties such as spacing between views. Default is `.default`.
    public var layout: Layout
    /// Tag shape. Default is `.capsule`.
    public var shape: Shape
    /// Whether a leading icon is present or not.
    var hasIcon: Bool { icon != nil }
    /// Whether a close button is present or not.
    var hasCloseButton: Bool { closeButton != nil }
}

更新或自定义外观

// Declare a tag view.
let tagView = TagView(title: "Hello World!!")

// Change background color, border color, shape, text color, and typography.
tagView.appearance.backgroundColor = .red
tagView.appearance.borderColor = .black
tagView.appearance.shape = .rectangle
tagView.appearance.title =  (.secondaryLabel, .smallSystem)

依赖项

Y—Tags 依赖于我们的 Y—CoreUIY—MatterType 框架(两者也都是开源的,并采用 Apache 2.0 许可)。

安装

您可以通过将其添加为软件包依赖项来将 Y—Tags 添加到 Xcode 项目中。

  1. 文件菜单中,选择添加软件包...
  2. 在软件包存储库 URL 文本字段中输入 "https://github.com/yml-org/ytags-ios"
  3. 点击添加软件包

为 Y—Tags 做出贡献

要求

SwiftLint (linter)

brew install swiftlint

Jazzy (文档)

sudo gem install jazzy

设置

克隆存储库并在 Xcode 中打开 Package.swift

版本控制策略

我们使用 语义版本控制

{major}.{minor}.{patch}

例如。

1.0.5

分支策略

我们为我们的框架使用简化的分支策略。

分支命名约定

feature/{ticket-number}-{short-description}
bugfix/{ticket-number}-{short-description}

例如。

feature/CM-44-button
bugfix/CM-236-textview-color

拉取请求

在提交拉取请求之前,您应该

  1. 编译并确保没有警告和错误。
  2. 运行所有单元测试并确认一切通过。
  3. 检查单元测试覆盖率并确认所有新的/修改的代码都已完全覆盖。
  4. 从命令行运行 swiftlint 并确认没有违规。
  5. 从命令行运行 jazzy 并确认您拥有 100% 的文档覆盖率。
  6. 考虑使用 git rebase -i HEAD~{commit-count} 将您最后的 {commit-count} 个提交合并成功能块。
  7. 如果父分支(通常是 main)的 HEAD 在您创建分支后已更新,请使用 git rebase main 重新设置您的分支。
    • 永远不要将父分支合并到您的分支中。
    • 始终根据父分支重新设置您的分支。

提交拉取请求时

合并拉取请求时

发布新版本

生成文档(通过 Jazzy)

您可以使用以下来自终端的命令,直接从源代码生成您自己的本地文档集

jazzy

这会在 /docs 下生成一组文档。默认配置在默认配置文件 .jazzy.yaml 文件中设置。

要查看其他文档选项,请键入

jazzy --help

每次将提交推送到 main 时,GitHub Action 都会自动运行,该操作运行 Jazzy 以生成我们 GitHub 页面上的文档:https://yml-org.github.io/ytags-ios/