From 89b119a328b41a674a2d8e5b5491581cf0bc4d70 Mon Sep 17 00:00:00 2001 From: hiddenblue Date: Tue, 15 Oct 2024 21:14:20 +0800 Subject: [PATCH] zh-CN translation: Add translation for `debian ubuntu packaging` and `Setter Precedence` --- .../current/deployment/debian-ubuntu.md | 252 ++++++++++++++++++ .../styles-and-resources/setter-precedence.md | 225 ++++++++++++++++ 2 files changed, 477 insertions(+) create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/deployment/debian-ubuntu.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/styles-and-resources/setter-precedence.md diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/deployment/debian-ubuntu.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/deployment/debian-ubuntu.md new file mode 100644 index 000000000..0152eaf1d --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/deployment/debian-ubuntu.md @@ -0,0 +1,252 @@ +--- +id: debian-ubuntu +title: Debian / Ubuntu 打包 +--- + +Avalonia Linux 程序可以通过双击可执行文件或在终端中启动的方式，在大多数 Linux 发行版中运行。但是为了提供更好的用户体验，建议将程序安装到系统中，这样用户可以通过桌面快捷方式（比如在 GNOME 和 KDE 等桌面环境中）或通过命令行启动程序，前提是将程序添加到 PATH当中。 + +Debian 和 Ubuntu 等相关的发行版将其应用程序打包为 .deb 文件，这样可以通过 sudo apt install ./your_package.deb 命令进行安装。 + +## 打包教程 + +在本教程中，我们将使用 `dpkg-deb` 工具来编译你的 `.deb` 包。 + +### 1) 在暂存文件夹组织程序文件 + +Debian 包遵循以下基本结构： + +```sh +./staging_folder/ # 暂存文件夹 +├── DEBIAN +│   └── control # 包控制文件 +└── usr + ├── bin + │   └── myprogram # 启动脚本 + ├── lib + │   └── myprogram + │   ├── libHarfBuzzSharp.so # Avalonia 本地库 + │   ├── libSkiaSharp.so # Avalonia 本地库 + │   ├── other_native_library_1.so + │   ├── myprogram_executable # 主可执行文件 + │   ├── myprogram.dll + │   ├── my_other_dll.dll + │   ├── ... # 所有由 dotnet publish 生成的文件 + └── share + ├── applications + │   └── MyProgram.desktop # 桌面快捷方式文件 + ├── icons + │   └── hicolor + │   ├── ... # 其他分辨率图标（可选） + └── pixmaps + └── myprogram.png # 主应用程序图标 +``` + +每个文件夹的含义： + +* `DEBIAN`: 需要包含 `control` 文件。 +* `/usr/bin/`: 包含启动脚本(推荐用于通过命令行启动程序)。 +* `/usr/lib/myprogram/`: 所有由 `dotnet publish` 生成的文件存放的位置。 +* `/usr/share/applications/`: 存放桌面快捷方式的文件夹。 +* `/usr/share/pixmaps/` 和 `/usr/share/icons/hicolor/**`: 应用程序图标所在的文件夹。 + +:::info + +`/usr/share/icons/hicolor/**` 是可选的，即使没有这些图片，你的应用程序图标也可以显示在桌面上，但建议为更好的区分度来提供它们。 +::: + +### 2) 创建`control` 文件 + +`control` 文件放在 `DEBIAN` 文件夹中。 + +这个文件描述了程序的一般方面，如名称、版本、类别、依赖项、维护者、处理器架构和许可证。[Debian 文档](https://www.debian.org/doc/debian-policy/ch-controlfields.html) 提供了文件中所有可能字段的更详细描述。 + +:::tip[作者提示] + +不必过于担心填写所有可能的字段，大多数字段不是必需的。本教程旨在制作一个“够用就行”的 Debian 包。 +::: + +.NET 依赖项可以通过运行 `apt show dotnet-runtime-deps-8.0`（后缀根据其他 .NET 版本变化）列出；它们将出现在以 *Depends: ...* 开头的行中。你也可以在 [.NET Core 仓库](https://github.com/dotnet/core/blob/main/release-notes/8.0/linux-packages.md) 中查看它们。 + +Avalonia 所需的依赖项是：`libx11-6, libice6, libsm6, libfontconfig1`。 + +总的来说，所有 .NET 和 Avalonia 依赖项都是必需的，再加上你的应用程序特定的任何其他依赖项。 + +下面是一个简单的 `control` 文件示例。 + +``` +Package: myprogram +Version: 3.1.0 +Section: devel +Priority: optional +Architecture: amd64 +Installed-Size: 68279 +Depends: libx11-6, libice6, libsm6, libfontconfig1, ca-certificates, tzdata, libc6, libgcc1 | libgcc-s1, libgssapi-krb5-2, libstdc++6, zlib1g, libssl1.0.0 | libssl1.0.2 | libssl1.1 | libssl3, libicu | libicu74 | libicu72 | libicu71 | libicu70 | libicu69 | libicu68 | libicu67 | libicu66 | libicu65 | libicu63 | libicu60 | libicu57 | libicu55 | libicu52 +Maintainer: Ken Lee +Homepage: https://github.com/kenlee/myprogram +Description: This is MyProgram, great for doing X. +Copyright: 2022-2024 Ken Lee +``` + +### 3) 创建启动脚本 + +推荐这个步骤有两个原因：首先可以减少桌面快捷方式的复杂性，其次使你的应用程序可以从终端运行。 + +启动脚本的文件名最好是 `myprogram`（不带 `.sh` 扩展名），这样当用户在终端中输入 "myprogram" 时，他/她将启动你的程序。 + +**myprogram_executable** 文件通常与其 .NET 项目的名称相同，例如，如果你的 Avalonia .csproj 项目名为 *MyProgram.Desktop*，那么由 dotnet publish 生成的主可执行文件将是 `MyProgram.Desktop`。 + +启动脚本示例: + +```sh +#!/bin/bash + +# 使用 exec 以避免包装脚本作为一个单独的进程存在 +# "$@" 用于将命令行参数传递给应用程序 + +exec /usr/lib/myprogram/myprogram_executable "$@" +``` + +### 4) 创建桌面快捷方式 + +桌面快捷方式文件遵循 [FreeDesktop 规范](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#recognized-keys)。Arch Linux Wiki 也有一些好的[Arch Linux规范](https://wiki.archlinux.org/title/Desktop_entries)。 + +下面是一个桌面快捷方式文件的示例。 + +``` +[Desktop Entry] +Name=MyProgram +Comment=MyProgram, great for doing X +Icon=myprogram +Exec=myprogram +StartupWMClass=myprogram +Terminal=false +Type=Application +Categories=Development +GenericName=MyProgram +Keywords=keyword1; keyword2; keyword3 +``` + +:::tip + +如果你想要你的应用程序可以打开文件，请在 `Exec` 行的末尾，`myprogram` 之后附加 **%F**；如果它应该打开 URL，则附加 **%U**。 + +::: + +### 5) 添加 hicolor 图标（可选） + +Hicolor 图标遵循如下文件夹结构。 + +[这篇博客](https://martin.hoppenheit.info/blog/2016/where-to-put-application-icons-on-linux/) 建议我们根据 [Debian Menu System 文档](https://www.debian.org/doc/packaging-manuals/menu.html/ch3.html#s3.7) 和 [FreeDesktop 文档](https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-0.11.html#install_icons)，将图标放在 `hicolor` 和 `pixmaps` 目录中。 +``` +├── icons +│   └── hicolor +│   ├── 128x128 +│   │   └── apps +│   │   └── myprogram.png +│   ├── 16x16 +│   │   └── apps +│   │   └── myprogram.png +│   ├── 256x256 +│   │   └── apps +│   │   └── myprogram.png +│   ├── 32x32 +│   │   └── apps +│   │   └── myprogram.png +│   ├── 48x48 +│   │   └── apps +│   │   └── myprogram.png +│   ├── 512x512 +│   │   └── apps +│   │   └── myprogram.png +│   ├── 64x64 +│   │   └── apps +│   │   └── myprogram.png +│   └── scalable +│   └── apps +│   └── myprogram.svg +``` + +### 6) 编译 `.deb` 包 + +```sh +# 对于 x64 架构，建议的后缀是 amd64。 +dpkg-deb --root-owner-group --build ./staging_folder/ "./myprogram_${versionName}_amd64.deb" +``` + +## 完整的 Linux shell 脚本示例 + +```bash +#!/bin/bash + +# 清理 +rm -rf ./out/ +rm -rf ./staging_folder/ + +# .NET 发布 +# 推荐使用 self-contained 发布，这样用户不需要安装 .NET运行时 +dotnet publish "./src/MyProgram.Desktop/MyProgram.Desktop.csproj" \ + --verbosity quiet \ + --nologo \ + --configuration Release \ + --self-contained true \ + --runtime linux-x64 \ + --output "./out/linux-x64" + +# 暂存目录 +mkdir staging_folder + +# Debian control文件 +mkdir ./staging_folder/DEBIAN +cp ./src/MyProgram.Desktop.Debian/control ./staging_folder/DEBIAN + +# 启动脚本 +mkdir ./staging_folder/usr +mkdir ./staging_folder/usr/bin +cp ./src/MyProgram.Desktop.Debian/myprogram.sh ./staging_folder/usr/bin/myprogram +chmod +x ./staging_folder/usr/bin/myprogram # 设置启动脚本的执行权限 + +# 其他文件 +mkdir ./staging_folder/usr/lib +mkdir ./staging_folder/usr/lib/myprogram +cp -f -a ./out/linux-x64/. ./staging_folder/usr/lib/myprogram/ # 从publish目录复制所有文件 +chmod -R a+rX ./staging_folder/usr/lib/myprogram/ # 设置所有文件的读权限 +chmod +x ./staging_folder/usr/lib/myprogram/myprogram_executable # 设置主可执行文件的执行权限 + +# 桌面快捷方式 +mkdir ./staging_folder/usr/share +mkdir ./staging_folder/usr/share/applications +cp ./src/MyProgram.Desktop.Debian/MyProgram.desktop ./staging_folder/usr/share/applications/MyProgram.desktop + +# 桌面图标 +# 一个 1024px x 1024px 的 PNG 文件，类似于 VS Code 使用的图标 +mkdir ./staging_folder/usr/share/pixmaps +cp ./src/MyProgram.Desktop.Debian/myprogram_icon_1024px.png ./staging_folder/usr/share/pixmaps/myprogram.png + +# Hicolor 图标 +mkdir ./staging_folder/usr/share/icons +mkdir ./staging_folder/usr/share/icons/hicolor +mkdir ./staging_folder/usr/share/icons/hicolor/scalable +mkdir ./staging_folder/usr/share/icons/hicolor/scalable/apps +cp ./misc/myprogram_logo.svg ./staging_folder/usr/share/icons/hicolor/scalable/apps/myprogram.svg + +# 制作 .deb 文件 +dpkg-deb --root-owner-group --build ./staging_folder/ ./myprogram_3.1.0_amd64.deb +``` + +## 安装 + +```sh +sudo apt install ./myprogram_3.1.0_amd64.deb +``` + +## 卸载 / 删除 + +```sh +sudo apt remove myprogram +``` + +## 第三方打包工具（适用于 Debian / Ubuntu） + +* https://github.com/quamotion/dotnet-packaging +* https://github.com/SuperJMN/DotnetPackaging +* https://github.com/kuip \ No newline at end of file diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/styles-and-resources/setter-precedence.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/styles-and-resources/setter-precedence.md new file mode 100644 index 000000000..a89ffefac --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/styles-and-resources/setter-precedence.md @@ -0,0 +1,225 @@ +--- +id: setter-precedence +title: 设置器优先级 +--- + +import SetterPrecedenceAnimationWrongScreenshot from '/img/guides/styles-and-resources/setter-precedence-animation-wrong.gif'; +import SetterPrecedenceAnimationCorrectScreenshot from '/img/guides/styles-and-resources/setter-precedence-animation-correct.gif'; + +Avalonia 的 `Setter` 按照 `BindingPriority`、视觉树局部性和样式集合顺序依次应用。每个 `StyledProperty` 都单独应用优先级，从而使得样式可以受益于组合。`DirectProperty` 和 CLR 属性不能被样式化，因此不参与此优先级。 +## 绑定优先级 + +```cs +Animation = -1, // 最高优先级 +LocalValue = 0, +StyleTrigger, +Template, +Style, +Inherited, +Unset = int.MaxValue, // 最低优先级 +``` + +## 如何在XAML中分配绑定优先级？ + +`BindingPriority` 不能在 XAML 中显式设置。以下示例展示了如何在每个场景中隐式分配 `绑定优先级`。这对于设计和排除样式故障至关重要，以确保样式按预期工作。 + +### Animation + +`Animation` 具有最高的 `绑定优先级`，并应用于 `Keyframe` 中的 `Setter`，通常在整个过渡系统中应用。 + +```xml + +``` + +### LocalValue + +当 XAML 属性在 `ControlTemplate` 之外直接设置时分配。下面的两个 `Background` `Setter` 都将具有 `LocalValue` 优先级。 + +```xml + +``` + +